From a66997c3c9d4d2187e95e7496ba2276b93b1037a Mon Sep 17 00:00:00 2001
From: Kazuki Nakanishi <kazuki.nakanishi.mg@hitachi.com>
Date: Wed, 29 Nov 2017 09:37:43 +0000
Subject: [PATCH] Created Design: Changeable node icon (markdown)

---
 Design:-Changeable-node-icon.md | 133 ++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 Design:-Changeable-node-icon.md

diff --git a/Design:-Changeable-node-icon.md b/Design:-Changeable-node-icon.md
new file mode 100644
index 0000000..70096ae
--- /dev/null
+++ b/Design:-Changeable-node-icon.md
@@ -0,0 +1,133 @@
+_**This is a work in progress.**_
+
+# Description
+## Node-defined icon function
+This feature allows a node to dynamically change its icon based on its configuration.
+
+### Use Cases
+Currently when you change the `Repeat` type of inject node from `none` to `interval`, a special mark is shown after node name.
+You can also change a node icon with this feature by changing an icon definition from the fixed file name to a function.
+
+none: <img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/timestamp_1.png" width=30% height=40% alt="timestamp_none">
+
+interval: <img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/timestamp_2.png" width=30% height=40% alt="timestamp_interval">
+
+The sample code is:
+
+    icon: function() {
+        if (!this.repeat && !this.crontab) {
+            return "inject.png";
+        } else {
+            return "timer.png";
+        }
+    },
+
+With the above code, when you set `interval` and click `OK` button, the node icon will change.
+
+Note that the above code is just for an explanation of this feature. This is not the actual code of an inject node.
+
+
+## User-defined icons
+A user can deploy multiple nodes with a same type on a workspace.  Although all of those nodes show a same icon now, the user may want to pick a custom icon for any node.
+This would override the icon specified by the node definition.
+
+- To be clear: this is not changing the icon in response to runtime events.
+
+### Use Cases
+#### Use case 1: Change the icon of mqtt node to the picture of an actual device so that a user can recognize which device sends data to the mqtt node at a glance.
+- similar nodes: http, websocket, tcp/udp, etc.
+
+**Before**
+
+<img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/mqtt_before.png" width=80% height=80% alt="mqtt before">
+
+
+**After**
+
+<img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/mqtt_after.png" width=80% height=80% alt="mqtt after">
+
+#### Use case 2: Use icons with different colors for comment nodes to express which one is important and which one is not.
+
+**Before**
+
+<img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/comment_before.png" width=60% height=60% alt="comment before">
+
+**After** 
+
+<img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/comment_after.png" width=60% height=60% alt="comment after">
+
+
+#### Use case 3: The icons of all function nodes on a workspace are same although each function node does a different thing.  A user can choose an appropriate icon for each node with this feature.
+- similar nodes: template, subflow
+
+# UI design
+## How to specify icon files (t.b.d.)
+There are several ways to let a user specify an icon file.
+Node-RED may have to support not only one of them but also some of them.
+
+### Proposal 1: Simple input type
+select box or text input is a good starting point.
+
+### Proposal 2: Icon tile
+
+<img src="https://github.com/Kazuki-Nakanishi/node-red/wiki/changeable_node_icon/select_icon_2.png" width=30% height=30% alt="select icon">
+
+### Proposal 3: Specify URL of icon file
+As some Node-RED servers have no internet connection such as Raspberry Pi, this proposal may not be chosen.
+
+Necessary actions to realize this proposal:
+- Contributor
+  - deploys icon files somewhere on the Internet.
+- Node-RED user
+  - specifies **URL** of an icon file on an edit node dialog.
+
+## Select icon
+User can select an icon on the node settings tab.  Once you click `OK` button, the node icon will change.
+
+## Unknown icon
+There are two cases that cause unknown icon.
+- Node-defined icon does not exist.
+  - Cause: The definition of a contribution node has a problem.
+  - Handling: Show arrow-in.png. (as is)
+- User-defined icon path does not exist although node-defined icon exists.
+  - Cause: Export a flow that uses an icon from a 3rd party module, and import the flow on the other Node-RED that does not install the 3rd party module.
+  - Handling: Show node-defined icon on behalf of user-defined icon. Show node-error.png icon on the top of the node, and surround the input field of icon in `node settings` section with red frame.
+
+# API design
+## Icon property of flow data
+Add a new property `icon` as one of core properties ([Core properties of flow format](https://github.com/node-red/node-red/wiki/Flow-Format#core-properties)).
+
+The format of `icon` property is `{module_name}/{icon_filename}`. (e.g. node-red/trigger.png, node-red-dashboard/ui_button.png)
+
+## Admin API
+This API is subject to manage icon files.
+
+- `GET /icons` - List icon files.
+
+### `GET /icons`
+
+Returns a list of all icon files available in the editor for each module.
+
+```
+{
+ "node-red": [
+  "alert.png",
+  "arduino.png",
+  "arrow-in.png",
+  ...
+ ],
+ "node-red-node-rbe": [
+  "rbe.png"
+ ]
+}
+```
+
+
+# Candidates of enhancement
+- Add "enableIconChange" parameter in settings.js to enable/disable this feature.
+  - Default value is true.
+- Enable it to choose font-awesome and material design icon.
+- Changeable node color
+- Show a node type:
+  - during mouse over
+  - in a small icon or string