Commit fd18ce46 authored by markcarver's avatar markcarver

Issue #3031415 by markcarver: Overhaul CDN Providers API

parent 6aa33213
......@@ -69,48 +69,56 @@ function _drush_bootstrap_generate_docs_settings(Theme $bootstrap) {
$output[] = '```';
// Determine the groups.
$groups = [];
$groups = [
'general' => [],
'components' => [],
'javascript' => [],
'cdn' => [],
'advanced' => [],
];
foreach ($bootstrap->getSettingPlugin() as $setting) {
// Only get the first two groups (we don't need 3rd, or more, levels).
$_groups = array_slice($setting->getGroups(), 0, 2, FALSE);
$_groups = array_filter(array_slice($setting->getGroups(), 0, 2, FALSE));
if (!$_groups) {
continue;
}
$groups[implode(' > ', $_groups)][] = $setting->getPluginDefinition();
$groups[array_keys($_groups)[0]][implode(' > ', $_groups)][] = $setting->getPluginDefinition();
}
// Generate a table of each group's settings.
foreach ($groups as $group => $settings) {
$output[] = '';
$output[] = '---';
$output[] = '';
$output[] = "### $group";
$output[] = '';
$output[] = '<table class="table table-striped table-responsive">';
$output[] = ' <thead>';
$output[] = ' <tr>';
$output[] = ' <th class="col-xs-3">Setting name</th>';
$output[] = ' <th>Description and default value</th>';
$output[] = ' </tr>';
$output[] = ' </thead>';
$output[] = ' <tbody>';
foreach ($settings as $definition) {
$output[] = ' <tr>';
$output[] = ' <td class="col-xs-3">';
$output[] = $definition['id'];
$output[] = ' </td>';
$output[] = ' <td>';
$output[] = ' <div class="help-block">';
$output[] = str_replace('&quote;', '"', wordwrap($definition['description']));
$output[] = ' </div>';
$output[] = ' <pre class=" language-yaml"><code>';
$output[] = wordwrap(Yaml::encode([$definition['id'] => $definition['defaultValue']]));
$output[] = '</code></pre>';
$output[] = ' </td>';
$output[] = ' </tr>';
foreach ($groups as $subgroups) {
foreach ($subgroups as $group => $settings) {
$output[] = '';
$output[] = '---';
$output[] = '';
$output[] = "### $group";
$output[] = '';
$output[] = '<table class="table table-striped table-responsive">';
$output[] = ' <thead>';
$output[] = ' <tr>';
$output[] = ' <th class="col-xs-3">Setting name</th>';
$output[] = ' <th>Description and default value</th>';
$output[] = ' </tr>';
$output[] = ' </thead>';
$output[] = ' <tbody>';
foreach ($settings as $definition) {
$output[] = ' <tr>';
$output[] = ' <td class="col-xs-3">';
$output[] = $definition['id'];
$output[] = ' </td>';
$output[] = ' <td>';
$output[] = ' <div class="help-block">';
$output[] = str_replace('&quote;', '"', wordwrap($definition['description']));
$output[] = ' </div>';
$output[] = ' <pre class=" language-yaml"><code>';
$output[] = wordwrap(Yaml::encode([$definition['id'] => $definition['defaultValue']]));
$output[] = '</code></pre>';
$output[] = ' </td>';
$output[] = ' </tr>';
}
$output[] = ' </tbody>';
$output[] = '</table>';
}
$output[] = ' </tbody>';
$output[] = '</table>';
}
// Ensure we have link references at the bottom.
......
......@@ -671,8 +671,8 @@ function _bootstrap_remove_class($class, array &$element, $property = 'attribute
* @endcode
*
* @see \Drupal\bootstrap\Plugin\ProviderManager
* @see \Drupal\bootstrap\Theme::getProviders()
* @see \Drupal\bootstrap\Theme::getProvider()
* @see \Drupal\bootstrap\Theme::getCdnProviders()
* @see \Drupal\bootstrap\Theme::getCdnProvider()
*/
function bootstrap_cdn_provider($provider = NULL, $reset = FALSE) {
Bootstrap::deprecated();
......@@ -746,7 +746,20 @@ function bootstrap_element_smart_description(array &$element, array &$target = N
*
* // After.
* use Drupal\bootstrap\Plugin\ProviderManager;
* $assets = ProviderManager::load($theme, $provider)->getAssets($type);
* $original_type = $type;
* $config = \Drupal::config('system.performance');
* $cdnAssets = ProviderManager::load($theme, $provider)->getCdnAssets();
* $data = [];
* $types = !isset($type) ? ['css', 'js'] : (array) $type;
* foreach ($types as $type) {
* if ($config->get("$type.preprocess") && !empty($cdnAssets['min'][$type])) {
* $data[$type] = $cdnAssets['min'][$type];
* }
* elseif (!empty($data[$type])) {
* $data[$type] = $cdnAssets[$type];
* }
* }
* $assets = is_string($original_type) ? $data[$original_type] : $data;
* @endcode
*
* @see \Drupal\bootstrap\Plugin\Provider\Custom::getAssets()
......@@ -757,7 +770,20 @@ function bootstrap_element_smart_description(array &$element, array &$target = N
*/
function bootstrap_get_cdn_assets($type = NULL, $provider = NULL, $theme = NULL) {
Bootstrap::deprecated();
return ProviderManager::load($theme, $provider)->getAssets($type);
$original_type = $type;
$assets = [];
$config = \Drupal::config('system.performance');
$cdnAssets = ProviderManager::load($theme, $provider)->getCdnAssets();
$types = !isset($type) ? ['css', 'js'] : (array) $type;
foreach ($types as $type) {
if ($config->get("$type.preprocess") && !empty($cdnAssets['min'][$type])) {
$assets[$type] = $cdnAssets['min'][$type];
}
elseif (!empty($data[$type])) {
$assets[$type] = $cdnAssets[$type];
}
}
return is_string($original_type) ? $assets[$original_type] : $assets;
}
/**
......
......@@ -18,11 +18,24 @@ can override CSS, templates, and theme processing.
#### Choose a Starterkit {#starterkit}
- @link sub_theming_cdn CDN Starterkit @endlink - uses the "out-of-the-box"
CSS and JavaScript files served by the [jsDelivr CDN].
CSS and JavaScript files served by a CDN Provider (like [jsDelivr]).
- @link sub_theming_less Less Starterkit @endlink - uses the
[Bootstrap Framework] [Less] source files and a local [Less] preprocessor.
- @link sub_theming_sass Sass Starterkit @endlink - uses the
[Bootstrap Framework] [Sass] source files and a local [Sass] preprocessor.
{.alert.alert-info} **Note** Using the "CDN Starterkit" is the preferred method
for loading Bootstrap CSS and JS on simpler sites that do not use a site-wide
CDN. Using a CDN Provider for loading Bootstrap, however, does mean that it
depends on a third-party service. There is no obligation or commitment made by
this project or these third-party CDN services that guarantees up-time or
quality of service. If you need to customize Bootstrap, you must choose one of
the Less or Sass Starterkits, compile the source code locally, and disable the
"CDN Provider" theme setting. Alternatively, you may also choose to enable a
site-wide CDN implementation for performance reasons.
{.alert.alert-warning} **Warning** All locally compiled versions of Bootstrap
will be superseded by any enabled "CDN Provider"; **do not use both**.
Once you've selected one of the above starterkits, here's how to install it:
......@@ -62,6 +75,6 @@ to customize.
[Drupal Bootstrap]: https://www.drupal.org/project/bootstrap
[Bootstrap Framework]: https://getbootstrap.com/docs/3.4/
[jsDelivr CDN]: http://www.jsdelivr.com
[jsDelivr]: http://www.jsdelivr.com
[Less]: http://lesscss.org
[Sass]: http://sass-lang.com
......@@ -13,55 +13,7 @@ SETTING_NAME: SETTING_VALUE
---
### Advanced
<table class="table table-striped table-responsive">
<thead>
<tr>
<th class="col-xs-3">Setting name</th>
<th>Description and default value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="col-xs-3">
include_deprecated
</td>
<td>
<div class="help-block">
Enabling this setting will include any <code>deprecated.php</code> file
found in your theme or base themes.
</div>
<pre class=" language-yaml"><code>
include_deprecated: 0
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
suppress_deprecated_warnings
</td>
<td>
<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>
<pre class=" language-yaml"><code>
suppress_deprecated_warnings: 0
</code></pre>
</td>
</tr>
</tbody>
</table>
---
### Advanced > CDN (Content Delivery Network)
### General > Buttons
<table class="table table-striped table-responsive">
<thead>
......@@ -73,107 +25,42 @@ suppress_deprecated_warnings: 0
<tbody>
<tr>
<td class="col-xs-3">
cdn_provider
</td>
<td>
<div class="help-block">
Choose between jsdelivr or a custom cdn source.
</div>
<pre class=" language-yaml"><code>
cdn_provider: jsdelivr
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
cdn_custom_css
</td>
<td>
<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>
<pre class=" language-yaml"><code>
cdn_custom_css:
'https://cdn.jsdelivr.net/npm/bootstrap@3.4.1/dist/css/bootstrap.css'
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
cdn_custom_css_min
</td>
<td>
<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>
<pre class=" language-yaml"><code>
cdn_custom_css_min:
'https://cdn.jsdelivr.net/npm/bootstrap@3.4.1/dist/css/bootstrap.min.css'
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
cdn_custom_js
</td>
<td>
<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>
<pre class=" language-yaml"><code>
cdn_custom_js:
'https://cdn.jsdelivr.net/npm/bootstrap@3.4.1/dist/js/bootstrap.js'
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
cdn_custom_js_min
button_colorize
</td>
<td>
<div class="help-block">
Additionally, you can provide the minimized version of the file. It will be
used instead if site aggregation is enabled.
Adds classes to buttons based on their text value.
</div>
<pre class=" language-yaml"><code>
cdn_custom_js_min:
'https://cdn.jsdelivr.net/npm/bootstrap@3.4.1/dist/js/bootstrap.min.js'
button_colorize: 1
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
cdn_jsdelivr_version
button_iconize
</td>
<td>
<div class="help-block">
Choose the Bootstrap version from jsdelivr
Adds icons to buttons based on the text value
</div>
<pre class=" language-yaml"><code>
cdn_jsdelivr_version: 3.4.1
button_iconize: 1
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
cdn_jsdelivr_theme
button_size
</td>
<td>
<div class="help-block">
Choose the example Bootstrap Theme provided by Bootstrap or one of the
Bootswatch themes.
Defines the Bootstrap Buttons specific size
</div>
<pre class=" language-yaml"><code>
cdn_jsdelivr_theme: bootstrap
button_size: ''
</code></pre>
</td>
......@@ -183,7 +70,7 @@ cdn_jsdelivr_theme: bootstrap
---
### Components > Breadcrumbs
### General > Container
<table class="table table-striped table-responsive">
<thead>
......@@ -195,44 +82,15 @@ cdn_jsdelivr_theme: bootstrap
<tbody>
<tr>
<td class="col-xs-3">
breadcrumb
</td>
<td>
<div class="help-block">
Show or hide the Breadcrumbs
</div>
<pre class=" language-yaml"><code>
breadcrumb: '1'
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
breadcrumb_home
</td>
<td>
<div class="help-block">
If your site has a module dedicated to handling breadcrumbs already, ensure
this setting is enabled.
</div>
<pre class=" language-yaml"><code>
breadcrumb_home: 0
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
breadcrumb_title
fluid_container
</td>
<td>
<div class="help-block">
If your site has a module dedicated to handling breadcrumbs already, ensure
this setting is disabled.
Uses the <code>.container-fluid</code> class instead of
<code>.container</code>.
</div>
<pre class=" language-yaml"><code>
breadcrumb_title: 1
fluid_container: 0
</code></pre>
</td>
......@@ -242,7 +100,7 @@ breadcrumb_title: 1
---
### Components > Navbar
### General > Forms
<table class="table table-striped table-responsive">
<thead>
......@@ -254,124 +112,80 @@ breadcrumb_title: 1
<tbody>
<tr>
<td class="col-xs-3">
navbar_inverse
</td>
<td>
<div class="help-block">
Select if you want the inverse navbar style.
</div>
<pre class=" language-yaml"><code>
navbar_inverse: 0
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
navbar_position
forms_has_error_value_toggle
</td>
<td>
<div class="help-block">
Determines where the navbar is positioned on the page.
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>
<pre class=" language-yaml"><code>
navbar_position: ''
forms_has_error_value_toggle: 1
</code></pre>
</td>
</tr>
</tbody>
</table>
---
### Components > Region Wells
<table class="table table-striped table-responsive">
<thead>
<tr>
<th class="col-xs-3">Setting name</th>
<th>Description and default value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="col-xs-3">
region_wells
forms_required_has_error
</td>
<td>
<div class="help-block">
Enable the <code>.well</code>, <code>.well-sm</code> or
<code>.well-lg</code> classes for specified regions.
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>
<pre class=" language-yaml"><code>
region_wells:
navigation: ''
navigation_collapsible: ''
header: ''
highlighted: ''
help: ''
content: ''
sidebar_first: ''
sidebar_second: well
footer: ''
forms_required_has_error: 0
</code></pre>
</td>
</tr>
</tbody>
</table>
---
### General > Buttons
<table class="table table-striped table-responsive">
<thead>
<tr>
<th class="col-xs-3">Setting name</th>
<th>Description and default value</th>
</tr>
</thead>
<tbody>
<tr>
<td class="col-xs-3">
button_colorize
forms_smart_descriptions
</td>
<td>
<div class="help-block">
Adds classes to buttons based on their text value.
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>
<pre class=" language-yaml"><code>
button_colorize: 1
forms_smart_descriptions: 1
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
button_iconize
forms_smart_descriptions_allowed_tags
</td>
<td>
<div class="help-block">
Adds icons to buttons based on the text value
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>
<pre class=" language-yaml"><code>
button_iconize: 1
forms_smart_descriptions_allowed_tags: 'b, code, em, i, kbd, span, strong'
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
button_size
forms_smart_descriptions_limit
</td>
<td>
<div class="help-block">
Defines the Bootstrap Buttons specific size
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>
<pre class=" language-yaml"><code>
button_size: ''
forms_smart_descriptions_limit: '250'
</code></pre>
</td>
......@@ -381,7 +195,7 @@ button_size: ''
---
### General > Container
### General > Images
<table class="table table-striped table-responsive">
<thead>
......@@ -393,15 +207,32 @@ button_size: ''
<tbody>
<tr>
<td class="col-xs-3">
fluid_container
image_responsive
</td>
<td>
<div class="help-block">
Uses the <code>.container-fluid</code> class instead of
<code>.container</code>.
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>
<pre class=" language-yaml"><code>
fluid_container: 0
image_responsive: 1
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
image_shape
</td>
<td>
<div class="help-block">
Add classes to an <code>&lt;img&gt;</code> element to easily style images
in any project.
</div>
<pre class=" language-yaml"><code>
image_shape: ''
</code></pre>
</td>
......@@ -411,7 +242,7 @@ fluid_container: 0
---
### General > Forms
### General > Tables
<table class="table table-striped table-responsive">
<thead>
......@@ -423,80 +254,75 @@ fluid_container: 0
<tbody>
<tr>
<td class="col-xs-3">
forms_has_error_value_toggle
table_bordered
</td>
<td>
<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.
Add borders on all sides of the table and cells.
</div>
<pre class=" language-yaml"><code>
forms_has_error_value_toggle: 1
table_bordered: 0
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
forms_required_has_error
table_condensed
</td>
<td>
<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.
Make tables more compact by cutting cell padding in half.
</div>
<pre class=" language-yaml"><code>
forms_required_has_error: 0
table_condensed: 0
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
forms_smart_descriptions
table_hover
</td>
<td>
<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.
Enable a hover state on table rows.
</div>
<pre class=" language-yaml"><code>
forms_smart_descriptions: 1
table_hover: 1
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
forms_smart_descriptions_allowed_tags
table_striped
</td>
<td>
<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.
Add zebra-striping to any table row within the <code>&lt;tbody&gt;</code>.
</div>
<pre class=" language-yaml"><code>
forms_smart_descriptions_allowed_tags: 'b, code, em, i, kbd, span, strong'
table_striped: 1
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
forms_smart_descriptions_limit
table_responsive
</td>
<td>
<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.
Wraps tables with <code>.table-responsive</code> to make them horizontally
scroll when viewing them on devices under 768px. When viewing on devices
larger than 768px, you will not see a difference in the presentational
aspect of these tables. The <code>Automatic</code> option will only apply
this setting for front-end facing tables, not the tables in administrative
areas.
</div>
<pre class=" language-yaml"><code>
forms_smart_descriptions_limit: '250'
table_responsive: -1
</code></pre>
</td>
......@@ -506,7 +332,7 @@ forms_smart_descriptions_limit: '250'
---
### General > Images
### Components > Breadcrumbs
<table class="table table-striped table-responsive">
<thead>
......@@ -518,32 +344,44 @@ forms_smart_descriptions_limit: '250'
<tbody>
<tr>
<td class="col-xs-3">
image_responsive
breadcrumb
</td>
<td>
<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.
Show or hide the Breadcrumbs
</div>
<pre class=" language-yaml"><code>
breadcrumb: '1'
</code></pre>
</td>
</tr>
<tr>
<td class="col-xs-3">
breadcrumb_home
</td>
<td>
<div class="help-block">
If your site has a module dedicated to handling breadcrumbs already, ensure
this setting is enabled.
</div>
<pre class=" language-yaml"><code>
image_responsive: 1