JSON Methods

I'll preface it by saying that there are 4 parameters that all API requests require - 'version', 'url', 'api_key', 'api_secret'. If those parameters aren't given, you still get access, but AdaptCMS automatically handles those for you. We also are using the url parameter 'v1', which is the version of the API - currently Version 1. In the future this will change and we will update these docs to support that.

Version Check

/v1/version-check?version=param
To do a simple version check, the version is entered in and returned back is the version information if it is a valid one, an error message if not. By default, this is all it does, AdaptCMS in a helper takes that data and checks to see if the 'current_version' parameter is set to 1, if not, then it displays an appropiate message.

Plugin/Theme Version Check

/v1/(plugin|theme)-version-check?ids=api_id1,api_id2
This is another version check, but for plugins and themes. Plugin/Theme ID's are passed in, separated by a comma. If the ID's are not found, an error is returned, otherwise an array of the data is returned. This is also used by the API Helper on the Admin Tools Plugin page - which checks to make sure plugins installed are up to date. As well, on the main appearance page in the admin for themes.

Get Key

/v1/key
The Get Key method generates a new API Key/Secret and passes it back to the client. Version and URL are mandatory, otherwise an error is returned. It first looks to see if the website already has a key and returns that one instead of creating a new one, if found.

AdaptCMS.com Content

/v1/site-(news|blog)/limit_amount
Used on the main admin page, this method retrieves the latest content from the official AdaptCMS.com website. You can either enter 'news' or 'blog' as the category and a numeric limit amount. Returned is an array of the article data sorted descending by the created date.

Get Plugins/Themes

/v1/(plugins|themes)?sort_by=optional&sort_dir=optional2&limit=optional3
One of the main methods, get plugins/themes retrieves plugins or themes in an array of data. Optionally, you can provide a sort_by (title, slug, views, downloads, created, modified), sort_dir (sort direction - asc, desc) and numeric limit of how many to display. If all three aren't provided, then the most viewed 10 Plugins/Themes are returned.

Get Specific Plugin/Theme

/v1/(plugin|theme)/{id}
A JSON Encoded array of Plugin/Theme data is returned if the ID entered here exists in the database, otherwise a message error is returned.

Plugins

Plugins are made to extend the functionality of AdaptCMS. We plan on making a considerable amount of plugins ourselves, but we need developers to help out too. Below is everything you need to know on how to make plugins for adaptcms.

How to make a Plugin

First, please read over the official "How To" for making a plugin in cakePHP - check it out. That page goes over configuration and initial setting up a plugin and the basics of cakePHP in general, check out controllers and models.

That said, the very basic setup of a new plugin in AdaptCMS is creating a folder in

/app/Plugin

Then create a file in the base of your folder which will contain the base configuration of your plugin:

plugin.json

Read below on how to configure that file. But after that it's kind of your sandbox to play in. You'll want a Controller and likely model setup, Views and you can setup a folder in:

/app/Plugin/YourPlugin/webroot

You can put in js, css files - files that are publicly available. The AdaptCMS JS/CSS Autoloader will look at this location and you can enter in a 'global.js' file, for example, and it will be called on every frontend file. (perfect for dynamic blocks that could be used anywhere and require js for your plugin to work)

Plugin JSON Configuration

First up, here's the bare bones example of a plugin.json file:

{
    "title": "YourPlugin"
}
And a more complete version:
{
    "title": "YourPlugin",
    "current_version": "0.7",
    "api_id": 1,
    "install": {
        "module_active": 1,
        "model_title": "Poll",
        "permissions": {
            "file": "Install/permissions.php",
            "className": "PermissionsInstall",
            "functionName": "generate"
        },
        "text": "Install/install_text.md",
        "sql": [
            "Install/install_data.sql"
        ]
    },
    "uninstall": {
        "text": "Install/uninstall_text.md",
        "sql": [
            "Install/uninstall_data.sql"
        ]
    },
    "upgrade": {
        "1.0": {             "text": "Install/upgrade_1-0_text.md",
            "sql": [
                "Install/upgrade_1-0.sql"
            ]
        }     }
}

  • title - Name of your plugin. If it is on the official site or you want it to be, please use an unused name.
  • current_version - Current version, if you don't really do versioning, just enter 1.0 to have something.
  • api_id - This is your API ID from the AdaptCMS API Website. After your plugin has been approved you will receive this number. Contact us anytime if you lost it and we will re-send it.

install

  • block_active - (0 or 1) - This number represents if your plugin can be used with the Dynamic Data feature of Blocks, which also requires the next setting be entered. If you wish it to be disabled, don't even put this in.
  • model_title - This is used for multiple things. In order for your plugin to use blocks, this must be set. If your plugin intends on using the {module_id} variable in install/uninstall/upgrade sql it must be set. Also, if you wish to use the plugin settings callback (called after that plugins settings have been saved successfully) this also must be set. In general, if you have a model file, I would recommend using this.
  • permissions - To setup default permissions, we highly recommend you setup a permission installer. Examples can be seen in AdaptBB, Polls and Links. The script sends your specified file/class/function a list of roles and a module ID, from there you set actions to be setup in the database.
  • text - Location of an installation text file, relative to the directory of the plugin. It will be displayed when a user installs your plugin.
  • sql - Either leave this setting out of the file or enter in an array of SQL files that will be executed on install. (path is from root of your plugin folder)

uninstall

  • text - Location of an un-installation text file, relative to the directory of the plugin. It will be displayed when a user un-installs your plugin.
  • sql - Either leave this setting out of the file or enter in an array of SQL files that will be executed on un-install. (path is from root of your plugin folder)

upgrade

  • NEW IN 3.0.1 1.0 - An example version, simply enter in a previous version to upgrade from and inside that, text/sql to show up.
  • text - Location of an upgrade text file, relative to the directory of the plugin. It will be displayed when a user upgrades your plugin.
  • sql - Either leave this setting out of the file or enter in an array of SQL files that will be executed on upgrade. (path is from root of your plugin folder)

Plugin Settings & Configuration

You can also configure your Plugin. You can set custom routing and setup a configuration file of settings that CMS users can change, this is really great for API's - requiring the user to enter their API info in order to use it. Simply setup:

Config/config.php

In your plugin root folder. Here is an example below on how it is done:

$params = '{"html_tags_allowed":"<strong>,<a>,<p>,<br>","num_posts_per_page_topic": 10,"num_topics_per_page_forum":5,"num_posts_hot_topic":10}';

This is for the AdaptBB configuration, if the item has a menu item then you need to merge the parameter arrays and decode the json. Keep in mind anything in the system_config variable (for example) is written to the Plugin configuration, but is separate of the normal params - meaning you can have have core config only accessible by the application.

$config = json_decode($params, true);
Configure::write('PluginName', array_merge($config, $system_config) );

Menu Item

For your plugin to appear under 'Plugins' in the admin area, you must set an admin_menu array containing the plugin name, controller and action - optionally, you can set a custom label or else the plugin name is used.

Routing

As mentioned, checkout the cake page for details on how to do routing. But for them to be used, simply create the following file in your base folder:

Config/routes.php

Assets

Another recent addition is assets, this is images, css, js, etc. that is pulled from the below folder and is editable through the manage plugins area.

webroot/

Themes

Themes come in two flavors - a theme with layout/templates and theme with data to install. Some themes are only for asthetic purposes and others are fully featured themes with new design and categories/fields setup. Read below to find out how to create a theme.

How to make a Theme

First, we recommend reading the official docs on themes at cakephp.org. This will explain where your Theme will go, where asset files are managed and more.

That said, the very basic setup of a new theme in AdaptCMS is creating a folder in

/app/View/Old_Themed

Then create a file in the base of your folder which will contain the base configuration of your theme:

theme.json

Read below on how to configure that file. But after that it's kind of your sandbox to play in. You may want to create it in the 'Old' folder so you can insert in any sql files or whichever, then can run the install fresh. For asset files you can setup a folder in:

/app/webroot/themes/YourTheme

Theme Configuration

First up, here's the bare bones example of a theme.json file:

{
    "title": "YourTheme"
}
And a more complete version:
{
    "title": "YourTheme",
    "current_version": "0.7",
    "api_id": 1,
    "install": {
        "text": "Install/install_text.md",
        "afterInstallFilter": {
            "file": "Install/install.php",
            "className": "InstallFilters",
            "functionName": "afterInstallFilter"
        },
        "sql": [
            "Install/install_data.sql"
        ]
    },
    "uninstall": {
        "text": "Install/uninstall_text.md",
        "sql": [
            "Install/uninstall_data.sql"
        ]
    },
    "upgrade": {
        "1.0": {             "text": "Install/upgrade_1-0_text.md",
            "sql": [
                "Install/upgrade_1-0.sql"
            ]
        }     }
}

  • title - Name of your theme. If it is on the official site or you want it to be, please use an unused name.
  • current_version - Current version, if you don't really do versioning, just enter 1.0 to have something.
  • api_id - This is your API ID from the AdaptCMS API Website. After your theme has been approved you will receive this number. Contact us anytime if you lost it and we will re-send it.

install

  • text - Location of an installation text file, relative to the directory of the theme. It will be displayed when a user installs your theme.
  • afterInstallFilter - This custom functionality is used to insert custom data into the database. Example useage is the Gaming theme, which adds - categories, fields, articles and article data. The installer loops through the array looking for data passed to it and creates it if necessary. The array must look like this:

    • Categories > CategoryName -> title = CategoryName
    • Categories > CategoryName -> Field = array which must have keys - title, field_type and optionally - description, field_options
    • Categories -> CategoryName -> Article = array containing arrays of articles to insert, needing to contain the key/values of 'title' at minimum and can also have tags as well as ArticleValue, explained below...
    • Categories -> CategoryName -> Article -> array -> ArticleValue = an array containing arrays of article data to insert into database, field_name (previously mentioned above) and data.

  • sql - Either leave this setting out of the file or enter in an array of SQL files that will be executed on install. (path is from root of your theme folder)

uninstall

  • text - Location of an un-installation text file, relative to the directory of the theme. It will be displayed when a user un-installs your theme.
  • sql - Either leave this setting out of the file or enter in an array of SQL files that will be executed on un-install. (path is from root of your theme folder)

upgrade

  • NEW IN 3.0.1 1.0 - An example version, simply enter in a previous version to upgrade from and inside that, text/sql to show up.
  • text - Location of an upgrade text file, relative to the directory of the theme. It will be displayed when a user upgrades your theme.
  • sql - Either leave this setting out of the file or enter in an array of SQL files that will be executed on upgrade. (path is from root of your theme folder)