Allow "help wanted" messages (#516)

Author: FloEdelmann

fixtures/adb/warp-m.json

@@ -228,11 +228,25 @@
     },
     "Zoom": {
       "type": "Zoom",
-      "defaultValue": 0
+      "defaultValue": 0,
+      "capabilities": [
+        {
+          "range": [0, 255],
+          "name": "Zoom narrow…wide",
+          "helpWanted": "Correct direction?"
+        }
+      ]
     },
     "Focus": {
       "type": "Focus",
-      "defaultValue": 0
+      "defaultValue": 0,
+      "capabilities": [
+        {
+          "range": [0, 255],
+          "name": "Focus near…far",
+          "helpWanted": "Correct direction?"
+        }
+      ]
     },
     "Shutter A Rot/Index": {
       "type": "Shutter",

fixtures/american-dj/xs-400.json

@@ -9,6 +9,7 @@
     "lastModifyDate": "2017-10-16"
   },
   "manualURL": "http://adjmedia.s3-website-eu-west-1.amazonaws.com/manuals/XS%20400.pdf",
+  "helpWanted": "What is tiltMax?",
   "physical": {
     "dimensions": [169.9, 284.5, 123.6],
     "weight": 2.5,

fixtures/boomtonedj/crazy-spot-30.json

@@ -81,7 +81,8 @@
         },
         {
           "range": [57, 127],
-          "name": "Split colors"
+          "name": "Split colors",
+          "helpWanted": "Which DMX value selects which split color?"
         },
         {
           "range": [128, 189],

lib/model/Capability.mjs

@@ -66,6 +66,13 @@ export default class Capability {
     return this._jsonObject.name; // required
   }
 
+  /**
+   * @returns {?string} A string describing the help that is needed for this capability, or null if no help is needed.
+   */
+  get helpWanted() {
+    return this._jsonObject.helpWanted || null;
+  }
+
   /**
    * @returns {'start'|'center'|'end'|'hidden'} The method which DMX value to set when this capability is chosen in a menu.
    */

lib/model/Channel.mjs

@@ -266,4 +266,17 @@ export default class Channel extends AbstractChannel {
 
     return this._cache.capabilities;
   }
+
+  /**
+   * @returns {!boolean} True if help is needed in a capability of this channel, false otherwise.
+   */
+  get isHelpWanted() {
+    if (!(`isHelpWanted` in this._cache)) {
+      this._cache.isHelpWanted = this.capabilities.some(
+        cap => cap.helpWanted !== null
+      );
+    }
+
+    return this._cache.isHelpWanted;
+  }
 }

lib/model/Fixture.mjs

@@ -154,6 +154,24 @@ export default class Fixture {
     return this._jsonObject.comment || ``;
   }
 
+  /**
+   * @returns {?string} A string describing the help that is needed for this fixture, or null if no help is needed.
+   */
+  get helpWanted() {
+    return this._jsonObject.helpWanted || null;
+  }
+
+  /**
+   * @returns {!boolean} True if help is needed in this fixture (maybe in a capability), false otherwise.
+   */
+  get isHelpWanted() {
+    if (!(`isHelpWanted` in this._cache)) {
+      this._cache.isHelpWanted = this.helpWanted !== null || this.availableChannels.concat(this.templateChannels).some(ch => ch.isHelpWanted);
+    }
+
+    return this._cache.isHelpWanted;
+  }
+
   /**
    * @returns {?string} An url to an online version of the fixture's manual. Used as reference for all the information included in this fixture. Defaults to null.
    */
@@ -522,6 +540,18 @@ export default class Fixture {
     return this._cache.channelsByKey[key] || null;
   }
 
+  /**
+   * @returns {!Array.<Capability>} All available channels' and template channels' capabilities.
+   */
+  get capabilities() {
+    if (!(`capabilities` in this._cache)) {
+      const channels = this.availableChannels.concat(this.templateChannels);
+      this._cache.capabilities = concatArrayProperty(channels, `capabilities`);
+    }
+
+    return this._cache.capabilities;
+  }
+
   /**
    * @returns {!Array.<Mode>} The fixture's different modes providing different channel lists.
    */

schemas/capability.json

@@ -17,6 +17,7 @@
     "color": { "$ref": "definitions.json#/colorString" },
     "color2": { "$ref": "definitions.json#/colorString" },
     "image": { "$ref": "definitions.json#/nonEmptyString" },
+    "helpWanted": { "$ref": "definitions.json#/nonEmptyString" },
     "switchChannels": {
       "type": "object",
       "minProperties": 1,

schemas/fixture-redirect.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/OpenLightingProject/open-fixture-library/master/schemas/fixture-redirect.json",
 
-  "version": "7.1.1",
+  "version": "7.2.0",
 
   "type": "object",
   "properties": {

schemas/fixture.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/OpenLightingProject/open-fixture-library/master/schemas/fixture.json",
 
-  "version": "7.1.1",
+  "version": "7.2.0",
 
   "type": "object",
   "properties": {
@@ -65,6 +65,7 @@
     },
     "comment": { "$ref": "definitions.json#/nonEmptyMultilineString" },
     "manualURL": { "$ref": "definitions.json#/urlString" },
+    "helpWanted": { "$ref": "definitions.json#/nonEmptyString" },
     "rdm": {
       "type": "object",
       "properties": {

schemas/manufacturers.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/OpenLightingProject/open-fixture-library/master/schemas/manufacturers.json",
 
-  "version": "7.1.1",
+  "version": "7.2.0",
 
   "type": "object",
   "propertyNames": {

ui/assets/icons/comment-question-outline.svg

@@ -9,6 +9,7 @@ export default {
   'chevron-double-down': require(`./chevron-double-down.svg`),
   'chevron-double-up': require(`./chevron-double-up.svg`),
   'close': require(`./close.svg`),
+  'comment-question-outline': require(`./comment-question-outline.svg`),
   'earth': require(`./earth.svg`),
   'email': require(`./email.svg`),
   'folder-multiple': require(`./folder-multiple.svg`),

ui/assets/icons/icons.mjs

@@ -10,6 +10,7 @@ html, body {
   background: $grey-200;
   word-wrap: break-word;
   text-rendering: optimizeLegibility;
+  scroll-behavior: smooth;
 }
 
 html {
@@ -502,6 +503,20 @@ a.card, .link, .list a {
   font-size: 1.2rem;
 }
 
+.help-wanted {
+  position: relative;
+  margin: 1ex 0;
+  padding: 0.4em 0.5em 0.4em calc(1.4em + 2*0.5em);
+  background: $yellow-300;
+  border-radius: 2px;
+  min-height: 32px;
+
+  .icon {
+    margin-left: calc(-1.4em - 0.5em);
+    margin-right: 0.5em;
+  }
+}
+
 /* display mode cards in a 2-col layout and allow values to wrap below labels */
 @media (min-width: $tablet) {
   .fixture-mode {

ui/assets/styles/style.scss

@@ -12,6 +12,7 @@ $blue-600: #1e88e5;
 $blue-700: #1976d2;
 
 $yellow-300: #fff176;
+$yellow-700: #fbc02d;
 
 $orange-500: #ff9800;
 $orange-600: #fb8c00;

ui/assets/styles/vars.scss

@@ -16,7 +16,7 @@
   </app-conditional-details>
 
   renders:
-  <div>Hello</div>
+  <div class="summary">Hello</div>
 
 -->
 
@@ -89,7 +89,9 @@ export default {
       ]);
     }
 
-    return createElement(`div`, this.$slots.summary);
+    return createElement(`div`, {
+      class: `summary`
+    }, this.$slots.summary);
   }
 };
 </script>

ui/components/conditional-details.vue

@@ -206,6 +206,7 @@
 #channel-dialog {
   max-width: 700px;
   width: 80%;
+  scroll-behavior: auto;
 }
 </style>
 

ui/components/editor-channel-dialog.vue

@@ -54,6 +54,13 @@
             <span class="switching-channel-key">{{ switchChannel.key }} (channel&nbsp;{{ switchChannel.index + 1 }}) →</span>&nbsp;{{ switchChannel.to }}
           </td>
         </tr>
+
+        <tr
+          v-if="cap.helpWanted !== null"
+          :key="`cap-${index}-helpWanted`">
+          <td colspan="4" />
+          <td colspan="2"><div class="help-wanted"><app-svg name="comment-question-outline" title="Help wanted!" />{{ cap.helpWanted }}</div></td>
+        </tr>
       </template>
     </tbody>
   </table>
@@ -161,6 +168,7 @@ export default {
             color2: cap.color2 ? cap.color2.rgb().string() : null,
             image: cap.image,
             name: cap.name,
+            helpWanted: cap.helpWanted,
             menuClick: cap.menuClick,
             switchChannels
           };

ui/components/fixture-capability-table.vue

@@ -3,6 +3,11 @@
     <app-conditional-details class="channel">
       <template slot="summary">
         <app-fixture-channel-type-icon :channel="channel" />{{ unwrappedChannel.name }}<code v-if="channelKey" class="channel-key">{{ channelKey }}</code>{{ appendToHeading ? ` ${appendToHeading}` : `` }}
+        <app-svg
+          v-if="channel.isHelpWanted"
+          class="help-wanted-icon"
+          name="comment-question-outline"
+          title="Help wanted!" />
       </template>
 
       <div v-if="(unwrappedChannel instanceof FineChannel)">
@@ -99,9 +104,16 @@
 <style lang="scss" scoped>
 @import '~assets/styles/vars.scss';
 
-summary > .icon,
-div.channel > .icon {
-  margin-right: 1.2ex;
+summary, .summary {
+  & > .icon {
+    margin-right: 1.2ex;
+  }
+
+  & > .help-wanted-icon {
+    fill: $yellow-700;
+    margin-left: 0.7ex;
+    margin-right: 0;
+  }
 }
 
 ol.mode-channels {
@@ -116,7 +128,6 @@ ol.mode-channels {
 }
 </style>
 
-
 <script>
 import svg from '~/components/svg.vue';
 import conditionalDetails from '~/components/conditional-details.vue';

ui/components/fixture-channel.vue

@@ -49,6 +49,11 @@
         <span class="value"><a :href="fixture.manualURL" rel="nofollow">{{ fixture.manualURL }}</a></span>
       </section>
 
+      <section v-if="fixture.isHelpWanted" class="help-wanted">
+        <app-svg name="comment-question-outline" title="Help wanted!" /><a href="#contribute">You can help to improve this fixture definition!</a>
+        {{ fixture.helpWanted !== null ? fixture.helpWanted : `Specific questions are included in the capabilities below.` }}
+      </section>
+
       <section v-if="fixture.rdm !== null" class="rdm">
         <span class="label"><abbr title="Remote Device Management">RDM</abbr> data</span>
         <span class="value">
@@ -87,7 +92,7 @@
       <div class="clearfix" />
     </section>
 
-    <section>
+    <section id="contribute">
       <h2>Something wrong with this fixture definition?</h2>
       <p>It does not work in your lighting software or you see another problem? Then please help correct it!</p>
       <div class="grid list">
@@ -125,6 +130,27 @@
     display: inline;
   }
 }
+
+#contribute:target {
+  animation: contribute-highlight 1.5s ease;
+  animation-delay: 0.5s;
+  animation-fill-mode: backwards;
+}
+
+@keyframes contribute-highlight {
+  0% {
+    background-color: $blue-100;
+    box-shadow: 0 0 3px 5px $blue-100;
+  }
+  35% {
+    background-color: $blue-100;
+    box-shadow: 0 0 3px 5px $blue-100;
+  }
+  100% {
+    background-color: $grey-200; // page background color
+    box-shadow: 0 0 3px 5px $grey-200;
+  }
+}
 </style>
 
 <script>