diff --git a/README.md b/README.md index e301171..2984464 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,15 @@ _A slightly better color picker for CraftCMS_ -by Michael Rog -[https://topshelfcraft.com](https://topshelfcraft.com) +by Michael Rog [https://topshelfcraft.com](https://topshelfcraft.com), Aaron Waldon, and contributors -### TL;DR. +## TL;DR. -The _Hue_ fieldtype works almost identically to Craft's native Color field, with some added bonuses: +Hue has two fieldtypes: **Hue Color Picker** and **Hue Color Palette** + +The **Hue Color Picker** fieldtype works almost identically to Craft's native Color field, with some added bonuses: - You can directly edit the color code as text. - You can specify a default color in the field settings. @@ -17,77 +18,155 @@ The _Hue_ fieldtype works almost identically to Craft's native Color field, with - You can set the default color to be empty. - The `ColorModel` gives you access to nice helper variables. -![Screenshot](hue/resources/screenshots/HueFieldTypePreview.png) +![Hue Color Picker Screenshot](screenshots/HueColorPickerFieldtypePreview.png) + + + +The **Hue Color Palette** fieldtype works a lot like (and is inspired by) the [Button Box](https://github.com/supercool/buttonbox) color fields, with a few advantages. + +- You can update your colors in your config and they will instantly be in sync anywhere the field is being used. +- You can disable a color so that it cannot be selected anymore, but still allow its existing data to be available. +- You can change the value, label, and hex color information at any time, and it updates everywhere. + +![Hue Color Palette Screenshot](screenshots/HueColorPaletteFieldtypePreview.png) + * * * -### Working with Hue fields +## Working with Hue Color Picker fields + +When you access a Hue Color Picker field in your templates, its value will either be `null` (if there is no color set), or a _Hue_ColorModel_. + + + +## Working with Hue Color Palette fields + +Create a `craft/config/hue.php` config file, and define your color palettes and their colors: + +```php + [ + 'Bar Palette' => [ + 'Color 1' => [ + 'value' => 'tangerine', + 'label' => 'Tangerine', + 'hex' => '#F88D2D', + ], + 'Color 3' => [ + 'value' => 'springGreen', + 'label' => 'Spring Green', + 'hex' => '#71A850' + ], + ], + 'Backgrounds' => [ + 'bg1' => [ + 'value' => 'teal', + 'label' => 'Teal', + 'hex' => '#009383' + ], + 'bg2' => [ + 'value' => 'transparent', + 'label' => 'None', + 'hex' => '', //null is transparent + 'disabled' => true //disabled will make the color unselectable + ] + ] + ] +]; +``` + +When you create your Hue Color Palette field, you can select which palette you would like to use. The palette's colors will now be available for selection wherever the field is used. + +When you access a Hue Color Palette field in your templates, its value will either be `null` (if there is no color set), or a _Hue_ColorPaletteColorModel_. + +If you output just the field, it's `value` will be returned. For example, this: + +```twig +{{ myColorPaletteField ?? 'someDefault' }} +``` + +is the same as: -When you access a Hue field in your templates, its value will either be `null` (if there is no color set), or a _ColorModel_. +```twig +{{ myColorPaletteField.value ?? 'someDefault' }} +``` -### Using Hue without a field +## Using Hue without a field -You can create a Hue _ColorModel_ instance in your templates and work with it just like you would a Hue field. To create a Hue instance in your template, simply pass a color to the `craft.hue.createColorFromHex( '#ff80ff' )` method. +You can create a _Hue_ColorModel_ instance in your templates and work with it just like you would a Hue field. To create a Hue instance in your template, simply pass a color to the `craft.hue.createColorFromHex( '#ff80ff' )` method. Here's an example to determine whether a hex color is light or dark: ```twig - {% set hex = '#ff80ff' %} - {% set hueColor = craft.hue.createColorFromHex(hex) %} -

The color "{{ hex }}" is {{ hueColor.luma > 0.5 ? 'light' : 'dark') }}.

+{% set hex = '#ff80ff' %} +{% set hueColor = craft.hue.createColorFromHex(hex) %} +

The color "{{ hex }}" is {{ hueColor.luma > 0.5 ? 'light' : 'dark') }}.

``` -### ColorModel properties +## Hue_ColorModel + -A _ColorModel_ has the following methods/properties: +### Returned By -##### `getHex()` / `.hex` +- A Hue Color Picker fieldtype +- The `craft.hue.createColorFromHex` template method +- The `.color` property of a Hue Color Palette field -Returns the _string_ representation of the color in hexidecimal format, including the `#` at the beginning. -##### `getRgb()` / `.rgb` +### Methods/Properties -Returns the _string_ representation of the color in RGB format, i.e. `"0,255,0"` for blue. +* **`getHex()` / `.hex`** - Returns the _string_ representation of the color in hexidecimal format, including the `#` at the beginning. +* **`getRgb()` / `.rgb`** - Returns the _string_ representation of the color in RGB format, i.e. `"0,255,0"` for blue. +* **`getRed()` / `.red`** - Returns the _numeric_ value of the red channel, from 0-255. +* **`getGreen()` / `.green`** - Returns the _numeric_ value of the green channel, from 0-255. +* **`getBlue()` / `.blue`** - Returns the _numeric_ value of the blue channel, from 0-255. +* **`luma()` / `.luma`** - Returns the _numeric_ brightness of an image, from 0-1. Values closer to 0 are darker, closer to 1 are lighter. -##### `getRed()` / `.red` -Returns the _numeric_ value of the red channel, from 0-255. -##### `getGreen()` / `.green` +## Hue_ColorPaletteColorModel -Returns the _numeric_ value of the green channel, from 0-255. -##### `getBlue()` / `.blue` +### Returned By -Returns the _numeric_ value of the blue channel, from 0-255. +- A Hue Color Palette field -##### `luma()` / `.luma` -Returns the _numeric_ brightness of an image, from 0-1. Values closer to 0 are darker, closer to 1 are lighter. +### Methods/Properties +* **`.key`** - The key used to define the palette color. +* **`.value`** - The palette color's value, as set in the config. +* **`.label`** - The palette color's label, as set in the config. +* **`.hex`** - The palette color's hex value, as set in the config. +* **`.disabled`** - Whether or not the palette color is disabled, as set in the config. +* **`.color`** - Returns a Hue_ColorModel that is created from the palette color's hex value. -### What are the system requirements? + +## What are the system requirements? Craft 2.5+ and PHP 5.4+ -### I found a bug. +## I found a bug. Please open a GitHub Issue, submit a PR to the `dev` branch, or just email me to let me know. + * * * -#### Contributors: +## Contributors: - - Plugin development: [Michael Rog](http://michaelrog.com) / @michaelrog - - Plugin development: [Steve V](https://github.com/dubcanada) / @dubcanada - - Plugin development: [Aaron Waldon](https://github.com/aaronwaldon) / @aaronwaldon + - [Michael Rog](http://michaelrog.com) / @michaelrog + - [Steve V](https://github.com/dubcanada) / @dubcanada + - [Aaron Waldon](https://github.com/aaronwaldon) / @aaronwaldon diff --git a/hue/config.php b/hue/config.php new file mode 100644 index 0000000..c8e751c --- /dev/null +++ b/hue/config.php @@ -0,0 +1,7 @@ + [ + + ] +]; \ No newline at end of file diff --git a/hue/fieldtypes/HueFieldType.php b/hue/fieldtypes/HueFieldType.php index e4c7bfb..6f68f10 100755 --- a/hue/fieldtypes/HueFieldType.php +++ b/hue/fieldtypes/HueFieldType.php @@ -21,7 +21,7 @@ class HueFieldType extends BaseFieldType implements IPreviewableFieldType */ public function getName() { - return Craft::t('Hue'); + return Craft::t('Hue Color Picker'); } /** diff --git a/hue/fieldtypes/Hue_ColorPaletteFieldType.php b/hue/fieldtypes/Hue_ColorPaletteFieldType.php new file mode 100644 index 0000000..946b8e9 --- /dev/null +++ b/hue/fieldtypes/Hue_ColorPaletteFieldType.php @@ -0,0 +1,209 @@ + + * @copyright Copyright (c) 2018, Aaron Waldon + * @license MIT + * @package craft.plugins.hue + * @since 1.0 + */ +class Hue_ColorPaletteFieldType extends BaseFieldType implements IPreviewableFieldType +{ + + /** + * The fieldtype's name. + * + * @inheritDoc IComponentType::getName() + * + * @return string + */ + public function getName() + { + return Craft::t('Hue Color Palette'); + } + + /** + * The database column type. + * + * @inheritDoc IFieldType::defineContentAttribute() + * + * @return mixed + */ + public function defineContentAttribute() + { + return array(AttributeType::String, 'required' => false); + } + + /** + * The plugin settings. + * + * @return array + */ + protected function defineSettings() + { + return array( + 'palette' => AttributeType::String + ); + } + + /** + * The HTML for the settings. + * + * @return mixed + * @throws Exception + */ + public function getSettingsHtml() + { + $options = []; + $palettes = craft()->config->get('palettes', 'hue'); + if (!empty($palettes) && is_array($palettes)) + { + foreach ($palettes as $name => $colors) + { + $options[$name] = $name; + } + } + + return craft()->templates->render('hue/Hue_ColorPaletteFieldType/settings', array( + 'settings' => $this->getSettings(), + 'options' => $options + )); + } + + /** + * Returns the fieldtype's input HTML. + * + * @param string $name + * @param Hue_ColorPaletteColorModel|null $value + * + * @return string + * @throws Exception + */ + public function getInputHtml($name, $value) + { + //prep the id + $id = craft()->templates->formatInputId($name); + + //get the colors + $paletteColors = $this->getPaletteColors(); + + //include the js and css + craft()->templates->includeJsResource('hue/js/hue-palette-fields.js'); + craft()->templates->includeCssResource('hue/css/hue-palette-fields.css'); + + //add the js to initialize this element + craft()->templates->includeJs('new Craft.HueColorPalette("'.craft()->templates->namespaceInputId($name).'");'); + + return craft()->templates->render('hue/Hue_ColorPaletteFieldType/input', array( + 'id' => $id, + 'name' => $name, + 'selectedModel' => $value, + 'colors' => $paletteColors + )); + } + + /** + * Return the data that will be used in the templates and anytime this value is referenced. + * + * @param mixed $value + * @return BaseModel|Hue_ColorPaletteColorModel|null + */ + public function prepValue($value) + { + if (!empty($value)) + { + $colorData = $this->getColorFromKey($value); + + if (!empty($colorData) && is_array($colorData)) + { + $colorData['key'] = $value; + return Hue_ColorPaletteColorModel::populateModel($colorData); + } + } + + return null; + } + + /** + * Returns a color preview field. + * + * @param Hue_ColorPaletteColorModel|null $value + * @return string + */ + public function getStaticHtml($value) + { + if (!is_null($value) && !empty($value->hex)) + { + return HtmlHelper::encodeParams('
{bgColor}
', array('bgColor' => $value->hex)); + } + return ' '; + } + + /** + * Returns a color preview field. + * + * @param Hue_ColorPaletteColorModel|null $value + * + * @return string + */ + public function getTableAttributeHtml($value) + { + if (!is_null($value) && !empty($value->hex)) + { + return HtmlHelper::encodeParams('
{bgColor}
', array('bgColor' => $value->hex)); + } + + return ' '; + } + + /** + * Get the colors in this field's palette. + * + * @return array|null + */ + private function getPaletteColors() + { + $colors = null; + + //get this field's palette + $paletteKey = $this->getSettings()->palette; + + if (!is_null($paletteKey)) + { + //get the config palettes + $palettes = craft()->config->get('palettes', 'hue'); + + //set the options + if (!is_null($palettes) && is_array($palettes) && !empty($palettes[$paletteKey])) + { + $colors = (array) $palettes[$paletteKey]; + } + } + + return $colors; + } + + /** + * Return a palette color by its key. + * + * @param $key + * @return mixed|null + */ + private function getColorFromKey($key) + { + if (!is_null($key)) + { + $colors = $this->getPaletteColors(); + + if (!is_null($colors) && is_array($colors) && isset($colors[$key])) + { + return $colors[$key]; + } + } + + return null; + } +} diff --git a/hue/models/Hue_ColorPaletteColorModel.php b/hue/models/Hue_ColorPaletteColorModel.php new file mode 100644 index 0000000..ebb1216 --- /dev/null +++ b/hue/models/Hue_ColorPaletteColorModel.php @@ -0,0 +1,46 @@ +value) ? $this->value : ''; + } + + /** + * @return array + */ + protected function defineAttributes() + { + return array( + 'key' => AttributeType::String, + 'value' => AttributeType::String, + 'label' => AttributeType::String, + 'hex' => AttributeType::String, + 'disabled' => AttributeType::Bool + ); + } + + /** + * Returns a color model. + * + * @return BaseModel + */ + public function color() + { + return Hue_ColorModel::populateModel(['color' => $this->hex]); + } +} \ No newline at end of file diff --git a/hue/resources/css/hue-palette-fields.css b/hue/resources/css/hue-palette-fields.css new file mode 100644 index 0000000..ac9a574 --- /dev/null +++ b/hue/resources/css/hue-palette-fields.css @@ -0,0 +1,31 @@ +/* +Attempts to match the style of the button box color blocks. +https://github.com/supercool/buttonbox +*/ +.huePaletteColors-color { + display: inline-block; + vertical-align: middle; + border-radius: 4px; + width: 18px; + height: 18px; + border: 2px solid #fff; + margin-right: 8px; +} + +.huePaletteColors-label { + display: inline-block; + vertical-align: middle; + padding-top: 2px; +} + +.huePaletteColors-select { + display: none; +} + +.huePaletteColors-button { + -webkit-appearance: none; + border-radius: 0; + border: none; + background: none; + padding-left: 0; +} \ No newline at end of file diff --git a/hue/resources/js/hue-palette-fields.js b/hue/resources/js/hue-palette-fields.js new file mode 100644 index 0000000..273f441 --- /dev/null +++ b/hue/resources/js/hue-palette-fields.js @@ -0,0 +1,71 @@ +/** + * Highly inspired by Button Box (MIT License) + * https://github.com/supercool/buttonbox/blob/master/LICENSE.md + * + * @author Aaron Waldon '+$option.text()+''; + } + + //update the button text + this.$btn.html(buttonHtml); + } + }); +})(jQuery); diff --git a/hue/templates/Hue_ColorPaletteFieldType/input.twig b/hue/templates/Hue_ColorPaletteFieldType/input.twig new file mode 100644 index 0000000..5432ed5 --- /dev/null +++ b/hue/templates/Hue_ColorPaletteFieldType/input.twig @@ -0,0 +1,53 @@ +
+ {% if colors is not empty %} + {% set value = selectedModel.key ?? null %} + + {% set selectOptions = '' %} + {% set menuOptions = '' %} + {% set buttonHtml = 'Pick a color' %} + + {% for key, option in colors %} + {% set optionLabel = (option.label is defined ? option.label : key)|escape %} + {% set optionKey = key|escape %} + {% set optionDisabled = (option.disabled is defined ? option.disabled : false) %} + {% set optionHex = (option.hex ?? 'transparent')|escape %} + + {# set the selection option #} + {% set selectOption %} + + {% endset %} + {% set selectOptions = selectOptions~selectOption %} + + {# set the menu option #} + {% set menuOption %} +
  • + {{ optionLabel }} +
  • + {% endset %} + {% set menuOptions = menuOptions~menuOption %} + + {# update the button value #} + {% if optionKey == value or loop.first %} + {% set buttonHtml %} + {{ optionLabel }} + {% endset %} + {% endif %} + {% endfor %} + + + + + + + {% else %} + {# let the user know that we couldn't find any colors #} + +

    + {% endif %} +
    \ No newline at end of file diff --git a/hue/templates/Hue_ColorPaletteFieldType/settings.twig b/hue/templates/Hue_ColorPaletteFieldType/settings.twig new file mode 100644 index 0000000..6bf781f --- /dev/null +++ b/hue/templates/Hue_ColorPaletteFieldType/settings.twig @@ -0,0 +1,9 @@ +{% import '_includes/forms' as forms %} + +{{ forms.selectField({ + label: 'Palette', + name: 'palette', + instructions : "Choose which config palette to use.", + value: settings.palette ?? '', + options: options +}) }} \ No newline at end of file diff --git a/hue/variables/HueVariable.php b/hue/variables/HueVariable.php index 3da06ad..4132abc 100644 --- a/hue/variables/HueVariable.php +++ b/hue/variables/HueVariable.php @@ -1,25 +1,27 @@ setColor($hex); - return $model; - } - } + /** + * Creates a color from a hex value. + * + * @author Aaron Waldon setColor($hex); + return $model; + } + + return null; + } } diff --git a/screenshots/HueColorPaletteFieldtypePreview.png b/screenshots/HueColorPaletteFieldtypePreview.png new file mode 100644 index 0000000..a24a3e1 Binary files /dev/null and b/screenshots/HueColorPaletteFieldtypePreview.png differ diff --git a/hue/resources/screenshots/HueFieldTypePreview.png b/screenshots/HueColorPickerFieldtypePreview.png similarity index 100% rename from hue/resources/screenshots/HueFieldTypePreview.png rename to screenshots/HueColorPickerFieldtypePreview.png