www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/environment_indicator/README.md

   1 INTRODUCTION
   2 ------------
   3
   4 Designed to keep you sane while working on different copies of your site
   5 (Development, Staging, Production, etc.), Environment Indicator adds some
   6 visual cues (displaying a colored bar, changing the background color of the
   7 toolbar, and an overlay on the site's favicon) to indicate which copy of the
   8 site you are interacting with.
   9
  10 This is incredibly useful if you have multiple environments for each of your
  11 sites, and like me, are prone to forgetting which version of the site you are
  12 currently looking at.
  13
  14 Environment Indicator can also be configured to add links to the other copies of
  15 the site, in case you find yourself on the wrong one and want to quickly jump to
  16 another.
  17
  18 REQUIREMENTS
  19 ------------
  20
  21 No special requirements.
  22
  23 RECOMMENDED MODULES
  24 -------------------
  25
  26  * The Toolbar module (which ships with core):
  27    When enabled, Environment Indicator adds an item to it and changes its
  28    background color.
  29
  30 INSTALLATION
  31 ------------
  32
  33  * Install as you would normally install a contributed Drupal module. See:
  34    https://drupal.org/documentation/install/modules-themes/modules-7
  35    for further information.
  36
  37 CONFIGURATION
  38 -------------
  39
  40 In order for a user to see the environment indicator, they will need the "See
  41 environment indicator" permission.
  42
  43 Global options, such as  whether to change the background of the Toolbar, and
  44 whether to show an overlay on top of the favicon, can be configured from the
  45 settings page at admin/config/development/environment-indicator. In order for a
  46 user to change the global options, they will need the "Administer
  47 environment_indicator settings" permission.
  48
  49 Since each copy of the site should have it's own `settings.local.php` (to store
  50 database credentials without checking them into version control), you must
  51 configure Environment Indicator by adding some configuration overrides to
  52 `settings.local.php`:
  53
  54  * `$config['environment_indicator.indicator']['bg_color']`:
  55
  56    The background color for the indicator (or Toolbar). Must be a string
  57    containing a valid CSS color (including the leading # if using hexadecimal
  58    notation). See http://www.w3.org/TR/css3-color#colorunits for more
  59    information.
  60
  61    If you have the typical "development-staging-production" environments, it can
  62    be helpful to choose "stoplight colors" - green for development (to indicate
  63    that most changes are okay), yellow for staging (to indicate caution, as
  64    clients may be working on staging), and red for production (to indicate that
  65    you are making changes to a live website).
  66
  67    This configuration is optional. If you do not set it, the background color
  68    will be inherited from the CSS styles on the page.
  69
  70  * `$config['environment_indicator.indicator']['fg_color']`:
  71
  72    The text color for the environment name. Must be a string containing a valid
  73    CSS color (including the leading # if using hexadecimal notation). See
  74    http://www.w3.org/TR/css3-color#colorunits for more information.
  75
  76    To be readable, the text color must contrast with the background color. See
  77    http://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast for more
  78    information about choosing contrasting colors which meet accessibility
  79    standards.
  80
  81    This configuration is optional. If you do not set it, the text color will be
  82    inherited from the CSS styles on the page.
  83
  84  * `$config['environment_indicator.indicator']['name']`:
  85
  86    A string of text to display indicate the environment name. Note that Drupal's
  87    translation system has not yet been boostrapped when `settings.local.php` is
  88    run, so you cannot use the t() function here.
  89
  90    This configuration is optional. If you do not set it, Environment Indicator
  91    will try to find the name of the current release. If the current release name
  92    cannot be determined, then it will appear as an empty string.
  93
  94    The release name is stored as a state:
  95    ```php
  96    \Drupal::state()->set('environment_indicator.current_release', 'v1.2.44');
  97    ```
  98
  99 An example configuration could look like:
 100
 101 ```php
 102 $config['environment_indicator.indicator']['bg_color'] = '#FF5555';
 103 $config['environment_indicator.indicator']['fg_color'] = '#555533';
 104 $config['environment_indicator.indicator']['name'] = 'Staging';
 105 ```
 106
 107 To add links to switch to other environments, you must add a configuration for
 108 each environment at admin/config/development/environment-indicator/switcher.
 109 This configuration can copied to other environments using Drupal core's
 110 configuration management system. See
 111 https://www.drupal.org/documentation/administer/config for more information. In
 112 order for a user to add environment switchers, they will need the "Administer
 113 environment_indicator settings" permission.
 114
 115 TROUBLESHOOTING
 116 ---------------
 117
 118 If your configuration is in `settings.local.php`, but is not showing up, you may
 119 need to enable the file by uncommenting the appropriate lines from the bottom of
 120 `settings.php`.
 121
 122 If your configuration is in `settings.local.php`, but is not showing up for a
 123 particular user, you may need to grant that user the "See environment indicator"
 124 permission.
 125
 126 If you encounter fatal errors ("white screens of death") after making changes to
 127 `settings.local.php`, there may be a syntax error. You can check for syntax
 128 errors by running `php -l settings.local.php`.
 129
 130 If you find any bugs, have any suggestions for new features, or are interested
 131 in the latest developments to this module, please visit
 132 https://www.drupal.org/project/issues/environment_indicator for more
 133 information.
 134
 135 FAQ
 136 ---
 137
 138 Q: What happened to the feature which allowed me to save environment
 139    configurations that would be selected by looking at the request URL?
 140
 141 A: This feature has been removed from the 8.x-3.x branch.
 142
 143 Q: What happened to the feature which allowed me to position the environment
 144    indicator at the bottom of the screen?
 145
 146 A: This feature has been removed from the 8.x-3.x branch.
 147
 148 Q: What happened to the feature which allowed me to display the environment
 149    indicator in a fixed position in the browser window, regardless of where I
 150    scrolled?
 151
 152 A: This feature has been removed from the 8.x-3.x branch.
 153
 154 MAINTAINERS
 155 -----------
 156
 157 Current maintainers:
 158 * e0ipso - https://www.drupal.org/u/e0ipso
 159 * Tom Kirkpatrick (mrfelton) - https://www.drupal.org/u/mrfelton
 160
 161 This project has been sponsored by:
 162 * Lullabot (Development and maintenance for the 7.x-2.x & 8.x-2.x branches).
 163 * SystemSeed (Development and maintenance for hte 6.x-1.x & 7.x-1.x branches).