From 6e0b05246c33f494446bab3eed8aeba5cd3ad5a3 Mon Sep 17 00:00:00 2001
From: William Hearn <sylus1984@gmail.com>
Date: Thu, 7 Jul 2016 11:48:01 -0400
Subject: [PATCH] Issue #2761099: Document @BootstrapSetting plugin

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

diff --git a/docs/plugins/Setting.md b/docs/plugins/Setting.md
index c15f360..726fe1c 100644
--- a/docs/plugins/Setting.md
+++ b/docs/plugins/Setting.md
@@ -3,7 +3,116 @@
 <!-- @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 custom groups](#groupings)
+- [Create a plugin](#create)
+- [Rebuild the cache](#rebuild)
 
-See the existing classes below on examples of how to implement your own.
+---
+
+## Create custom groups {#groupings}
+
+Before we leverage the `@BootstrapSetting` annotated discovery plugin we first must extend the SystemThemeSettings `@BootstrapForm` as we have custom groupings we wish to leverage in our own vertical tabs section that will be referenced later in `@BootstrapSetting`. This section can otherwise be skipped if instead you choose to use the default groupings.
+
+Replace all of the following instances of `THEMENAME` with the actual machine name of your sub-theme.
+
+Create a file at `./THEMENAME/src/Plugin/Form/OverrideSystemThemeSettings.php ` with the following contents:
+
+```php
+namespace Drupal\THEMENAME\Plugin\Form;
+
+use Drupal\bootstrap\Plugin\Form\SystemThemeSettings;
+use Drupal\bootstrap\Annotation\BootstrapForm;
+use Drupal\bootstrap\Bootstrap;
+use Drupal\bootstrap\Utility\Element;
+use Drupal\Core\Form\FormStateInterface;
+
+/**
+ * Implements hook_form_system_theme_settings_alter().
+ *
+ * @ingroup plugins_form
+ * @ingroup plugins_setting
+ *
+ * @BootstrapForm("system_theme_settings")
+ */
+class OverrideThemeSettings extends SystemThemeSettings  {
+
+  /**
+   * Sets up the vertical tab groupings.
+   *
+   * @param array $form
+   *   Nested array of form elements that comprise the form.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The current state of the form.
+   */
+  protected function createGroups(array &$form, FormStateInterface $form_state) {
+
+    // Provide the necessary default groups.
+    $form['THEMENAME'] = [
+      '#type' => 'vertical_tabs',
+      '#prefix' => '<h2><small>' . t('THEMENAME Bootstrap Settings') . '</small></h2>',
+      '#weight' => -10,
+    ];
+    $groups = [
+      'accessibility' => t('Accessibility'),
+      'customization' => t('Customization'),
+    ];
+    foreach ($groups as $group => $title) {
+      $form[$group] = [
+        '#type' => 'details',
+        '#title' => $title,
+        '#group' => 'THEMENAME',
+      ];
+    }
+
+    parent::createGroups($form, $form_state);
+  }
+
+}
+```
+
+## Create a plugin {#create}
+
+We will use `SkipLinkPrimary` as our first `@BootstrapSetting` to create. Replace all following instances of `THEMENAME` with the actual machine name of your sub-theme.
+
+Please also note if you didn't create the custom groups in the step above you will have to change the groupings to the defaults provided by the Bootstrap base theme.
+
+Create a file at `./THEMENAME/src/Plugin/Preprocess/Accessibility/SkipNav/SkipLinkPrimary.php` with the following contents:
+
+```php
+namespace Drupal\THEMENAME\Plugin\Setting\Accessibility\SkipNav;
+
+use Drupal\bootstrap\Annotation\BootstrapSetting;
+use Drupal\bootstrap\Plugin\Setting\SettingBase;
+use Drupal\Core\Annotation\Translation;
+
+/**
+ * The "THEMENAME_skip_link_primary" theme setting.
+ *
+ * @ingroup plugins_setting
+ *
+ * @BootstrapSetting(
+ *   id = "THEMENAME_skip_link_primary",
+ *   type = "textfield",
+ *   title = @Translation("Anchor ID for the primary ""skip link"""),
+ *   defaultValue = "wb-cont",
+ *   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 = {
+ *     "accessibility" = @Translation("Accessibility"),
+ *     "skip_nav" = @Translation("Skip Navigation"),
+ *   }
+ * )
+ */
+class SkipLinkPrimary extends SettingBase {}
+```
+
+## 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)