diff --git a/docs/en/02_Developer_Guides/01_Templates/06_Themes.md b/docs/en/02_Developer_Guides/01_Templates/06_Themes.md index 80cc8a1b4..cf4232798 100644 --- a/docs/en/02_Developer_Guides/01_Templates/06_Themes.md +++ b/docs/en/02_Developer_Guides/01_Templates/06_Themes.md @@ -8,23 +8,21 @@ application can provide multiple unique themes (i.e a mobile theme). ## Downloading -Head to the [ Themes ](http://www.silverstripe.org/themes) area of the website to check out the range of themes the -community has built. Each theme has a page with links you can use to preview and download it. The theme is provided -as a .tar.gz file. +Head to the [ themes section of the addons site ](http://addons.silverstripe.org/add-ons?search=&type=theme) to check out the range of themes the +community has built. Each theme has a page with links you can use to preview and download it. Themes are normally published and downloaded using Composer, +but may be available as archive files as well. ## Installation -### Manually - -Unpack the contents of the zip file you download into the `themes` directory in your SilverStripe installation. The -theme should be accessible at `themes/theme_name`. - ### Via Composer -If a theme has `composer` support you can require it directly through `composer`. +If a theme has Composer support you can require it directly through `composer`. - :::bash - composer require "author/theme_name" "dev/master" +```bash +composer require author/theme_name [version] +``` + +*Note:* `[version]` should be replaced with a version constraint if you know it, otherwise leave it blank to pull the latest version compatible with your project.
As you've added new files to your SilverStripe installation, make sure you clear the SilverStripe cache by appending @@ -32,60 +30,49 @@ As you've added new files to your SilverStripe installation, make sure you clear
After installing the files through either method, update the current theme in SilverStripe. This can be done by -either altering the `SSViewer.theme` setting in a [config.yml](../configuration) or by changing the current theme in +either altering the `SSViewer.themes` setting in a [config.yml](../configuration) or by changing the current theme in the Site Configuration panel (http://yoursite.com/admin/settings) **mysite/_config/app.yml** - :::yml - SSViewer: - theme: theme_name + +```yaml +SilverStripe\View\SSViewer: + themes: + - theme_name + - '$default' +``` + +### Manually + +Unpack the contents of the zip file you download into the `themes` directory in your SilverStripe installation. The +theme should be accessible at `themes/theme_name`. ## Developing your own theme -A `theme` within SilverStripe is simply a collection of templates and other front end assets such as javascript and css. -located within the `themes` directory. +A `theme` within SilverStripe is simply a collection of templates and other front end assets such as javascript and CSS located within the `themes` directory. ![themes:basicfiles.gif](../../_images/basicfiles.gif) -Your theme can also be organised into split folders for each module it caters for. +SilverStripe 4 has support for cascading themes, which will allow users to define multiple themes for a project. This means you can have a template defined in any theme, and have it continue to look back through the list of themes until a match it found. -``` -themes - blackcandy - css - style.css - images - templates - Page.ss - Layout - Page.ss - Includes - blackcandy_blog - css - blog.css - images - templates - Layout - BlogHolder.ss - BlogEntry.ss - Includes -``` +To define extra themes simply add extra entries to the `SilverStripe\View\SSViewer.themes` configuration array. You will probably always want to ensure that you include `'$default'` in your list of themes to ensure that the base templates are used when required. -## Submitting your theme to SilverStripe +## Submitting your theme to addons -If you want to submit your theme to the SilverStripe directory then check +If you want to submit your theme to the SilverStripe addons directory then check: * You should ensure your templates are well structured, modular and commented so it's easy for other people to customise -* Templates should not contain text inside images and all images provided must be open source and not break any +* Templates should not contain text inside images and all images provided must be open source and not break any copyright or license laws. This includes any icons your template uses. -* A theme does not include any PHP files. Only CSS, HTML, Images and javascript. +* A theme does not include any PHP files. Only CSS, HTML, images and javascript. +* Your theme contains a `composer.json` file specifying the theme name, author and license, and that it has `"type": "silverstripe-theme"`. -Your theme file must be in a .tar.gz format. A useful tool for this is - [7 Zip](http://www.7-zip.org/). Using 7Zip you -must select the your_theme folder and Add to archive, select TAR and create. Then after you have the TAR file right -click it -> Add to Archive (again) -> Then use the archive format GZIP. +Once you've created your module and set up your Composer configuration, create a new repository and push your theme to a Git host such as [GitHub.com](https://github.com). + +The final step is to [submit your theme to Packagist](https://packagist.org/about#how-to-submit-packages) (the central Composer package repository). Once your theme is listed in Packagist, and has `"type": "silverstripe-theme"` in its configuration, it will automatically be pulled into our addons listing site. ## Links - * [Themes Listing on silverstripe.org](http://silverstripe.org/themes) - * [Themes Forum on silverstripe.org](http://www.silverstripe.org/themes-2/) - * [Themes repository on github.com](http://github.com/silverstripe-themes) + * [Themes Listing on silverstripe.org](http://addons.silverstripe.org/add-ons?search=&type=theme) + * [Themes Forum on silverstripe.org](https://www.silverstripe.org/community/forums/themes-2/) + * [Themes repositories on github.com](http://github.com/silverstripe-themes)