From c61881a4c0be8b9d7d6500e06bd8fd17ca5a0092 Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Wed, 8 Jan 2020 10:41:28 +1300 Subject: [PATCH] DOCS Clearer create module instructions (#9365) * DOCS Clearer create module instructions Incl. link to skeleton * Update docs/en/02_Developer_Guides/05_Extending/00_Modules.md Co-Authored-By: Garion Herman Co-authored-by: Garion Herman --- .../05_Extending/00_Modules.md | 35 ++++++++++++------- .../How_Tos/01_Publish_a_Module.md | 3 ++ 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/docs/en/02_Developer_Guides/05_Extending/00_Modules.md b/docs/en/02_Developer_Guides/05_Extending/00_Modules.md index aff8e3636..f8ac44206 100644 --- a/docs/en/02_Developer_Guides/05_Extending/00_Modules.md +++ b/docs/en/02_Developer_Guides/05_Extending/00_Modules.md @@ -10,9 +10,9 @@ SilverStripe is designed to be a modular application system - even the CMS is si framework. A module is a collection of classes, templates, and other resources that is loaded into a directory. -Usually this directory is a [Composer package](https://getcomposer.org/), which is placed in the `vendor/` folder. -SilverStripe modules are just Composer packages with a toplevel `_config` directory or `_config.php` file, -as well as a special type in their `composer.json` file. +Modules are [Composer packages](https://getcomposer.org/), and are placed in the `vendor/` folder. +These packages need to contain either a toplevel `_config` directory or `_config.php` file, +as well as a special `type` in their `composer.json` file ([example](https://github.com/silverstripe/silverstripe-module/blob/4/composer.json)). ``` app/ @@ -24,15 +24,14 @@ app/ vendor/my_vendor/my_module/ | +-- _config/ ++-- composer.json +-- ... ``` -SilverStripe will automatically include any PHP classes and templates from within your module when you next flush your -cache. - -Creating a module is a good way to re-use 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. +Like with any Composer package, we recommend declaring your PHP classes through +[PSR autoloading](https://getcomposer.org/doc/01-basic-usage.md#autoloading). +SilverStripe will automatically discover templates and configuration settings +within your module when you next flush your cache. ## Finding Modules @@ -71,14 +70,23 @@ To lock down to a specific version, branch or commit, read up on After you add or remove modules, make sure you rebuild the database, class and configuration manifests by going to http://yoursite.com/dev/build?flush=1 [/notice] -## Publishing your own SilverStripe module +## Creating a Module {#create} -See the [How to Publish a SilverStripe Module](how_tos/publish_a_module) for details on how to publish your SilverStripe -modules with the community +Creating a module is a good way to re-use code and templates across multiple projects, +or share your code with the community. 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. + +The easiest way to get started is our [Module Skeleton](https://github.com/silverstripe/silverstripe-module). +In case you want to share your creation with the community, +read more about [publishing a module](how_tos/publish_a_module). ## 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. +This standard is also part of the more highlevel +[Supported Modules Definition](https://www.silverstripe.org/software/addons/supported-modules-definition/) +which the SilverStripe project applies to the modules it creates and maintains directly. ### Coding Guidelines @@ -126,4 +134,5 @@ Documentation will cover: ## Related -* [How to Publish a SilverStripe Module](how_tos/publish_a_module) +* [Module Skeleton](https://github.com/silverstripe/silverstripe-module) +* [Publishing a module](how_tos/publish_a_module) diff --git a/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md b/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md index 06f993c73..c73eea71b 100644 --- a/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md +++ b/docs/en/02_Developer_Guides/05_Extending/How_Tos/01_Publish_a_Module.md @@ -6,6 +6,9 @@ icon: rocket # How to Publish a SilverStripe module. +After you've [created](modules#create) your own Silverstripe module, +you could decide to make it open source and share it with the world. + If you wish to submit your module to our public directory, you take responsibility for a certain level of code quality, adherence to conventions, writing documentation, and releasing updates.