From 827a36e9ad09d2cd4553f2886359ce9750f77203 Mon Sep 17 00:00:00 2001
From: William Hearn <sylus1984@gmail.com>
Date: Fri, 8 Jul 2016 13:48:51 -0400
Subject: [PATCH] Issue #2761099 by sylus: Document @BootstrapSetting plugin

---
 docs/plugins/Setting.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 102 insertions(+), 3 deletions(-)

diff --git a/docs/plugins/Setting.md b/docs/plugins/Setting.md
index c15f360..ca79f06 100644
--- a/docs/plugins/Setting.md
+++ b/docs/plugins/Setting.md
@@ -3,7 +3,106 @@
 <!-- @ingroup -->
 # @BootstrapSetting
 
-This plugin is a little too complex to explain (for now). If you would like to
-help expand this documentation, please [create an issue](https://www.drupal.org/node/add/project-issue/bootstrap).
+- [Create a plugin](#create)
+- [Rebuild the cache](#rebuild)
+- [Customize a plugin](#customize)
 
-See the existing classes below on examples of how to implement your own.
+## Create a plugin {#create}
+
+We will use `SkipLink` as our first `@BootstrapSetting` to create. In this example we want our custom sub-theme to specify a different skip link anchor id to use in the user interface then the default of `#main-content`.
+
+Replace all following instances of `THEMENAME` with the actual machine name of your sub-theme.
+
+Create a file at `./THEMENAME/src/Plugin/Setting/General/Accessibility/SkipLink.php` with the following contents:
+
+```php
+namespace Drupal\THEMENAME\Plugin\Setting\General\Accessibility\SkipLink;
+
+use Drupal\bootstrap\Annotation\BootstrapSetting;
+use Drupal\bootstrap\Plugin\Setting\SettingBase;
+use Drupal\Core\Annotation\Translation;
+
+/**
+ * The "THEMENAME_skip_link" theme setting.
+ *
+ * @ingroup plugins_setting
+ *
+ * @BootstrapSetting(
+ *   id = "THEMENAME_skip_link",
+ *   type = "textfield",
+ *   title = @Translation("Anchor ID for the ""skip link"""),
+ *   defaultValue = "main-content",
+ *   description = @Translation("Specify the HTML ID of the element that the accessible-but-hidden ""skip link"" should link to. (<a href="":link"">Read more about skip links</a>.)", arguments = { ":link"  = "http://drupal.org/node/467976" }),
+ *   groups = {
+ *     "general" = @Translation("General"),
+ *     "accessibility" = @Translation("Accessibility"),
+ *   },
+ * )
+ */
+class SkipLink extends SettingBase {}
+```
+
+This setting can now be leveraged in the `@BootstrapPreprocess` plugin layer via `$this->theme->getSetting()` which every plugin has access to.
+
+Create a file at `./THEMENAME/src/Plugin/Preprocess/Html.php` with the following contents:
+
+```php
+
+<?php
+namespace Drupal\THEMENAME\Plugin\Preprocess;
+
+use Drupal\bootstrap\Annotation\BootstrapPreprocess;
+use Drupal\bootstrap\Utility\Element;
+use Drupal\bootstrap\Utility\Variables;
+
+/**
+ * Pre-processes variables for the "html" theme hook.
+ *
+ * @ingroup plugins_preprocess
+ *
+ * @BootstrapPreprocess("html")
+ */
+class Html extends \Drupal\bootstrap\Plugin\Preprocess\PreprocessBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function preprocess(array &$variables, $hook, array $info) {
+
+    // Assign skip link variable.
+    $variables['THEMENAME_skip_link'] = $this->theme->getSetting('THEMENAME_skip_link');
+
+    parent::preprocess($variables, $hook, $info);
+  }
+}
+```
+
+This variable can now be used in the `html.html.twig` file with the following contents:
+
+```php
+
+...
+
+    <a href="#{{ THEMENAME_skip_link_primary }}" class="visually-hidden focusable skip-link">
+      {{ 'Skip to main content'|t }}
+    </a>
+
+...
+
+```
+
+## Customize a plugin {#create}
+
+In this section we will now discuss the variety of ways Bootstrap facilitates the customization of plugins.
+
+## Rebuild the cache {#rebuild}
+
+Once you have saved, you must rebuild your cache for this new plugin to be
+discovered. This must happen anytime you make a change to the actual file name
+or the information inside the `@BootstrapSetting` annotation.
+
+To rebuild your cache, navigate to `admin/config/development/performance` and
+click the `Clear all caches` button. Or if you prefer, run `drush cr` from the
+command line.
+
+Voilà! After this, you should have a fully functional `@BootstrapSetting` plugin!
-- 
2.5.4 (Apple Git-61)