Includable Documentation

  • 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:

{ ... &quot;webOptions&quot;: { &quot;inlineResources&quot;: { &quot;before&quot;: [ &quot;web/styles.css&quot; ], &quot;after&quot;: [ &quot;web/scripts.js&quot; ] }, ... }
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.
Suggest a change