Services

Module.json file

module.json is a JSON file that contains all the information Includable needs about your module. It needs to exist in the root folder of your module. Look for an example at the bottom of this page.

JSON fields

Module slug

The module slug basically sets the path to the module. If your community name is mysite and your module slug is todo, the URL with which you can access your module would be:

http://mysite.includable.com/todo

The module slug may only consist of lowercase letters, numbers and undescores. It's length should be between 3 and 20 characters and should not be one of these words that are used by Includable itself:

home
user
login
logout
password
uploadhandler
settings

Remember that the Community Manager is able to chance the slug for the module on their site, so never hardcode it, but rather use the $this->module->slug or $this->request->base_url PHP variable in your code.

Module settings

The settings a user can change for a particular module. Retrievable via the PHP $this->settings method.

Types:

text – A simple one-line text input
textarea – A multiline text input
Number – A numeric input, you can set the keys min and max
checkbox – A checkbox for toggling a setting
radio – Choose for multiple options (radio button)
header – Text header for setting subcategories, text can be set using key text
link – A link to Manager page

Controllers

Controllers route requests from different sources to the right PHP files.

Default controllers:

web: The default web interface
api: API methods of your module
manager: Interface for adminstrator
post-install: Script that will be executed after installation (prepare for use)
pre-uninstall: Script that will be executed before removal (clean up)

Example

An example module.json could look like this:

module.json

{
    "slug": "courses",

    "title": "Courses",
    "description": "Share lesson materials and information with your students.",

    "version": "2.0",
    "author": {
        "name": "Includable",
        "www": "https://www.includable.com/",
        "email": "support@includable.com"
    },

    "controllers": {
        "web": "web/index.php",
        "manager": "manager/index.php",
        "api": "api/index.php"
    },

    "webOptions": {
        "staticPaths": [
            "web/scripts.js",
            "web/styles.css"
        ]
    },

    "apiMethods": {
        "courses": "list_courses",
        "courses/all": "list_courses_all",
        "courses/:id": "course_info",
        "courses/:id/members": "course_members",
        "courses/:id/members/flat": "course_members_flat",
        "courses/:id/files": "course_files",
        "courses/:id/files/categories": "course_files_categories",
        "courses/:id/lessons": "course_lessons"
    }
}

Reference

This is an overview of all the possible object keys in module.json. Everywhere where there is a dot in the left column of this table, it means that it contains a key that is part of an object.

Key Type Description

controllers

object

Contains the controllers that the module supplies.

Key	Type	Description
`controllers.web`	string	Path to the .php or .html file that is shown on the web version of a community that has this module installed.
`controllers.api`	string	Path to the .php file that contains the API functions.
`controllers.<controller_name>`	string	Path to the .php or .html file used for a particular controller or hook.

apiMethods object A list of API methods with their respective function names.

webOptions

object

Options that allow you to change the appearance and function of the web controller:

Key	Type	Description
`webOptions.angular`	bool	Whether to enable AngularJS for the current module. Defaults to false.
`webOptions.angularAppName`	string	Value for the `ng-app` attribute that is added to the <html> tag when AngularJS support is enabled.
`webOptions.headerFile`	string	Path to a .html file in the module directory that contains HTML that needs to be added before </head> tag of the page. Note: this content is not parsed as PHP, so PHP variables and other PHP code will not be processed. When you need dynamic header inserts, use the `site-header` hook.
`webOptions.publicPaths`	array	The URL paths that should be available without the need to sign in to see them. These should not include a leading (or trailing) slash, with the exception of the value ‘/’, denoting the homepage of the module. Can use wildcards in the form of `*`.
`webOptions.staticPaths`	`array`	Contains a list of paths to use as a static asset within the web interface for this module. Can use wildcards in the form of `*`.
`webOptions.inlineResources`	object	An object of arrays, with the following possible keys: `before` and `after`. This can be used to automatically insert contents of a Javascript or CSS file into the page HTML upon loading, either before or after the content. Example: `{ ... "webOptions": { "inlineResources": { "before": [ "web/styles.css" ], "after": [ "web/scripts.js" ] }, ... }`

requires Object: this can be used though to specify a required PHP version or <module dependencies>. Look at the <Composer reference> for the format of this object.

settings Array: the available configuration options for the Community Manager.

managerTitle String: title of the menu item in Community Manager when a manager controller is defined. Defaults to the name of the Module.

managerLinks Object: contains the slugs and titles of the menu items that should be shown in the Community Manager menu. When this object is not empty, the managerTitle is used as the title of a submenu containing the links defined in this object instead of a single menu item for the module.

manager_tab_name String: the name of the tab shown in a user profile in the Community Manager when the hook manager-user is defined. Defaults to the name of the Module.