diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c8629df --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Environment Label Changelog + +_A plugin for Craft CMS 3.x to help distinguish your Craft environments ...so you don't forget where you are._ + +The format of this file is based on [Keep a Changelog](http://keepachangelog.com/). This project adheres to [Semantic Versioning](http://semver.org/). + +## 3.0.0 - 2017-12-25 + +### Added + +- Environment Label is ready for Craft 3! diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..2070650 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,9 @@ +The MIT License (MIT) + +Copyright (c) 2017 Michael Rog + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..e05ad06 --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ +# Environment Label + +_...so you don't forget where you are._ + +**A [Top Shelf Craft](https://topshelfcraft.com) creation** +in collaboration with [Kind](https://madebykind.com/) + +— Based on the original [LabelEnvironment](https://github.com/madebykind/craft.labelenvironment) plugin by [Tom Davies](https://github.com/tomdavies) + + +### TL;DR. + +The _Environment Label_ plugin adds a nice coloured banner to your CraftCMS control panel so you'll never forget what environment you're using. + +The colors and text of the environment label are configurable via the plugin config file. + +![Screenshot](docs/dev.jpg) + +* * * + + +## Installation + +Visit the _Plugin Store_ in your Craft control panel, search for **Environment Label**, and click to _Install_ the plugin. + + +## Configuration + +By default, the environment label will pull in the value of Craft's `CRAFT_ENVIRONMENT` constant, which is set to the current hostname unless you override it. + +_(In other words, out of the box, you get a red banner with white text that alerts you to the current hostname.)_ + +You can use a plugin config file to tweak the appearance and text of the environment label for each installation. + +Simply add an `environment-label.php` file to your `config` directory. + +(There is a sample plugin config included in the plugin files - `config/environment-label.php` - which you can copy and use as a starter. + +```php + true, + 'labelText' => CRAFT_ENVIRONMENT, + 'prefix' => null, + 'suffix' => null, + 'labelColor' => '#cc5643', + 'textColor' => '#ffffff', + +]; +``` + +I suggest referencing [PHP environment variables](http://php.net/manual/en/function.getenv.php), rather than using hard-coded values, to make your configuration more consistently maintainable. + +I also _highly recommend_ using the [PHP dot-env](https://github.com/vlucas/phpdotenv) package to easily set and deploy environment variables across your installations. (The [Craft starter project](https://github.com/craftcms/craft)) ships with dot-env included.) + +For example, your `environment-label.php` config file might use environment variables set by the server: + +```php + getenv('CRAFT_ENV_SHOW_LABEL'), + 'labelText' => getenv('CRAFT_ENV_LABEL_TEXT'), + +); +``` + +For added flexibility, the full text of the label will be rendered as a Twig template, so you can also include template variables if you want: + +```php + " // {{ currentUser }}", + +); +``` + + +## Changing Settings in the Control Panel + +You can also make basic changes to the text and appearance of the environment label via the plugin Settings page. + +![Settings](docs/settings.jpg) + + + +This is provided as a convenience for easily testing out the plugin, but for full customizability, you should use a plugin config file as described above. + +(Settings specified in the plugin config file will override any changes made via the Settings page in the control panel.) + + +## Twig template globals + +_Environment Label_ makes its properties available via a Twig template global variable, so you can create your own +environment label rendering in your public templates: + +```twig +{{ environmentLabel.renderedText }} +{{ environmentLabel.labelColor }} +{{ environmentLabel.textColor }} +``` + +## JavaScript globals + +_Environment Label_ also makes its properties available as JS globals on each authenticated CP page. + +```js +window.CRAFT_ENVIRONMENT +window.CRAFT_ENVIRONMENT_LABEL +``` + +## What are the system requirements? + +Craft 3.0+ and PHP 7.0+ + + +## I've found a bug. + +No you haven't. + + +## Yes, I believe I have. + +Well, alright. Please open a [GitHub Issue](https://github.com/topshelfcraft/Environment-Label/issues), and if you're feeling ambitious, submit a PR to the `dev` branch. + + +* * * + +### Contributors: + + - Plugin development: [Michael Rog](http://michaelrog.com) / @michaelrog + - Craft 2 plugin development: [Tom Davies](https://github.com/tomdavies) / @metadaptive + - Icon: [NAS](http://nasztu.com/), via [The Noun Project](https://thenounproject.com/search/?q=label&i=28588) diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..452441f --- /dev/null +++ b/composer.json @@ -0,0 +1,44 @@ +{ + "name": "topshelfcraft/environment-label", + "description": "...so you don't forget where you are.", + "type": "craft-plugin", + "version": "3.0.0", + "keywords": [ + "craft", + "cms", + "craftcms", + "craft-plugin", + "environment label" + ], + "support": { + "docs": "https://raw.githubusercontent.com/TopShelfCraft/Environment-Label", + "issues": "https://github.com/TopShelfCraft/Environment-Label/issues" + }, + "license": "MIT", + "authors": [ + { + "name": "Top Shelf Craft (Michael Rog)", + "homepage": "https://topshelfcraft.com" + } + ], + "require": { + "craftcms/cms": "^3.0.0-RC3" + }, + "autoload": { + "psr-4": { + "topshelfcraft\\environmentlabel\\": "src/" + } + }, + "extra": { + "name": "Environment Label", + "handle": "environment-label", + "schemaVersion": "1.0.0", + "hasCpSettings": true, + "hasCpSection": false, + "changelogUrl": "https://raw.githubusercontent.com/TopShelfCraft/Environment-Label/master/CHANGELOG.md", + "components": { + "label": "topshelfcraft\\environmentlabel\\services\\Label" + }, + "class": "topshelfcraft\\environmentlabel\\EnvironmentLabel" + } +} diff --git a/config/environment-label.php b/config/environment-label.php new file mode 100644 index 0000000..1590690 --- /dev/null +++ b/config/environment-label.php @@ -0,0 +1,31 @@ + getenv('ENVIRONMENT_SHOW_LABEL'), +// 'labelText' => CRAFT_ENVIRONMENT, +// 'prefixText' => '', +// 'suffixText' => '', +// 'labelColor' => getenv('ENVIRONMENT_LABEL_COLOR'), +// 'textColor' => '#ffffff', + +]; diff --git a/docs/dev.jpg b/docs/dev.jpg new file mode 100644 index 0000000..1c5b136 Binary files /dev/null and b/docs/dev.jpg differ diff --git a/docs/settings.jpg b/docs/settings.jpg new file mode 100644 index 0000000..258c307 Binary files /dev/null and b/docs/settings.jpg differ diff --git a/src/EnvironmentLabel.php b/src/EnvironmentLabel.php new file mode 100644 index 0000000..f9bc521 --- /dev/null +++ b/src/EnvironmentLabel.php @@ -0,0 +1,101 @@ +, Tom Davies + * @link https://topshelfcraft.com + * @copyright Copyright 2017, Top Shelf Craft (Michael Rog) + * @see https://github.com/topshelfcraft/Environment-Label + */ + +namespace topshelfcraft\environmentlabel; + +use Craft; +use craft\base\Plugin; +use topshelfcraft\environmentlabel\models\Settings; +use topshelfcraft\environmentlabel\services\Label; +use topshelfcraft\environmentlabel\twigextensions\EnvironmentLabelTwigExtension; + + +/** + * @author Michael Rog + * @package EnvironmentLabel + * @since 3.0.0 + * + * @property Label $label + * @property Settings $settings + * + * @method Settings getSettings() + */ +class EnvironmentLabel extends Plugin +{ + + + /* + * Static properties + */ + + /** + * @var EnvironmentLabel + */ + public static $plugin; + + + /* + * Public methods + */ + + /** + * Initializes the plugin, sets its static self-reference, registers the Twig extension, + * and adds the environment label as appropriate. + */ + public function init() + { + + parent::init(); + self::$plugin = $this; + + Craft::$app->view->registerTwigExtension(new EnvironmentLabelTwigExtension()); + + EnvironmentLabel::$plugin->label->doItBaby(); + + } + + + /* + * Protected methods + */ + + + /** + * Creates and returns the model used to store the plugin’s settings. + * + * @return \topshelfcraft\environmentlabel\models\Settings|null + */ + protected function createSettingsModel() + { + return new Settings(); + } + + + /** + * Returns the rendered settings HTML, which will be inserted into the content + * block on the settings page. + * + * @return string The rendered settings HTML + * + * @throws \Twig_Error_Loader + * @throws \yii\base\Exception + */ + protected function settingsHtml(): string + { + return Craft::$app->view->renderTemplate( + 'environment-label/settings', + [ + 'settings' => $this->getSettings() + ] + ); + } + + +} diff --git a/src/icon.svg b/src/icon.svg new file mode 100644 index 0000000..895c4bb --- /dev/null +++ b/src/icon.svg @@ -0,0 +1,29 @@ + + + + + + + + + diff --git a/src/models/Settings.php b/src/models/Settings.php new file mode 100644 index 0000000..9dba912 --- /dev/null +++ b/src/models/Settings.php @@ -0,0 +1,58 @@ +, Tom Davies + * @link https://topshelfcraft.com + * @copyright Copyright 2017, Top Shelf Craft (Michael Rog) + * @see https://github.com/topshelfcraft/Environment-Label + */ + +namespace topshelfcraft\environmentlabel\models; + +use craft\base\Model; + + +/** + * @author Michael Rog + * @package EnvironmentLabel + * @since 3.0.0 + */ +class Settings extends Model +{ + + /* + * Public properties + */ + + /** + * @var boolean + */ + public $showLabel = true; + + /** + * @var string|null + */ + public $labelColor = null; + + /** + * @var string|null + */ + public $textColor = null; + + /** + * @var string|null + */ + public $prefixText = null; + + /** + * @var string|null + */ + public $labelText = CRAFT_ENVIRONMENT; + + /** + * @var string|null + */ + public $suffixText = null; + +} diff --git a/src/services/Label.php b/src/services/Label.php new file mode 100644 index 0000000..8328250 --- /dev/null +++ b/src/services/Label.php @@ -0,0 +1,181 @@ +, Tom Davies + * @link https://topshelfcraft.com + * @copyright Copyright 2017, Top Shelf Craft (Michael Rog) + * @see https://github.com/topshelfcraft/Environment-Label + */ + +namespace topshelfcraft\environmentlabel\services; + +use topshelfcraft\environmentlabel\EnvironmentLabel; + +use Craft; +use craft\base\Component; + + +/** + * @author Michael Rog + * @package EnvironmentLabel + * @since 3.0.0 + */ +class Label extends Component +{ + + + /* + * Public methods + */ + + /** + * @return string + */ + public function getPrefixText(): string + { + return (string) EnvironmentLabel::$plugin->getSettings()->prefixText; + } + + /** + * @return string + */ + public function getSuffixText(): string + { + return (string) EnvironmentLabel::$plugin->getSettings()->suffixText; + } + + /** + * @return string + */ + public function getLabelText(): string + { + return (string) EnvironmentLabel::$plugin->getSettings()->labelText; + } + + /** + * @return string + */ + public function getRenderedText(): string + { + + $prefix = $this->getPrefixText(); + $suffix = $this->getSuffixText(); + $label = $this->getLabelText(); + $fullText = $prefix . $label . $suffix; + + $view = Craft::$app->getView(); + return $view->renderString($fullText); + + } + + /** + * @return string + */ + public function getLabelColor(): string + { + return (string) EnvironmentLabel::$plugin->getSettings()->labelColor; + } + + /** + * @return string + */ + public function getTextColor(): string + { + return (string) EnvironmentLabel::$plugin->getSettings()->textColor; + } + + /** + * @return string + */ + public function getTargetSelector(): string + { + // TODO: Make the target selector customizable via Settings (?) + return "#main-container:before"; + } + + /** + * @return string + */ + public function getCss(): string + { + + $selector = $this->getTargetSelector(); + $labelColor = $this->getLabelColor(); + $textColor = $this->getTextColor(); + + // TODO: Make the base CSS customizable/overridable via Settings (?) + $css = " + {$selector} + { + display: block; + background-color: #cc5643; + background-image: linear-gradient(#da5a47, #cc5643); + color: #ffffff; + border-bottom: 1px solid rgba(255, 255, 255, 0.1); + text-align: right; + padding: 14px 24px; + font-size: 15px; + font-weight: 700; + z-index: 9; + } + "; + + // Optionally override the label color + if (!empty($labelColor)) + { + $css .= " + html {$selector} { background-image: none; background-color: {$labelColor}; } + "; + } + + // Optionally override the label text color + if (!empty($textColor)) + { + $css .= " + html {$selector} { color: {$textColor}; } + "; + } + + return $css; + + } + + /** + * @return string + */ + public function getJs(): string + { + + $js = "window.CRAFT_ENVIRONMENT = " . json_encode(CRAFT_ENVIRONMENT) . ";"; + + $props = EnvironmentLabel::$plugin->getSettings()->getAttributes(); + $props['renderedText'] = $this->getRenderedText(); + $js .= "window.CRAFT_ENVIRONMENT_LABEL = " . json_encode($props) . ";"; + + return $js; + + } + + /** + * If we're in an authenticated CP request, the label is added to the CP, + * and some JS variables are injected for convenience debugging things in the console. + */ + public function doItBaby(): void + { + + if ( + EnvironmentLabel::$plugin->getSettings()->showLabel + && Craft::$app->getRequest()->isCpRequest + && Craft::$app->getUser()->getIdentity() + ) { + $view = Craft::$app->getView(); + $view->registerCss($this->getCss()); + $view->registerCss("{$this->getTargetSelector()} { content: '{$this->getRenderedText()}'; }"); + $view->registerJs($this->getJs()); + } + + } + + +} diff --git a/src/templates/settings.twig b/src/templates/settings.twig new file mode 100644 index 0000000..b17c052 --- /dev/null +++ b/src/templates/settings.twig @@ -0,0 +1,31 @@ +{# +This template generates the Settings form in the CP. +#} + +{# @var craft \craft\web\twig\variables\CraftVariable #} + +{% import "_includes/forms" as forms %} + +{{ forms.textField({ + label: 'Label Text', + instructions: 'Enter the environment-specific label text here. _(This text will be parsed as a Twig template, so it can include variables.)_', + id: 'labelText', + name: 'labelText', + value: settings['labelText']}) +}} + +{{ forms.colorField({ + label: 'Label Color', + instructions: 'Choose the background color for the label.', + id: 'labelColor', + name: 'labelColor', + value: settings['labelColor']}) +}} + +{{ forms.colorField({ + label: 'Text Color', + instructions: 'Choose the text color for the label.', + id: 'textColor', + name: 'textColor', + value: settings['textColor']}) +}} diff --git a/src/translations/en/environment-label.php b/src/translations/en/environment-label.php new file mode 100644 index 0000000..f584b26 --- /dev/null +++ b/src/translations/en/environment-label.php @@ -0,0 +1,11 @@ +, Tom Davies + * @link https://topshelfcraft.com + * @copyright Copyright 2017, Top Shelf Craft (Michael Rog) + * @see https://github.com/topshelfcraft/Environment-Label + */ + +return []; diff --git a/src/twigextensions/EnvironmentLabelTwigExtension.php b/src/twigextensions/EnvironmentLabelTwigExtension.php new file mode 100644 index 0000000..38aabfd --- /dev/null +++ b/src/twigextensions/EnvironmentLabelTwigExtension.php @@ -0,0 +1,66 @@ +, Tom Davies + * @link https://topshelfcraft.com + * @copyright Copyright 2017, Top Shelf Craft (Michael Rog) + * @see https://github.com/topshelfcraft/Environment-Label + */ + +namespace topshelfcraft\environmentlabel\twigextensions; + +use topshelfcraft\environmentlabel\EnvironmentLabel; + +/** + * @author Michael Rog + * @package EnvironmentLabel + * @since 3.0.0 + */ +class EnvironmentLabelTwigExtension extends \Twig_Extension implements \Twig_Extension_GlobalsInterface +{ + + /* + * Protected properties + */ + + protected $initializing = false; + + /* + * Public methods + */ + + /** + * Returns the name of the extension. + * + * @return string The extension name + */ + public function getName() + { + return 'EnvironmentLabel'; + } + + /** + * Returns a list of global variables to add to the existing list. + * + * @return array An array of global variables + */ + public function getGlobals(): array + { + + $props = EnvironmentLabel::$plugin->getSettings()->getAttributes(); + + if (!$this->initializing) + { + $this->initializing = true; + $props['renderedText'] = EnvironmentLabel::$plugin->label->getRenderedText(); + $this->initializing = false; + } + + return [ + 'environmentLabel' => $props + ]; + + } + +}