tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Update themes document for SS4

Browse Source 
* Remove module specific subthemes documentation as it's removed
* Added notes about cascading theme configuration
* Update links to Themes listing to point to addons
* Remove references to tarballs, and put composer publishing instructions in place instead
This commit is contained in:
Robbie Averill 2017-01-30 15:25:35 +13:00 committed by Robbie Averill
parent 77bfea1197
commit fa5370e4dd
1 changed files with 36 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/en/02_Developer_Guides/01_Templates/06_Themes.md
View File

@ -8,23 +8,21 @@ application can provide multiple unique themes (i.e a mobile theme).
## Downloading ## Downloading
Head to the [ Themes ](http://www.silverstripe.org/themes) area of the website to check out the range of themes the 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. The theme is provided 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,
as a .tar.gz file. but may be available as archive files as well.
## Installation ## 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 ### 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 ```bash
composer require "author/theme_name" "dev/master" 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.
<div class="alert" markdown="1"> <div class="alert" markdown="1">
As you've added new files to your SilverStripe installation, make sure you clear the SilverStripe cache by appending 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
</div> </div>
After installing the files through either method, update the current theme in SilverStripe. This can be done by 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) the Site Configuration panel (http://yoursite.com/admin/settings)
**mysite/_config/app.yml** **mysite/_config/app.yml**
:::yml
SSViewer: ```yaml
theme: theme_name 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 ## Developing your own theme
A `theme` within SilverStripe is simply a collection of templates and other front end assets such as javascript and css. 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.
located within the `themes` directory.
![themes:basicfiles.gif](../../_images/basicfiles.gif) ![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.
``` 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.
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
```
## 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 * 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. 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 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).
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. 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 ## Links
* [Themes Listing on silverstripe.org](http://silverstripe.org/themes) * [Themes Listing on silverstripe.org](http://addons.silverstripe.org/add-ons?search=&type=theme)
* [Themes Forum on silverstripe.org](http://www.silverstripe.org/themes-2/) * [Themes Forum on silverstripe.org](https://www.silverstripe.org/community/forums/themes-2/)
* [Themes repository on github.com](http://github.com/silverstripe-themes) * [Themes repositories on github.com](http://github.com/silverstripe-themes)