add custom colours, shouldHide

inspheric · Apr 13, 2019 · f6224ab · f6224ab
1 parent 782d444
commit f6224ab
Show file tree

Hide file tree

Showing 7 changed files with 157 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ Indicator::make('Status')
 
 The array key is the raw field value and the array value is the desired label.
 
-You can, of course use the Laravel `trans()` function.
+You can, of course use the Laravel `trans()` or `__()` functions to translate the labels.
 
 If a label is not defined for a value that appears in the field, the "unknown" label will be used (see below).
 
@@ -61,13 +61,48 @@ Indicator::make('Status')
     ->unknown('Unknown')
 ```
 
-You can, of course use the Laravel `trans()` function.
+You can, of course use the Laravel `trans()` or `__()` functions to translate the unknown label.
 
 If this is not set, an em dash will be displayed instead.
 
 This setting does not apply when `withoutLabels()` has been used. In that case, an unknown label will display with its raw value.
 
+#### Should Hide
+
+The indicator can be hidden if the field value is equal to a given value(s) or a callback:
+
+```php
+Indicator::make('Status')
+    ->shouldHide('active')
+```
+
+```php
+Indicator::make('Status')
+    ->shouldHide(['invited', 'requested'])
+```
+
+```php
+Indicator::make('Status')
+    ->shouldHide(function($value) {
+        return $value == 'inactive';
+    })
+```
+
+This is useful if you only want to highlight particular values in the grid and hide others, e.g. you want banned users to be displayed with a red indicator and label, and for active (not banned) users, you don't want the indicator displayed at all.
+
+#### Should Hide If No
+
+The indicator can be hidden if the field value is anything that PHP considers as falsy, i.e. false, 0, null or '':
+
+```php
+Indicator::make('Status')
+    ->shouldHideIfNo()
+```
+
+This is a shortcut for a common scenario for the above `shouldHide()` method.
+
 #### Colours
+##### Colour Classes
 
 Add your desired status colours:
 
@@ -83,9 +118,11 @@ Indicator::make('Status')
 
 The array key is the raw field value and the array value is the desired colour.
 
+If a colour is not specified for a status, it will be displayed as grey.
+
 The available colours are the default "base" colours from [Tailwind](https://tailwindcss.com/docs/colors), with the addition of black:
 - black (#22292F)
-- grey (#B8C2CC)
+- grey or gray (#B8C2CC)
 - red (#E3342F)
 - orange (#F6993F)
 - yellow (#FFED4A)
@@ -96,7 +133,43 @@ The available colours are the default "base" colours from [Tailwind](https://tai
 - purple (#9561E2)
 - pink (#F66D9B)
 
-If a colour is not specified for a status, it will be displayed as grey.
+Colour classes are not validated against the list above, so if you enter an invalid colour, it will fall back to grey.
+
+##### Literal Colours
+
+You can also use your own hexadecimal, RGB/RGBA or HSL/HSLA colours as in CSS:
+
+```php
+Indicator::make('Status')
+    ->colors([
+        '...' => '#ff0000',
+        '...' => 'rgb(0, 255, 0)',
+        '...' => 'rgba(0, 0, 0, 0.5)',
+        '...' => 'hsl(120, 100%, 50%)',
+        '...' => 'hsla(120, 100%, 50%, 0.5)',
+    ])
+```
+
+Literal colours are not validated, so if you enter an invalid CSS colour, it will fall back to grey.
+
+##### Additional Colour Classes
+
+If you want to specify your own colours as reusable classes, you can serve your own CSS file using Nova's Asset functionality. The classes must be prefixed with `indicator-`:
+
+```css
+.indicator-yourcolourname {
+    background: #000000;
+}
+```
+
+Which you would use in the field definition without the 'indicator-' prefix, as:
+
+```php
+Indicator::make('Status')
+    ->colors([
+        'yourstatus' => 'yourcolourname',
+    ])
+```
 
 ## Appearance
 
@@ -111,6 +184,6 @@ The field is displayed similarly to the built-in `Laravel\Nova\Fields\Boolean` f
 ### Form
 (Same as detail.)
 
-The indicator is not displayed on forms by default. If you choose to display it as a form field, the indicator is not editable and does not write back to the server, as it is intended to come from a read-only or derived model attribute.
+The indicator is not displayed on forms by default. If you choose to display it as a form field with `showOnUpdate()`, the indicator is not editable and does not write back to the server, as it is intended to come from a read-only or derived model attribute.
 
 If you do need an editable status field, you might want to add your own additional `Laravel\Nova\Fields\Select` field to your resource, referencing the same attribute name, and with `onlyOnForms()` set.
diff --git a/dist/css/field.css b/dist/css/field.css
diff --git a/dist/js/field.js b/dist/js/field.js
diff --git a/resources/js/components/FormField.vue b/resources/js/components/FormField.vue
@@ -15,12 +15,6 @@ export default {
 
     components: {
         'indicator-field': Indicator
-    },
-
-    methods: {
-        setInitialValue() {},
-        fill(formData) {},
-        handleChange(value) {}
     }
 }
 </script>
diff --git a/resources/js/components/Indicator.vue b/resources/js/components/Indicator.vue
@@ -1,8 +1,8 @@
 <template>
-    <span>
+    <span v-if="!field.shouldHide">
         <span
-            class="inline-block rounded-full w-2 h-2 mr-1"
-            :class="colorClass"
+            class="inline-block indicator-dot indicator-grey rounded-full w-2 h-2 mr-1"
+            v-bind="colorClassStyle"
         />
         <span v-if="labelText">
             {{ labelText }}
@@ -19,20 +19,28 @@ export default {
     computed: {
         labelText() {
             if (this.field.withoutLabels) {
-                return this.field.value;
+                return this.field.value
             }
             else if (this.field.labels && this.field.labels.hasOwnProperty(this.field.value)) {
-                return this.field.labels[this.field.value];
+                return this.field.labels[this.field.value]
             }
         },
-        colorClass() {
-            let color = 'grey';
+        colorClassStyle() {
+            let color = 'grey'
 
             if (this.field.colors && this.field.colors.hasOwnProperty(this.field.value)) {
-                color = this.field.colors[this.field.value];
+                color = this.field.colors[this.field.value]
             }
 
-            return `indicator-${color}`;
+            if (/^(?:#|(?:rgb|hsl)a?\()/.test(color)) {
+                return {
+                    style: `background:${color};`
+                }
+            }
+
+            return {
+                class: `indicator-${color}`
+            }
         }
     }
 }

diff --git a/resources/sass/field.scss b/resources/sass/field.scss
@@ -1,9 +1,10 @@
-// Nova Tool CSS
+// Nova Indicator Field CSS
 
 .indicator-black {
     background: #22292F;
 }
 
+.indicator-gray,
 .indicator-grey {
     background: #B8C2CC;
 }

diff --git a/src/Indicator.php b/src/Indicator.php
@@ -28,6 +28,13 @@ class Indicator extends Field
      */
     public $component = 'indicator-field';
 
+    /**
+     * The callback to be used to hide the field.
+     *
+     * @var \Closure
+     */
+    public $hideCallback;
+
     /**
      * Specify the labels that should be displayed.
      *
@@ -70,4 +77,55 @@ public function withoutLabels()
     {
         return $this->withMeta(['withoutLabels' => true]);
     }
+
+    /**
+     * Define the callback or value(s) that should be used to hide the field.
+     *
+     * @param  callable|array|mixed  $hideCallback
+     * @return $this
+     */
+    public function shouldHide($hideCallback)
+    {
+        $this->hideCallback = $hideCallback;
+
+        return $this;
+    }
+
+    /**
+     * Define that the field should be hidden if falsy (0, false, null, '')
+     *
+     * @return $this
+     */
+    public function shouldHideIfNo()
+    {
+        $this->hideCallback = function($value) {
+            return !$value;
+        };
+
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function resolveForDisplay($resource, $attribute = null)
+    {
+        parent::resolveForDisplay($resource, $attribute);
+
+        if (is_null($this->hideCallback)) {
+            return;
+        }
+
+        if (is_callable($this->hideCallback)) {
+            $shouldHide = call_user_func($this->hideCallback, $this->value, $resource);
+        }
+        elseif (is_array($this->hideCallback)) {
+            $shouldHide = in_array($this->value, $this->hideCallback, false);
+        }
+        else {
+            $shouldHide = $this->value == $this->hideCallback;
+        }
+
+        $this->withMeta(['shouldHide' => (bool) $shouldHide]);
+    }
 }