silverstrap 

silverstrap Git Source Tree

Root/README.md

1SilverStrap
2===========
3
4A [SilverStripe](http://www.silverstripe.org/) theme based on the
5[Bootstrap](http://twitter.github.io/bootstrap/) front-end framework.
6It should work out of the box on basic sites, so you can drop it into
7your `themes` folder, enable it (either programmatically by using
8`SSViewer::set_theme('silverstrap')` or by switching it in the CMS) and
9check how your new site look.
10
11The master-1.0 branch is in maintenance mode and it is based on the
12deprecated (and no longer officially supported) Bootstrap version 2.
13The master and dev branches, released as silverstrap-2.x.x, are based
14on Bootstrap 3.
15
16Installation
17------------
18
19With composer:
20
21 composer require entidi/silverstrap
22
23Without composer, download [the tarball](https://github.com/ntd/silverstrap/releases)
24and unpack it under the `themes` directory.
25
26Features
27--------
28
29* Composer ready.
30* No dependency on SASS/LESS/whatever. This is a plain SilverStripe
31 theme: just unpack the tarball under `themes/` or install via
32 `composer` and enable it.
33* Out of the box support for silverstripe blog and comments module.
34* Out of the box support for dynamically generated tables of contents.
35 If you install the [silverstripe-autotoc](http://dev.entidi.com/p/silverstripe-autotoc/)
36 module, silverstrap will generate on the fly the table of contents of
37 the current page (if possible) and it will present it in a _.navlist_
38 on the right side. Your site will gain table of contents for free.
39* Proper support for pages nested at arbitrary levels.
40* Quite extensible and customizable. This can be done by _overriding_
41 the default implementation instead of editing it: check the section
42 *Overriding silverstrap* for further details.
43* Different components inclusion methods. By default external components
44 (such as JQuery and Bootstrap) are fetched from the jsdelivr CDN
45 network but a couple of alternate methods are provided. See the
46 section *External dependencies* for details.
47
48External dependencies
49---------------------
50
51Silverstrap depends on some external project:
52
53* _Bootstrap_, the main dependency;
54* _JQuery_, needed by Bootstrap;
55* _Colorbox_, for zooming images;
56* _Fotorama_, for photo galleries.
57
58_Colorbox_ and _Fotorama_ are not strictly required but are useful when
59silverstrap is used in conjunction with other modules. In any case,
60all those components are included out of the box by the base templates.
61
62By default the resources are fetched from the jsdelivr CDN network (see
63the `SilverstrapJsdelivr.ss` template) but a couple of alternatives are
64included:
65
66* `SilverstrapOffline.ss` fetches the resources directly from the
67 filesystem, making the site usable when disconnected from internet;
68* `SilverstrapModular.ss` fetches the resources from jsdelivr too but it
69 is modular, e.g. every dependency has its own template.
70
71Depending on your requirements, you can prefer one of these methods
72instead of the default one. If this is the case, just override
73`Silverstrap.ss` to include the offline or the modular version. Consult
74the next session to know how to override templates.
75
76Overriding silverstrap
77----------------------
78
79Let's say you want to work off-line so you need to not depend on a CDN,
80as required out of the box by silverstrap. You can just modify
81`silverstrap/templates/Includes/Silverstrap.js` and change the code to
82include `SilverstrapOffline` instead of `SilverstrapJsdelivr`. Although
83this works, it will change the silverstrap directory tree... and this
84is very bad: you'll loose the possibility to update silverstrap with a
85`git pull` or by leveraging `composer`.
86
87Instead you can use the SilverStripe template trick used by the
88[silverstripe-treeish](http://dev.entidi.com/p/silverstripe-treeish/)
89project, i.e. override any template *without* touching a single byte of
90the original folder:
91
921. install silverstrap under `themes` (as usual): `composer` will do
93 this for you;
942. create a `silverstrap_Page` directory at the same level of the
95 `silverstrap` directory: any page of type `Page` (hence the whole
96 site) will look for templates in this directory first;
973. copy any template you want to override from `silverstrap` to
98 `silverstrap_Page`, retaining its relative path;
994. modify in any way you like whatever under `silverstrap_Page`;
1005. flush and test.
101
102In the case outlined by this section, you can copy `Silverstrap.ss` into
103`silverstrap_Page/templates/Includes/Silverstrap.ss` and change its
104content to:
105
106 <% include SilverstrapOffline %>
107
108This trick can be used to override pretty much everything, such as to
109enhance the default page template, to set the favicon, to add or remove
110a feature or to put a watermark on every page. The templates in
111silverstrap are quite fragmented to make the overriding easier. For
112example, [silverstripe-cerulean](http://dev.entidi.com/p/silverstripe-cerulean/)
113is an extension to Silverstrap that uses this very same approach to
114override the default plain Bootstrap theme with the
115[Cerulean](http://bootswatch.com/cerulean/) one.
116
117Accessing parent pages
118----------------------
119
120The default implementation provides support for custom nested levels
121in _.navbar_ but does not provide a way to access the parent pages, as
122commonly provided by vanilla SilverStripe. In other words, if you have
123subpages under `yoursite/contacts/` you can access them but there is no
124easy way to access `yoursite/contacts/` (apart from directly write the
125URL).
126
127To alleviate the problems a *Sitemap* of the first two levels is put
128by default before the footer. This does not resolve the problem for
129further levels though.
130
131To be able to access the parent pages directly from the _.navbar_ you
132can override `NavbarSubmenu.ss` and add a fixed item at the beginning
133of the `<ul>` list, right before looping on `$Children`. The
134`NavbarSubmenuAccessible.ss` file does exactly that, so you should use
135it instead of the original template. By leveraging the override trick
136explained in the previous section, you can accomplish this by creating
137`themes/silverstrap_Page/templates/Includes/NavbarItem.ss` under your
138website directory with the following content:
139
140 <% if $Children %><% if $Parent %>
141 <% include NavbarSubmenuAccessible %><% else %>
142 <% include NavbarMenu %><% end_if %>
143 <% else %>
144 <% include NavbarLink %>
145 <% end_if %>
146
147Support
148-------
149
150For bug reports or feature requests, please use the dedicated
151[development tracker](http://dev.entidi.com/p/silverstrap/).

Archive Download this file