From 995738562823c3340ced500e7a6a2664da034915 Mon Sep 17 00:00:00 2001
From: William Hearn <sylus1984@gmail.com>
Date: Fri, 8 Jul 2016 15:04:30 -0400
Subject: [PATCH] Document @BootstrapSetting plugin

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

diff --git a/docs/plugins/Setting.md b/docs/plugins/Setting.md
index c15f360..8cd10f4 100644
--- a/docs/plugins/Setting.md
+++ b/docs/plugins/Setting.md
@@ -3,7 +3,87 @@
 <!-- @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)
+- [Customize a plugin](#customize)
+- [Rebuild the cache](#rebuild)
+- [Helpful Tips](#helpful-tips)
 
-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` plugin to create. In
+this example we want our sub-theme to specify a different skip link anchor id
+to change in the Theme Settings interface altering the default of
+`#main-content`.
+
+Replace all of the following instances of `THEMENAME` with the actual machine
+name of your sub-theme.
+
+Create a file at `./THEMENAME/src/Plugin/Setting/THEMENAME/Accessibility/SkipLink.php`
+with the following contents:
+
+```php
+namespace Drupal\THEMENAME\Plugin\Setting\THEMENAME\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 = {
+ *     "THEMENAME" = "THEMETITLE",
+ *     "accessibility" = @Translation("Accessibility"),
+ *   },
+ * )
+ */
+class SkipLink extends SettingBase {}
+```
+
+Helpfully Bootstrap adds a global "theme" variable added to every template
+in `Bootstrap::preprocess()`.
+
+This variable can now simply be called in the `html.html.twig` file with the
+following contents:
+
+```php
+
+...
+
+    <a href="#{{ theme.settings.THEMENAME_skip_link }}" class="visually-hidden focusable skip-link">
+      {{ 'Skip to main content'|t }}
+    </a>
+
+...
+
+```
+
+## Customize a plugin {#create}
+
+Now that we covered how to create a basic `@BootstrapSetting` plugin, we can
+now discuss how to customize a setting to fulfill a range of requirements.
+
+## 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!
+
+## Helpful tips {#helpful-tips}
+
+A helpful primer on Annotation-based plugins can be found at:
+https://www.drupal.org/node/1882526
-- 
2.5.4 (Apple Git-61)