Version 3 end of life
This version of Silverstripe CMS will not recieve any additional bug fixes or documentation updates. Go to documentation for the most recent stable version.

Modules

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

A module is a collection of classes, templates, and other resources that is loaded into a top-level directory such as the framework, cms or mysite folders. The only thing that identifies a folder as a SilverStripe module is the existence of a _config directory or _config.php at the top level of the directory.

	mysite/
	|
	+-- _config/
	+-- code/
	+-- ..
	|
	my_custom_module/
	|
	+-- _config/
	+-- ...

cache.

[info] In a default SilverStripe installation, even resources in framework and mysite are treated in exactly the same as every other module. Order of priority is usually alphabetical unless stated. [/info]

Creating a module is a good way to re-use abstract code and templates across multiple projects. SilverStripe already has certain modules included, for example the cms module and core functionality such as commenting and spam protection are also abstracted into modules allowing developers the freedom to choose what they want.

Finding Modules

Installation

Modules should exist in the root folder of your SilverStripe installation.

[info] The root directory is the one containing the framework and mysite subdirectories. If your site is installed under /Users/sam.minnee/Sites/website/ your modules will go in the /Users/sam.minnee/Sites/website/ directory. [/info]

[notice] After you add or remove modules make sure you rebuild the database by going to http://yoursite.com/dev/build?flush=1 [/notice]

From Composer

Our preferred way to manage module dependencies is through the Composer 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. To install modules using this method, you will first need to setup SilverStripe with Composer.

Each module has a unique identifier, consisting of a vendor prefix and name. For example, the "blog" module has the identifier silverstripe/blog as it is published by silverstripe. To install, use the following command executed in the root folder: 

	composer require "silverstripe/blog" "*@stable"

tag name.

	composer require "silverstripe/blog" "1.1.0"

To lock down to a specific version, branch or commit, read up on Composer "lock" files. [/info]

From an Archive Download

[alert] Some modules might not work at all with this approach since they rely on the Composer autoloader, additional modules or post-install hooks, so we recommend using Composer. [/alert]

Alternatively, you can download the archive file from the modules page and extract it to the root folder mentioned above.

[notice] 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. [/notice]

Publishing your own SilverStripe module

See the How to Publish a SilverStripe Module for details on how to publish your SilverStripe modules with the community

Module Standard

The SilverStripe module standard defines a set of conventions that high-quality SilverStripe modules should follow. It’s a bit like PSR for SilverStripe CMS. Suggested improvements can be raised as pull requests.

Coding Guidelines

  • Declaration of level of support is provided for each module (either via README.md or composer) including the below.

    • Level of support provided.
    • Supporting user(s) and/or organisation(s).

  • Complies to a well defined module directory structure and coding standards:

    • templates (for ss templates)
    • code (for php files)
    • tests (for php test files) and
    • _config (for yml config)
  • The module is a Composer package.
  • All Composer dependencies are bound to a single major release (e.g. ^3.1 not >=3.1).
  • There is a level of test coverage.
  • A clear public API documented in the docblock tags.
  • Recommend the use of PSR-1 and PSR-2.
  • .gitattributes will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded.

Documentation Guidelines

Documentation will use the following format:

  • README.md provides:

    • Links or badges to CI and code quality tools.
    • A short summary of the module, end-user.
    • Installation instructions
    • Testing/development instructions and a link to contrib instructions.
    • How to report security vulnerabilities. Note that PSR-9 / PSR-10 may be recommended once released.
    • Security, license, links to more detailed docs.
  • CONTRIBUTING.md explaining terms of contribution.
  • A changelog CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). You could use a changelog generator to help create this.
  • Has a licence (LICENSE.md file) - for SilverStripe supported this needs to be BSD.
  • Detailed documentation in /docs/en as a nested set of GitHub-compatible Markdown files.
  • It is suggested to use a documentation page named userguide.md in docs/en/ that includes documentation of module features that have CMS user functionality (if applicable). For modules with large userguides, this should be in a directory named userguide with an index.md linking to any other userguide pages.
  • Links and image references are relative, and are able to be followed in viewers such as GitHub.
  • Markdown may include non-visible comments or meta-data.

Documentation will cover:

  • Installation
  • Configuration
  • Usage guides for key features; screenshots are recommended.
  • A committers guide, covering PR-merging and release guidelines.

Related

Edit on Github