InstantCMS 2 uses the mechanism of packages to install extensions (components, widgets, templates, patches and so on) and updates. A package consists of certain structure zip-archived files. The file can have the zip or icp extension.

The packages can be of several types according to which the CMS performs certain actions.

Such package implies that the component installation process will be performed. In other words, it is assumed that the component has not been installed before. With this type of package, the CMS fills the cms_controllers table itself.

Such package is assumed to contain only the previous version update files. You can install the package only if the updatable component has already been installed. The installer will automatically increase the component version and update the option array in the cms_controllers table.

This package implies that the installable extension is a widget. The CMS will itself add an entry to the cms_widget table on the basis of the manifest file.

The algorithm of actions is similar to the component update package, the only difference being that the cms_widgets table is used to edit the data.

The engine will recognize such package if the [install] or [update] blocks are missing in the manifest file (see below). When installing such a package, the CMS will perform nothing in respect of automatic entry adding to the cms_controllers and cms_widgets tables. In this case, the extension developer should take care of it.

Inside the archive, the file tree view is generally the following:

The tree must have:

• manifest.LANGUAGE.ini file

The following files are optional in the archive:

• package folder;
• install.sql file;
• icon.png file;
• install.php file;
• the manifest.LANGUAGE.ini files in languages other than Russian.

The structure of the package folder fully coinsides with the folder structure on the site. Hence, the entire folder structure of your component is copied to it, as it is on the site, starting from its root.

The file should be located in the archive root and have the title spesified in the manifest file. There are no restrictions on the file type and its size. However, you should certainly take into account that huge photos will distract the appearance of the package info page.

This file contains the description of all required sql requests that fill tables or create new ones for your extension. In sql requests, the table prefix should be substituted by the {#} symbol. For example, if an original request has the following view:

INSERT INTO `cms_controllers` (`title`, `name`, `is_enabled`, `options`, `author`, `url`, `version`, `is_backend`) VALUES
('Open Graph protocol', 'opengraph', 1, '---\nenabled_ctypes:\nis_https_available: null\ndefault_image:\n', 'InstantMedia Team', 'http://www.instantmedia.ru/', '1.1.0', 1);

then, in this file, the request should have the following view:

INSERT INTO `{#}controllers` (`title`, `name`, `is_enabled`, `options`, `author`, `url`, `version`, `is_backend`) VALUES
('Open Graph protocol', 'opengraph', 1, '---\nenabled_ctypes:\nis_https_available: null\ndefault_image:\n', 'InstantMedia Team', 'http://www.instantmedia.ru/', '1.1.0', 1);

Please note that in this file, in InstantCMS versions higher than 2.3.0, there is no need to write sql requests that add entries to the cms_widgets and cms_controllers tables; it will be enough if you specify the extension type in the manifest file. When installing an extension, the engine will itself add proper entries to these tables on the basis of the data specified in the manifest file and will futher automatically monitor the version when installing update packages.

The install_package function without arguments should be defined in this file. Inside the function, you can perform any actions by requesting proper objects of system classes. Surely, you can create any number of custom functions in this file and request them from the install_package function. The install_package function should return:

• if everything specified in it has been successfully performed;
• if an error occurred when executing the code;
• an error text that will be displayed to a user when installing an extension

In case of the false response or an error text, the engine will not add entries to the cms_widgets and cms_controllers tables and the extension will be considered as not installed.

Additionally, the function called «after_install_package», which is requested when an extension has already been successfully installed, can be defined in this file. This function is optional.

This file has a common ini file syntax, for example, like php.ini. The file title should have the following structure:

manifest.{language name}.ini

In other words, you can create a custom manifest file for each of them depending on the languages your extension supports. The manifest.ru.ini file will be used by default. For example, for English localization, the file title will be manifest.en.ini.

You can indicate the following blocks in the file:

• [info]
• [version]
• [depends]
• [author]
• [description]

in case of a typified package too:

• [install] or
• [update]

This block is mandatory

title = "your extension title, not more than 64 symbols"
image = "an extension icon title along with the file extension, for example, icon.png"

This block is mandatory

major = "the first number of the version"
minor = "the second number of the version"
build = "the third number of the version"
date  = "extension release date, for example, 20161231"

This block is optional

core = "an InstantCMS version older which the extension will not work"
package = "an already installed extension’s version"

for example,

core = "2.4.0"
package = "1.5.7"

The package option is required only if the package is of the «component update» or «widget update» type. If it is specified, the update will not be installed, provided that an already installed extension’s version is older than the one specified here. It is useful to know for sure that the update, for example, under 2.0.5 should necessarily be installed over version 2.0.4.

Parameters that are supported starting from InstantCMS version 2.6.0.

dependent_type = "an extension type on which the installable depends and which should be already installed"
dependent_name = "dependent extension title"
dependent_controller = "dependent extension’s controller title"
dependent_version = "a dependent extension’s version, older which the current package will not be installed"
dependent_url = "a link to the dependent controller page"
dependent_title = "dependent controller title"

By specifying the parameters listed above, you can distribute packages that will not be installed in the Control panel, if conditions do not meet. For example, you created some component. You distribute it. Then you decide to create a widget for it. Specify your component availability in the dependencies of the widget installation package. For example, the parameters of the widget dependent on a controller can have the following view:

dependent_type = "component"
dependent_name = "video"
dependent_version = "2.2"
dependent_url = "http://instantcms.ru/addons/instantvideo2.html"
dependent_title = "InstantVideo2"

In this case, if the InstantVideo2 component is not installed or is installed but is older than version 2.2, the widget package installation will fail.

If your extension depends on the availability of an installed widget (for example, your package distributes an additional template of it), the parameters will be as follows:

dependent_type = "widget"
dependent_name = "promo"
dependent_controller = "video"
dependent_version = "2.0"
dependent_url = "http://instantcms.ru/addons/instantvideo2.html"
dependent_title = "InstantVideo2 promo video"

In this case, during installation, the extension will require the «InstantVideo2 promo video» widget whose version is not older than 2.0. It is worth noting that the ''dependent_version'’ parameter is optional and the version is checked only if it exists.

This block is optional but advisable for users to know whom to contact about the extension issues.

name  = "developer name: brand or some name, not more than 128 symbols long"
url   = "website address starting with http://, if there is one, not more than 250 symbols long"
email = "developer’s e-mail, if there is one"

This block is optional

text[] = "Extension description"
text[] = "There can be one or"
text[] = "several strings"

Only one of the specified blocks can be in the file, i.e. either [install] or [update]. With the help of them the CMS detects the type: installation or update. The following options are required inside the block (identical for both types) :

type = "you can specify only component or widget or system"
name = "system name"
an option for a widget, can be empty or be missing if a widget does not need a controller

For example, the block of the video component installation package can have the following view:

[install]
type = "component"
name = "video"

as for the update, it will look like:

[update]
type = "component"
name = "video"

To install a widget bound to a specific component, the options can be as follows:

[install]
type = "widget"
name = "related"
controller = "video"

Analogously in the case of an update.

A Video Tutorial about an extension installer creation

The mechanism of removing custom components is available from InstantCMS version 2.4.0. By default, the deletion action deletes the component entries from the cms_controllers table. Extension developers can supplement the mechanism in two ways by default:

• create a method called deleteController in the custom Model and describe the removal instructions there, opposite to the ones performed during installation;
• create the «delete_component» special action in your controller’s Backend and similarly describe the actions to delete the component data.

You can choose not to supplement and not to implement the removal mechanism if your component does not need it. In this case, an entry from the cms_controllers table will simply be deleted upon removal.

As for the model method, the code may be as follows:

public function deleteController($id) {
 
    // here you write some code that, for instance, deletes tables created by the component during installation
    // delete entries concerning integration with other components, for example,
    // from the activity feed, rss and other components you use
 
 
    // you must request the parent method to delete an entry from the cms_controllers table
    return parent::deleteController($id);
 
}

Use the controller backend action, if you want a user to perform any action when deleting a component. The action is created as a standard action of the Backend Controller. The action must be called «delete_component». The parameters are not passed into it. As a result, apart from actions needed for your component, an entry from the cms_controllers table should be deleted.

$this->model->deleteController($controller_id);

Back to Contents