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
16Features
17--------
18
19* Should work out of the box.
20* No dependency on SASS or Ruby. This is a plain SilverStripe theme:
21 just unpack the tarball under `themes/` and enable it.
22* Out of the box support for dynamically generated tables of contents.
23 If you install the [silverstripe-autotoc](http://dev.entidi.com/p/silverstripe-autotoc/)
24 module, silverstrap will generate on the fly the table of contents of
25 the current page (if possible) and it will present it in a _.navlist_
26 on the left side. Your site will gain table of contents for free.
27* Proper support for pages nested at arbitrary levels.
28* Quite extensible and customizable. This can be done by *overriding*
29 the default implementation instead of editing it: check the following
30 section for further details.
31
32Overriding silverstrap
33----------------------
34
35Let's say you want to use a custom Bootstrap CSS, such as the ones
36provided by [Bootswatch](http://bootswatch.com/). You can download and
37store it over the default CSS found in `silverstrap/css/bootstrap.css`.
38This works but it will overwrite the default CSS provided by
39silverstrap... and this is bad. You loose the possibility to update
40silverstrap with a `git pull`.
41
42Instead, you can use the SilverStripe template trick used by
43[silverstripe-treeish](http://dev.entidi.com/p/silverstripe-treeish/)
44to override the templates *without touching a byte* of the original
45silverstrap folder:
46
471. put silverstrap under `themes` (as usual).
482. create a `silverstrap_Page` directory at the same directory level:
49 any page of type `Page` (hence the whole site) will look in this
50 directory before for every template;
513. copy the custom bootstrap CSS in some place accessible by the web
52 server, e.g. under `themes/silverstrap_Page/css/mybootstrap.css`;
534. create `themes/silverstrap_Page/templates/Includes/Bootstrap.ss`
54 and put the following template code in it:
55
56 <%-- Override the default bootstrap theme with the custom one --%>
57 <% require CSS(themes/silverstrap_Page/css/mybootstrap.css) %>
58 <% require themedCSS(bootstrap-responsive) %>
59 <script src="$ThemeDir/js/bootstrap.min.js"></script>
60
61
62[silverstripe-cerulean](http://dev.entidi.com/p/silverstripe-cerulean/)
63is an extension to Silverstrap that uses this very same approach to
64override the Bootstrap theme Silverstrap is based on with
65[Cerulean](http://bootswatch.com/cerulean/). You can check the
66[source code](http://dev.entidi.com/p/silverstripe-cerulean/source/tree/master/)
67for technical details.
68
69This trick can be used to override anything, such as to enhance the
70default page template, to set the favicon, to add or remove a feature
71or to put a watermark on every page. The templates in silverstrap are
72quite fragmented to make it easier to change only a single aspect.
73
74Accessing parent pages
75----------------------
76
77The default implementation provides support for custom nested levels
78in _.navbar_ but does not provide a way to access the parent pages, as
79commonly provided by vanilla SilverStripe. In other words, if you have
80subpages under `yoursite/contacts/` you can access them but there is no
81easy way to access `yoursite/contacts/` (apart from directly write the
82URL).
83
84To alleviate the problems a *Sitemap* of the first two levels is put
85by default before the footer. This does not resolve the problem for
86further levels though.
87
88To be able to access the parent pages directly from the _.navbar_ you
89can override `NavbarSubmenu.ss` and add a fixed item at the beginning
90of the `<ul>` list, right before looping on `$Children`. The
91`NavbarSubmenuAccessible.ss` file does exactly that, so you should use
92it instead of the original template. By leveraging the override trick
93explained in the previous section, you can accomplish this by creating
94`themes/silverstrap_Page/templates/Includes/NavbarItem.ss` under your
95website directory with the following content:
96
97 <% if $Children %><% if $Parent %>
98 <% include NavbarSubmenuAccessible %><% else %>
99 <% include NavbarMenu %><% end_if %>
100 <% else %>
101 <% include NavbarLink %>
102 <% end_if %>
103
104Support
105-------
106
107For bug reports or feature requests, please use the dedicated
108[development tracker](http://dev.entidi.com/p/silverstrap/).

Archive Download this file