Further modules included.
[yaffs-website] / web / themes / contrib / bootstrap / docs / Theme-Settings.md
1 <!-- @file Overview of theme settings for Drupal Bootstrap based themes. -->
2 <!-- @defgroup -->
3 <!-- @ingroup -->
4 # Theme Settings
5
6 To override a setting, open `./config/install/THEMENAME.settings.yml` and add the following:
7
8 ```yaml
9 # Settings
10
11 settings:
12   SETTING_NAME: SETTING_VALUE
13 ```
14
15 ---
16
17 ### Advanced
18
19 <table class="table table-striped table-responsive">
20   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
21   <tbody>
22   <tr>
23     <td class="col-xs-3">include_deprecated</td>
24     <td>
25       <div class="help-block">Enabling this setting will include any <code>deprecated.php</code> file found in your theme or base themes.</div>
26       <pre class=" language-yaml"><code>include_deprecated: 0
27 </code></pre>
28     </td>
29   </tr>
30   <tr>
31     <td class="col-xs-3">suppress_deprecated_warnings</td>
32     <td>
33       <div class="help-block">Enable this setting if you wish to suppress deprecated warning messages. <strong class='error text-error'>WARNING: Suppressing these messages does not "fix" the problem and you will inevitably encounter issues when they are removed in future updates. Only use this setting in extreme and necessary circumstances.</strong></div>
34       <pre class=" language-yaml"><code>suppress_deprecated_warnings: 0
35 </code></pre>
36     </td>
37   </tr>
38   </tbody>
39 </table>
40
41 ---
42
43 ### Advanced > CDN (Content Delivery Network)
44
45 <table class="table table-striped table-responsive">
46   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
47   <tbody>
48   <tr>
49     <td class="col-xs-3">cdn_provider</td>
50     <td>
51       <div class="help-block">Choose between jsdelivr or a custom cdn source.</div>
52       <pre class=" language-yaml"><code>cdn_provider: jsdelivr
53 </code></pre>
54     </td>
55   </tr>
56   <tr>
57     <td class="col-xs-3">cdn_custom_css</td>
58     <td>
59       <div class="help-block">It is best to use <code>https</code> protocols here as it will allow more flexibility if the need ever arises.</div>
60       <pre class=" language-yaml"><code>cdn_custom_css: 'https://cdn.jsdelivr.net/bootstrap/3.3.7/css/bootstrap.css'
61 </code></pre>
62     </td>
63   </tr>
64   <tr>
65     <td class="col-xs-3">cdn_custom_css_min</td>
66     <td>
67       <div class="help-block">Additionally, you can provide the minimized version of the file. It will be used instead if site aggregation is enabled.</div>
68       <pre class=" language-yaml"><code>cdn_custom_css_min: 'https://cdn.jsdelivr.net/bootstrap/3.3.7/css/bootstrap.min.css'
69 </code></pre>
70     </td>
71   </tr>
72   <tr>
73     <td class="col-xs-3">cdn_custom_js</td>
74     <td>
75       <div class="help-block">It is best to use <code>https</code> protocols here as it will allow more flexibility if the need ever arises.</div>
76       <pre class=" language-yaml"><code>cdn_custom_js: 'https://cdn.jsdelivr.net/bootstrap/3.3.7/js/bootstrap.js'
77 </code></pre>
78     </td>
79   </tr>
80   <tr>
81     <td class="col-xs-3">cdn_custom_js_min</td>
82     <td>
83       <div class="help-block">Additionally, you can provide the minimized version of the file. It will be used instead if site aggregation is enabled.</div>
84       <pre class=" language-yaml"><code>cdn_custom_js_min: 'https://cdn.jsdelivr.net/bootstrap/3.3.7/js/bootstrap.min.js'
85 </code></pre>
86     </td>
87   </tr>
88   <tr>
89     <td class="col-xs-3">cdn_jsdelivr_version</td>
90     <td>
91       <div class="help-block">Choose the Bootstrap version from jsdelivr</div>
92       <pre class=" language-yaml"><code>cdn_jsdelivr_version: 3.3.7
93 </code></pre>
94     </td>
95   </tr>
96   <tr>
97     <td class="col-xs-3">cdn_jsdelivr_theme</td>
98     <td>
99       <div class="help-block">Choose the example Bootstrap Theme provided by Bootstrap or one of the Bootswatch themes.</div>
100       <pre class=" language-yaml"><code>cdn_jsdelivr_theme: bootstrap
101 </code></pre>
102     </td>
103   </tr>
104   </tbody>
105 </table>
106
107 ---
108
109 ### Components > Breadcrumbs
110
111 <table class="table table-striped table-responsive">
112   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
113   <tbody>
114   <tr>
115     <td class="col-xs-3">breadcrumb</td>
116     <td>
117       <div class="help-block">Show or hide the Breadcrumbs</div>
118       <pre class=" language-yaml"><code>breadcrumb: '1'
119 </code></pre>
120     </td>
121   </tr>
122   <tr>
123     <td class="col-xs-3">breadcrumb_home</td>
124     <td>
125       <div class="help-block">If your site has a module dedicated to handling breadcrumbs already, ensure this setting is enabled.</div>
126       <pre class=" language-yaml"><code>breadcrumb_home: 0
127 </code></pre>
128     </td>
129   </tr>
130   <tr>
131     <td class="col-xs-3">breadcrumb_title</td>
132     <td>
133       <div class="help-block">If your site has a module dedicated to handling breadcrumbs already, ensure this setting is disabled.</div>
134       <pre class=" language-yaml"><code>breadcrumb_title: 1
135 </code></pre>
136     </td>
137   </tr>
138   </tbody>
139 </table>
140
141 ---
142
143 ### Components > Navbar
144
145 <table class="table table-striped table-responsive">
146   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
147   <tbody>
148   <tr>
149     <td class="col-xs-3">navbar_inverse</td>
150     <td>
151       <div class="help-block">Select if you want the inverse navbar style.</div>
152       <pre class=" language-yaml"><code>navbar_inverse: 0
153 </code></pre>
154     </td>
155   </tr>
156   <tr>
157     <td class="col-xs-3">navbar_position</td>
158     <td>
159       <div class="help-block">Determines where the navbar is positioned on the page.</div>
160       <pre class=" language-yaml"><code>navbar_position: ''
161 </code></pre>
162     </td>
163   </tr>
164   </tbody>
165 </table>
166
167 ---
168
169 ### Components > Region Wells
170
171 <table class="table table-striped table-responsive">
172   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
173   <tbody>
174   <tr>
175     <td class="col-xs-3">region_wells</td>
176     <td>
177       <div class="help-block">Enable the <code>.well</code>, <code>.well-sm</code> or <code>.well-lg</code> classes for specified regions.</div>
178       <pre class=" language-yaml"><code>region_wells:
179   navigation: ''
180   navigation_collapsible: ''
181   header: ''
182   highlighted: ''
183   help: ''
184   content: ''
185   sidebar_first: ''
186   sidebar_second: well
187   footer: ''
188 </code></pre>
189     </td>
190   </tr>
191   </tbody>
192 </table>
193
194 ---
195
196 ### General > Buttons
197
198 <table class="table table-striped table-responsive">
199   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
200   <tbody>
201   <tr>
202     <td class="col-xs-3">button_colorize</td>
203     <td>
204       <div class="help-block">Adds classes to buttons based on their text value.</div>
205       <pre class=" language-yaml"><code>button_colorize: 1
206 </code></pre>
207     </td>
208   </tr>
209   <tr>
210     <td class="col-xs-3">button_iconize</td>
211     <td>
212       <div class="help-block">Adds icons to buttons based on the text value</div>
213       <pre class=" language-yaml"><code>button_iconize: 1
214 </code></pre>
215     </td>
216   </tr>
217   <tr>
218     <td class="col-xs-3">button_size</td>
219     <td>
220       <div class="help-block">Defines the Bootstrap Buttons specific size</div>
221       <pre class=" language-yaml"><code>button_size: ''
222 </code></pre>
223     </td>
224   </tr>
225   </tbody>
226 </table>
227
228 ---
229
230 ### General > Container
231
232 <table class="table table-striped table-responsive">
233   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
234   <tbody>
235   <tr>
236     <td class="col-xs-3">fluid_container</td>
237     <td>
238       <div class="help-block">Uses the <code>.container-fluid</code> class instead of <code>.container</code>.</div>
239       <pre class=" language-yaml"><code>fluid_container: 0
240 </code></pre>
241     </td>
242   </tr>
243   </tbody>
244 </table>
245
246 ---
247
248 ### General > Forms
249
250 <table class="table table-striped table-responsive">
251   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
252   <tbody>
253   <tr>
254     <td class="col-xs-3">forms_has_error_value_toggle</td>
255     <td>
256       <div class="help-block">If an element has a <code>.has-error</code> class attached to it, enabling this will automatically remove that class when a value is entered.</div>
257       <pre class=" language-yaml"><code>forms_has_error_value_toggle: 1
258 </code></pre>
259     </td>
260   </tr>
261   <tr>
262     <td class="col-xs-3">forms_required_has_error</td>
263     <td>
264       <div class="help-block">If an element in a form is required, enabling this will always display the element with a <code>.has-error</code> class. This turns the element red and helps in usability for determining which form elements are required to submit the form.</div>
265       <pre class=" language-yaml"><code>forms_required_has_error: 0
266 </code></pre>
267     </td>
268   </tr>
269   <tr>
270     <td class="col-xs-3">forms_smart_descriptions</td>
271     <td>
272       <div class="help-block">Convert descriptions into tooltips (must be enabled) automatically based on certain criteria. This helps reduce the, sometimes unnecessary, amount of noise on a page full of form elements.</div>
273       <pre class=" language-yaml"><code>forms_smart_descriptions: 1
274 </code></pre>
275     </td>
276   </tr>
277   <tr>
278     <td class="col-xs-3">forms_smart_descriptions_allowed_tags</td>
279     <td>
280       <div class="help-block">Prevents descriptions from becoming tooltips by checking for HTML not in the list above (i.e. links). Separate by commas. To disable this filtering criteria, leave an empty value.</div>
281       <pre class=" language-yaml"><code>forms_smart_descriptions_allowed_tags: 'b, code, em, i, kbd, span, strong'
282 </code></pre>
283     </td>
284   </tr>
285   <tr>
286     <td class="col-xs-3">forms_smart_descriptions_limit</td>
287     <td>
288       <div class="help-block">Prevents descriptions from becoming tooltips by checking the character length of the description (HTML is not counted towards this limit). To disable this filtering criteria, leave an empty value.</div>
289       <pre class=" language-yaml"><code>forms_smart_descriptions_limit: '250'
290 </code></pre>
291     </td>
292   </tr>
293   </tbody>
294 </table>
295
296 ---
297
298 ### General > Images
299
300 <table class="table table-striped table-responsive">
301   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
302   <tbody>
303   <tr>
304     <td class="col-xs-3">image_responsive</td>
305     <td>
306       <div class="help-block">Images in Bootstrap 3 can be made responsive-friendly via the addition of the <code>.img-responsive</code> class. This applies <code>max-width: 100%;</code> and <code>height: auto;</code> to the image so that it scales nicely to the parent element.</div>
307       <pre class=" language-yaml"><code>image_responsive: 1
308 </code></pre>
309     </td>
310   </tr>
311   <tr>
312     <td class="col-xs-3">image_shape</td>
313     <td>
314       <div class="help-block">Add classes to an <code>&lt;img&gt;</code> element to easily style images in any project.</div>
315       <pre class=" language-yaml"><code>image_shape: ''
316 </code></pre>
317     </td>
318   </tr>
319   </tbody>
320 </table>
321
322 ---
323
324 ### General > Tables
325
326 <table class="table table-striped table-responsive">
327   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
328   <tbody>
329   <tr>
330     <td class="col-xs-3">table_bordered</td>
331     <td>
332       <div class="help-block">Add borders on all sides of the table and cells.</div>
333       <pre class=" language-yaml"><code>table_bordered: 0
334 </code></pre>
335     </td>
336   </tr>
337   <tr>
338     <td class="col-xs-3">table_condensed</td>
339     <td>
340       <div class="help-block">Make tables more compact by cutting cell padding in half.</div>
341       <pre class=" language-yaml"><code>table_condensed: 0
342 </code></pre>
343     </td>
344   </tr>
345   <tr>
346     <td class="col-xs-3">table_hover</td>
347     <td>
348       <div class="help-block">Enable a hover state on table rows.</div>
349       <pre class=" language-yaml"><code>table_hover: 1
350 </code></pre>
351     </td>
352   </tr>
353   <tr>
354     <td class="col-xs-3">table_responsive</td>
355     <td>
356       <div class="help-block">Makes tables responsive by wrapping them in <code>.table-responsive</code> to make them scroll horizontally up to small devices (under 768px). When viewing on anything larger than 768px wide, you will not see any difference in these tables.</div>
357       <pre class=" language-yaml"><code>table_responsive: 1
358 </code></pre>
359     </td>
360   </tr>
361   <tr>
362     <td class="col-xs-3">table_striped</td>
363     <td>
364       <div class="help-block">Add zebra-striping to any table row within the <code>&lt;tbody&gt;</code>.</div>
365       <pre class=" language-yaml"><code>table_striped: 1
366 </code></pre>
367     </td>
368   </tr>
369   </tbody>
370 </table>
371
372 ---
373
374 ### JavaScript > Modals
375
376 <table class="table table-striped table-responsive">
377   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
378   <tbody>
379   <tr>
380     <td class="col-xs-3">modal_enabled</td>
381     <td>
382       <div class="help-block">Enabling this will replace core's jQuery UI Dialog implementations with modals from the Bootstrap Framework.</div>
383       <pre class=" language-yaml"><code>modal_enabled: 1
384 </code></pre>
385     </td>
386   </tr>
387   <tr>
388     <td class="col-xs-3">modal_animation</td>
389     <td>
390       <div class="help-block">Apply a CSS fade transition to modals.</div>
391       <pre class=" language-yaml"><code>modal_animation: 1
392 </code></pre>
393     </td>
394   </tr>
395   <tr>
396     <td class="col-xs-3">modal_backdrop</td>
397     <td>
398       <div class="help-block">Includes a modal-backdrop element. Alternatively, specify <code>static</code> for a backdrop which doesn't close the modal on click.</div>
399       <pre class=" language-yaml"><code>modal_backdrop: 'true'
400 </code></pre>
401     </td>
402   </tr>
403   <tr>
404     <td class="col-xs-3">modal_keyboard</td>
405     <td>
406       <div class="help-block">Closes the modal when escape key is pressed.</div>
407       <pre class=" language-yaml"><code>modal_keyboard: 1
408 </code></pre>
409     </td>
410   </tr>
411   <tr>
412     <td class="col-xs-3">modal_show</td>
413     <td>
414       <div class="help-block">Shows the modal when initialized.</div>
415       <pre class=" language-yaml"><code>modal_show: 1
416 </code></pre>
417     </td>
418   </tr>
419   <tr>
420     <td class="col-xs-3">modal_size</td>
421     <td>
422       <div class="help-block">Defines the modal size between the default, <code>modal-sm</code> and <code>modal-lg</code>.</div>
423       <pre class=" language-yaml"><code>modal_size: ''
424 </code></pre>
425     </td>
426   </tr>
427   </tbody>
428 </table>
429
430 ---
431
432 ### JavaScript > Popovers
433
434 <table class="table table-striped table-responsive">
435   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
436   <tbody>
437   <tr>
438     <td class="col-xs-3">popover_enabled</td>
439     <td>
440       <div class="help-block">Elements that have the <code>data-toggle=&quot;popover&quot;</code> attribute set will automatically initialize the popover upon page load. <strong class='error text-error'>WARNING: This feature can sometimes impact performance. Disable if pages appear to hang after initial load.</strong></div>
441       <pre class=" language-yaml"><code>popover_enabled: 1
442 </code></pre>
443     </td>
444   </tr>
445   <tr>
446     <td class="col-xs-3">popover_animation</td>
447     <td>
448       <div class="help-block">Apply a CSS fade transition to the popover.</div>
449       <pre class=" language-yaml"><code>popover_animation: 1
450 </code></pre>
451     </td>
452   </tr>
453   <tr>
454     <td class="col-xs-3">popover_container</td>
455     <td>
456       <div class="help-block">Appends the popover to a specific element. Example: <code>body</code>. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.</div>
457       <pre class=" language-yaml"><code>popover_container: body
458 </code></pre>
459     </td>
460   </tr>
461   <tr>
462     <td class="col-xs-3">popover_content</td>
463     <td>
464       <div class="help-block">Default content value if <code>data-content</code> or <code>data-target</code> attributes are not present.</div>
465       <pre class=" language-yaml"><code>popover_content: ''
466 </code></pre>
467     </td>
468   </tr>
469   <tr>
470     <td class="col-xs-3">popover_delay</td>
471     <td>
472       <div class="help-block">The amount of time to delay showing and hiding the popover (in milliseconds). Does not apply to manual trigger type.</div>
473       <pre class=" language-yaml"><code>popover_delay: '0'
474 </code></pre>
475     </td>
476   </tr>
477   <tr>
478     <td class="col-xs-3">popover_html</td>
479     <td>
480       <div class="help-block">Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.</div>
481       <pre class=" language-yaml"><code>popover_html: 0
482 </code></pre>
483     </td>
484   </tr>
485   <tr>
486     <td class="col-xs-3">popover_placement</td>
487     <td>
488       <div class="help-block">Where to position the popover. When <code>auto</code> is specified, it will dynamically reorient the popover. For example, if placement is <code>auto left</code>, the popover will display to the left when possible, otherwise it will display right.</div>
489       <pre class=" language-yaml"><code>popover_placement: right
490 </code></pre>
491     </td>
492   </tr>
493   <tr>
494     <td class="col-xs-3">popover_selector</td>
495     <td>
496       <div class="help-block">If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added.</div>
497       <pre class=" language-yaml"><code>popover_selector: ''
498 </code></pre>
499     </td>
500   </tr>
501   <tr>
502     <td class="col-xs-3">popover_title</td>
503     <td>
504       <div class="help-block">Default title value if <code>title</code> attribute isn't present.</div>
505       <pre class=" language-yaml"><code>popover_title: ''
506 </code></pre>
507     </td>
508   </tr>
509   <tr>
510     <td class="col-xs-3">popover_trigger</td>
511     <td>
512       <div class="help-block">How a popover is triggered.</div>
513       <pre class=" language-yaml"><code>popover_trigger: click
514 </code></pre>
515     </td>
516   </tr>
517   <tr>
518     <td class="col-xs-3">popover_trigger_autoclose</td>
519     <td>
520       <div class="help-block">Will automatically close the current popover if a click occurs anywhere else other than the popover element.</div>
521       <pre class=" language-yaml"><code>popover_trigger_autoclose: 1
522 </code></pre>
523     </td>
524   </tr>
525   </tbody>
526 </table>
527
528 ---
529
530 ### JavaScript > Tooltips
531
532 <table class="table table-striped table-responsive">
533   <thead><tr><th class="col-xs-3">Setting name</th><th>Description and default value</th></tr></thead>
534   <tbody>
535   <tr>
536     <td class="col-xs-3">tooltip_enabled</td>
537     <td>
538       <div class="help-block">Elements that have the <code>data-toggle="tooltip"</code> attribute set will automatically initialize the tooltip upon page load. <strong class='error text-error'>WARNING: This feature can sometimes impact performance. Disable if pages appear to "hang" after initial load.</strong></div>
539       <pre class=" language-yaml"><code>tooltip_enabled: 1
540 </code></pre>
541     </td>
542   </tr>
543   <tr>
544     <td class="col-xs-3">tooltip_animation</td>
545     <td>
546       <div class="help-block">Apply a CSS fade transition to the tooltip.</div>
547       <pre class=" language-yaml"><code>tooltip_animation: 1
548 </code></pre>
549     </td>
550   </tr>
551   <tr>
552     <td class="col-xs-3">tooltip_container</td>
553     <td>
554       <div class="help-block">Appends the tooltip to a specific element. Example: <code>body</code>.</div>
555       <pre class=" language-yaml"><code>tooltip_container: body
556 </code></pre>
557     </td>
558   </tr>
559   <tr>
560     <td class="col-xs-3">tooltip_delay</td>
561     <td>
562       <div class="help-block">The amount of time to delay showing and hiding the tooltip (in milliseconds). Does not apply to manual trigger type.</div>
563       <pre class=" language-yaml"><code>tooltip_delay: '0'
564 </code></pre>
565     </td>
566   </tr>
567   <tr>
568     <td class="col-xs-3">tooltip_html</td>
569     <td>
570       <div class="help-block">Insert HTML into the tooltip. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.</div>
571       <pre class=" language-yaml"><code>tooltip_html: 0
572 </code></pre>
573     </td>
574   </tr>
575   <tr>
576     <td class="col-xs-3">tooltip_placement</td>
577     <td>
578       <div class="help-block">Where to position the tooltip. When <code>auto</code> is specified, it will dynamically reorient the tooltip. For example, if placement is <code>auto left</code>, the tooltip will display to the left when possible, otherwise it will display right.</div>
579       <pre class=" language-yaml"><code>tooltip_placement: 'auto left'
580 </code></pre>
581     </td>
582   </tr>
583   <tr>
584     <td class="col-xs-3">tooltip_selector</td>
585     <td>
586       <div class="help-block">If a selector is provided, tooltip objects will be delegated to the specified targets.</div>
587       <pre class=" language-yaml"><code>tooltip_selector: ''
588 </code></pre>
589     </td>
590   </tr>
591   <tr>
592     <td class="col-xs-3">tooltip_trigger</td>
593     <td>
594       <div class="help-block">How a tooltip is triggered.</div>
595       <pre class=" language-yaml"><code>tooltip_trigger: hover
596 </code></pre>
597     </td>
598   </tr>
599   </tbody>
600 </table>
601
602 [Drupal Bootstrap]: https://www.drupal.org/project/bootstrap
603 [Bootstrap Framework]: http://getbootstrap.com