silverstrap 

silverstrap Commit Details

Date:2018-01-05 13:44:57 (1 year 5 months ago)
Author:Nicola Fontana
Branch:dev, master
Commit:6f809088bcb9fd15157c793119ef3c65a7053695
Parents: df0a4a9261b66c5a83e91afda468349a698af62c
Message:Move usage section into user docs

Changes:
MREADME.md (3 diffs)
Mdocs/en/usage.md (1 diff)

File differences

README.md
22
33
44
5
6
7
8
9
5
6
7
108
11
12
9
10
1311
1412
1513
......
2725
2826
2927
30
31
32
28
3329
3430
3531
......
5349
5450
5551
56
57
5852
59
53
54
6055
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
56
57
58
59
60
61
===========
A [SilverStripe](http://www.silverstripe.org/) theme based on the
[Bootstrap](http://twitter.github.io/bootstrap/) front-end framework.
It should work out of the box on basic sites, so you can drop it into
your `themes` folder, enable it (either programmatically by using
`SSViewer::set_theme('silverstrap')` or by switching it in the CMS) and
check how your new site look.
[Bootstrap](http://twitter.github.io/bootstrap/) front-end framework. It should
work out of the box on basic sites, i.e. by installing and enabling it you
should already see how it looks a SilverStrap based website.
The master-1.0 branch is in maintenance mode and it is based on the
deprecated (and no longer officially supported) Bootstrap version 2.
The `boostrap2` branch is in maintenance mode and it is based on the
SilverStripe 3 and Bootstrap 2.
The master and dev branches, released as silverstrap-2.x.x, are based
on Bootstrap 3.
--------
* Composer ready.
* No dependency on SASS/LESS/whatever. This is a plain SilverStripe
theme: just unpack the tarball under `themes/` or install via
`composer` and enable it.
* No dependency on SASS/LESS/whatever.
* Out of the box support for silverstripe blog and comments module.
* Out of the box support for dynamically generated tables of contents.
If you install the [silverstripe-autotoc](http://dev.entidi.com/p/silverstripe-autotoc/)
* JavaScript configuration can be overriden: see *Customizing JavaScript
modules*.
External dependencies
---------------------
Silverstrap depends on some external project:
Other documentation
-------------------
* _Bootstrap_, the main dependency;
* _JQuery_, needed by Bootstrap;
* _Colorbox_, for zooming images;
* _Fotorama_, for photo galleries.
_Colorbox_ and _Fotorama_ are not strictly required but are useful when
silverstrap is used in conjunction with other modules. In any case,
all those components are included out of the box by the base templates.
By default the resources are fetched from the jsdelivr CDN network (see
the `SilverstrapJsdelivr.ss` template) but a couple of alternatives are
included:
* `SilverstrapOffline.ss` fetches the resources directly from the
filesystem, making the site usable when disconnected from internet;
* `SilverstrapModular.ss` fetches the resources from jsdelivr too but it
is modular, e.g. every dependency has its own template.
Depending on your requirements, you can prefer one of these methods
instead of the default one. If this is the case, just override
`Silverstrap.ss` to include the offline or the modular version. Consult
the next session to know how to override templates.
Customizing JavaScript modules
------------------------------
`silverstrap.js` defines the global object `silverstrap` where all the
default JavaScript settings are stored.
To override this settings (i.e. to change the out of the box behavior of
the JavaScript modules) you should change this global object after
including `silverstrap.js`, e.g.:
<script src="themes/silverstrap/js/silverstrap.js></script>
<script>
// Disable fullscreen in fotorama
silverstrap.fotorama.allowfullscreen = false;
// Colorbox zoom to 50% max
silverstrap.colorbox.maxWidth = '50%';
silverstrap.colorbox.maxHeight = '50%';
</script>
Overriding silverstrap
----------------------
Let's say you want to work off-line so you need to not depend on a CDN,
as required out of the box by silverstrap. You can just modify
`silverstrap/templates/Includes/Silverstrap.ss` and change the code to
include `SilverstrapOffline` instead of `SilverstrapJsdelivr`. Although
this works, it will change the silverstrap directory tree... and this
is very bad: you'll loose the possibility to update silverstrap with a
`git pull` or by leveraging `composer`.
Instead you can use the SilverStripe template trick used by the
[silverstripe-treeish](http://dev.entidi.com/p/silverstripe-treeish/)
project, i.e. override any template *without* touching a single byte of
the original folder:
1. install silverstrap under `themes` (as usual): `composer` will do
this for you;
2. create a `silverstrap_Page` directory at the same level of the
`silverstrap` directory: any page of type `Page` (hence the whole
site) will look for templates in this directory first;
3. copy any template you want to override from `silverstrap` to
`silverstrap_Page`, retaining its relative path;
4. modify in any way you like whatever under `silverstrap_Page`;
5. flush and test.
In the case outlined by this section, you can copy `Silverstrap.ss` into
`silverstrap_Page/templates/Includes/Silverstrap.ss` and change its
content to:
<% include SilverstrapOffline %>
This trick can be used to override pretty much everything, such as to
enhance the default page template, to set the favicon, to add or remove
a feature or to put a watermark on every page. The templates in
silverstrap are quite fragmented to make the overriding easier. For
example, [silverstripe-cerulean](http://dev.entidi.com/p/silverstripe-cerulean/)
is an extension to Silverstrap that uses this very same approach to
override the default plain Bootstrap theme with the
[Cerulean](http://bootswatch.com/cerulean/) one.
Accessing parent pages
----------------------
The default implementation provides support for custom nested levels
in _.navbar_ but does not provide a way to access the parent pages, as
commonly provided by vanilla SilverStripe. In other words, if you have
subpages under `yoursite/contacts/` you can access them but there is no
easy way to access `yoursite/contacts/` (apart from directly write the
URL).
To alleviate the problems a *Sitemap* of the first two levels is put
by default before the footer. This does not resolve the problem for
further levels though.
To be able to access the parent pages directly from the _.navbar_ you
can override `NavbarSubmenu.ss` and add a fixed item at the beginning
of the `<ul>` list, right before looping on `$Children`. The
`NavbarSubmenuAccessible.ss` file does exactly that, so you should use
it instead of the original template. By leveraging the override trick
explained in the previous section, you can accomplish this by creating
`themes/silverstrap_Page/templates/Includes/NavbarItem.ss` under your
website directory with the following content:
<% if $Children %><% if $Parent %>
<% include NavbarSubmenuAccessible %><% else %>
<% include NavbarMenu %><% end_if %>
<% else %>
<% include NavbarLink %>
<% end_if %>
Support
-------
This project has been developed by [ntd](mailto:ntd@entidi.it). Its
[home page](http://silverstripe.entidi.com/themes/) is shared by other
[SilverStripe](http://www.silverstripe.org/) modules and themes.
To check out the code, report issues or propose enhancements, go to the
[dedicated tracker](http://dev.entidi.com/p/silverstripe-carousel).
[dedicated tracker](http://dev.entidi.com/p/silverstrap/).
Alternatively, you can do the same things by leveraging the official
[github repository](https://github.com/ntd/silverstrap).
* [Usage](docs/en/usage.md)
* [Contributing](CONTRIBUTING.md)
* [Code of Conduct](https://docs.silverstripe.org/en/contributing/code_of_conduct)
* [BSD license](LICENSE.md)
* [ChangeLog](CHANGELOG.md)
* [Support](docs/en/support.md)
docs/en/usage.md
11
22
33
4
4
55
66
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
Usage
-----
Customization is provided by the related [SilverStripe
Complete layout customization is provided by the related [SilverStripe
module](https://github.com/ntd/silverstrap-module): see its documentation for
further details.
External dependencies
---------------------
Silverstrap depends on some external project:
* _Bootstrap_, the main dependency;
* _JQuery_, needed by Bootstrap;
* _Colorbox_, for zooming images;
* _Fotorama_, for photo galleries.
_Colorbox_ and _Fotorama_ are not strictly required but are useful when
silverstrap is used in conjunction with other modules (e.g.
`entidi/silverstripe-gallery`). In any case all those components are included
out of the box by the base templates.
By default the resources are fetched from the jsdelivr CDN network (see
the `SilverstrapJsdelivr.ss` template) but a couple of alternatives are
included:
* `SilverstrapOffline.ss` fetches the resources directly from the
filesystem, making the site usable when disconnected from internet;
* `SilverstrapModular.ss` fetches the resources from jsdelivr too but it
is modular, e.g. every dependency has its own template.
Depending on your requirements, you can prefer one of these methods
instead of the default one. If this is the case, just override
`Silverstrap.ss` to include the offline or the modular version. Consult
the next session to know how to override templates.
Customizing JavaScript modules
------------------------------
`silverstrap.js` defines the global object `silverstrap` where all the
default JavaScript settings are stored.
To override this settings (i.e. to change the out of the box behavior of
the JavaScript modules) you should change this global object after
including `silverstrap.js`, e.g.:
<script src="themes/silverstrap/js/silverstrap.js></script>
<script>
// Disable fullscreen in fotorama
silverstrap.fotorama.allowfullscreen = false;
// Colorbox zoom to 50% max
silverstrap.colorbox.maxWidth = '50%';
silverstrap.colorbox.maxHeight = '50%';
</script>
Overriding silverstrap
----------------------
Let's say you want to work off-line so you need to not depend on a CDN,
as required out of the box by silverstrap. You can just modify
`silverstrap/templates/Includes/Silverstrap.ss` and change the code to
include `SilverstrapOffline` instead of `SilverstrapJsdelivr`. Although
this works, it will change the silverstrap directory tree... and this
is very bad: you'll loose the possibility to update silverstrap with a
`git pull` or by leveraging `composer`.
Instead you can use the SilverStripe template trick used by the
[silverstripe-treeish](http://dev.entidi.com/p/silverstripe-treeish/)
project, i.e. override any template *without* touching a single byte of
the original folder:
1. install silverstrap under `themes` (as usual): `composer` will do
this for you;
2. create a `silverstrap_Page` directory at the same level of the
`silverstrap` directory: any page of type `Page` (hence the whole
site) will look for templates in this directory first;
3. copy any template you want to override from `silverstrap` to
`silverstrap_Page`, retaining its relative path;
4. modify in any way you like whatever under `silverstrap_Page`;
5. flush and test.
In the case outlined by this section, you can copy `Silverstrap.ss` into
`silverstrap_Page/templates/Includes/Silverstrap.ss` and change its
content to:
<% include SilverstrapOffline %>
This trick can be used to override pretty much everything, such as to
enhance the default page template, to set the favicon, to add or remove
a feature or to put a watermark on every page. The templates in
silverstrap are quite fragmented to make the overriding easier. For
example, [silverstripe-cerulean](http://dev.entidi.com/p/silverstripe-cerulean/)
is an extension to Silverstrap that uses this very same approach to
override the default plain Bootstrap theme with the
[Cerulean](http://bootswatch.com/cerulean/) one.
Accessing parent pages
----------------------
The default implementation provides support for custom nested levels
in _.navbar_ but does not provide a way to access the parent pages, as
commonly provided by vanilla SilverStripe. In other words, if you have
subpages under `yoursite/contacts/` you can access them but there is no
easy way to access `yoursite/contacts/` (apart from directly write the
URL).
To alleviate the problems a *Sitemap* of the first two levels is put
by default before the footer. This does not resolve the problem for
further levels though.
To be able to access the parent pages directly from the _.navbar_ you
can override `NavbarSubmenu.ss` and add a fixed item at the beginning
of the `<ul>` list, right before looping on `$Children`. The
`NavbarSubmenuAccessible.ss` file does exactly that, so you should use
it instead of the original template. By leveraging the override trick
explained in the previous section, you can accomplish this by creating
`themes/silverstrap_Page/templates/Includes/NavbarItem.ss` under your
website directory with the following content:
<% if $Children %><% if $Parent %>
<% include NavbarSubmenuAccessible %><% else %>
<% include NavbarMenu %><% end_if %>
<% else %>
<% include NavbarLink %>
<% end_if %>

Archive Download the corresponding diff file