Extension definition

The extension definition is a JSON file that declares information, configurations, bindings and user permissions of a plugin. The file must reside in the root folder of the extension and must have the following format as the filename:

  extension_code.plugin

Important note: a single syntax error in the JSON file will make the extension unusable for Navigate CMS.

The global structure of the file is:

{
    "title": "Demo",
    "version": "1.0",
    "author": "Naviwebs <info@naviwebs.com>",
    "website": "http://www.naviwebs.com",
    "description": "extension_description",
    "type": "extension_type",
    "run": false,
    "languages": {},
    "options": [],
    "bindings": [],
    "permissions":[]
}

The "type" field is used only for categorization when browsing the installed extensions in Navigate CMS. It determines the primary function of the extension, which can be (as of Navigate CMS 1.7):

≈ website - called usually when viewing a website

≈ admin - called when using Navigate CMS functions

≈ translate - translate service (must implement some internal functions)

"run" field declares if the extension is runnable like a Navigate CMS function (IFrame application).

Languages

If the extension generates HTML code for a website you may be interested in displaying texts in other languages. The translations may also be used when editing the extension configuration options in Navigate CMS.

The language codes are defined in the website configuration. We recommend using the 2-letters identifier for a language (ISO 639-1).

"languages":
{
    "language_code": "path to json dictionary from THEME ROOT",
    "en": "i18n/en.json"
}

All texts (descriptions, option titles and values...) can be translated using the extension dictionary. For example, given an extension that has an option to choose a scheme color,  the value "ec_blue" will be replaced for a string matching that code in the current language ("Electric Blue" in English, "Azul eléctrico" in Spanish) and show it in the application instead of "ec_blue", otherwise the default language will be used.

You can also put a "@" symbol before the string code to aid you identifying what will be checked against the dictionary (the symbol is not used for anything, it will be removed before checking the dictionary).

The dictionary is a JSON file like this:

{
    "string_code": "String translation",
    "color_scheme": "Color scheme",
    "dark": "Dark",
    "light": "Light",
    "soft": "Soft",
    "default": "Default"
}

Options

An extension may have configuration options, for example: color scheme, api key value, etc...

"options":
[
    {
        "id": "service_api_key",
        "name": "Service API Key",
        "type": "value"
    },
    {
        "id": "color_scheme",
        "name": "@color_scheme",
        "type": "option",
        "options": 
        {
            "default": "@default",
            "dark": "@dark",
            "light": "@light",
            "soft": "@soft"
        },
        "dvalue": "dark"
]

You can see the use of the @ character to identify strings located in the extension dictionary. You'll get each user-entered value asking Navigate CMS for the extension name and the "id" of the option to retrieve. Take a look at the examples on every extension type.

Check Themes > Configuration and options section to get a full list of option types and its custom properties.

Bindings

The bindings section is useful when your extension needs to execute an action when certain events happen. For example, each time a new comment is inserted your extension may check if it's spam or auto remove links...

For each event you need to define the "module" (function in Navigate CMS), "event" and "function" (the callback function that you want to be executed).

"bindings":
[
    {
        "module": "comments",
        "event": "after_insert",
        "function": "nvweb_your_extension_analyze_comment"
    },
    {
        "module": "comments",
        "event": "edit",
        "function": "nvweb_your_extension_tab"
    }
]

You can find the full list of available events and parameters here.

Permissions

Every extension can add their own set of permissions, so the website administrator can allow certain functions to Navigate CMS users. For example, if the extension adds a tab to a function, the administrator can decide he'll be the only one who can view it.

"permissions":
[
    {
        "name": "permission name following a dot separated categorization",
        "scope": "type of the permission, here always extensions",
        "function": "name of the function related to the permission",
        "description": "text describing the permission",
        "type": "field type of the permission - boolean, integer, string",
        "dvalue": "default value"
    },
    {
        "name": "extensions.akismet_antispam.display_tab",
        "scope": "extensions",
        "function": "akismet_antispam",
        "description": "Display Akismet tab on comments form",
        "type": "boolean",
        "dvalue": "true"
    }
]

Extensions in Navigate CMS is an always expanding feature, so try to keep up-to-date of every new developments.

0 Comments