5.7 KiB
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
- Official module list on silverstripe.org
- Packagist.org "silverstripe" tag
- Github.com "silverstripe" search
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.
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.
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.