Modules

SilverStripe is designed to be a modular application system - even the CMS is simply a module that plugs into it.

A module is, quite simply, a collection of classes, templates, and other resources that is loaded into a top-level directory. In a default SilverStripe download, even resources in 'framework' and 'mysite' are treated in exactly the same as every other module.

SilverStripe's [api:ManifestBuilder] will find any class, css or template files anywhere under the site's main directory. The _config.php file in the module directory as well as the _config/*.yml files can be used to define director rules, add extensions, etc. So, by unpacking a module into site's main directory and viewing the site with ?flush=1 on the end of the URL, all the module's new behaviour will be incorporated to your site:

You can create subclasses of base classes such as SiteTree to extend behaviour.
You can use Object::useCustomClass() to replace a built in class with a class of your own.
You can use an extension to extend or alter the behaviour of a built-in class without replacing it.
You can provide additional director rules to define your own controller for particular URLs.

For more information on creating modules, see module-development.

Types of Modules

Because of the broad definition of modules, they can be created for a number of purposes:

Applications: A module can define a standalone application that may work out of the box, or may get customisation from your mysite folder. "cms" is an example of this.
CMS Add-ons: A module can define an extension to the CMS, usually by defining special page types with their own templates and behaviour. "blog", "ecommerce", "forum", and "gallery" are examples of this.
Widgets: Small pieces of functionality such as showing the latest Comments or Flickr Photos. Since SilverStripe 3.0, they have been moved into a standalone module at github.com/silverstripe/silverstripe-widgets.
Developer Tools: A module can provide a number of classes or resource files that do nothing by themselves, but instead make it easier for developers to build other applications.

Finding Modules

Installation

Modules should exist in the root folder of your SilverStripe installation (the directory containing the framework and cms subdirectories).

The following article explains the generic installation of a module. Individual modules have their own requirements such as creating folders or configuring API keys. For information about installing or configuring a specific module see the modules README file. Modules should adhere to the directory-structure guidelines.

From a Composer Package

Our preferred way to manage module dependencies is through the [Composer][http://getcomposer.org] package manager. It enables you to install modules from specific versions, checking for compatibilities between modules and even allowing to track development branches of them.

After installing Composer itself, you can run a simple command to install a module. Each module has a unique identifier, consisting of a vendor prefix and name. For example, the popular "blog" module has the identifier silverstripe/blog, and would be installed with the following command executed in the root folder:

composer require silverstripe/blog:*@stable

This will fetch the latest compatible stable version. Every time you run composer update afterwards, Composer will check for a new stable version. To lock down to a specific version, branch or commit, read up on Composer "lock" files. You can also add modules by editing the "require" section of the composer.json file.

To find modules and their identifiers, search for them on packagist.org.

Older releases (<3.0.3, <2.4.9) don't come with a `composer.json` file in your root folder, which is required for its operation. In this case, we recommend upgrading to a newer release.

From an Archive Download

Alternatively, you can download the archive file from the modules page and extract it to the root folder mentioned above. Github also provides archive downloads which are generated automatically for every tag/version.

The main folder extracted from the archive might contain the version number or additional "container" folders above the actual module codebase. You need to make sure the folder name is the correct name of the module (e.g. "blog/" rather than "silverstripe-blog/"). This folder should contain a `_config/` directory. While the module might register and operate in other structures, paths to static files such as CSS or JavaScript won't work.

Some modules might not work at all with this approach since they rely on the Composer [autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading) or post-install hooks, so we recommend using Composer.

Git Submodules and Subversion Externals

Git and Subversion provide their own facilities for managing dependent repositories. This is essentially a variation of the "Archive Download" approach, and comes with the same caveats.

5.8 KiB Raw Blame History