From 63d14cb6ee848a760ab2653ef298b4c25d8d9f59 Mon Sep 17 00:00:00 2001 From: Kazuhito Yokoi Date: Thu, 23 Aug 2018 18:45:57 +0900 Subject: [PATCH] Move documentation to doc directory --- README.md | 32 +-- docs/index.md | 591 ++++++++++++++++++++++++++++++++++++++++++++++ docs/index_ja.md | 598 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1208 insertions(+), 13 deletions(-) create mode 100644 docs/index.md create mode 100644 docs/index_ja.md diff --git a/README.md b/README.md index 05150d7..e3a7b64 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Node generator for Node-RED -Node generator is command line tool to generate Node-RED node modules from a number of different sources including Swagger specification and function node's source. +Node generator is command line tool to generate Node-RED node modules from several various sources including Swagger specification and function node's source. Using this tool, node developers can dramatically reduce their time to implement Node-RED node modules. ## Installation @@ -34,28 +34,34 @@ You may need to run this with `sudo`, or from within an Administrator command sh --tgz : Save node as tgz file --help : Show help -### Example 1. Create original node from function node (JavaScript code) +### Example 1. Create original node from Swagger definition -- On Node-RED flow editor, save function node to library with file name (lower-case.js). -- node-red-nodegen ~/.node-red/lib/function/lower-case.js -- cd node-red-contrib-lower-case +- node-red-nodegen http://petstore.swagger.io/v2/swagger.json +- cd node-red-contrib-swagger-petstore - sudo npm link - cd ~/.node-red -- npm link node-red-contrib-lower-case +- npm link node-red-contrib-swagger-petstore - node-red --> You can use lower-case node on Node-RED flow editor. +-> You can use swagger-petstore node on Node-RED flow editor. -### Example 2. Create original node from Swagger definition +### Example 2. Create original node from function node (JavaScript code) -- node-red-nodegen http://petstore.swagger.io/v2/swagger.json -- cd node-red-contrib-swagger-petstore +- On Node-RED flow editor, save function node to library with file name (lower-case.js). +- node-red-nodegen ~/.node-red/lib/function/lower-case.js +- cd node-red-contrib-lower-case - sudo npm link - cd ~/.node-red -- npm link node-red-contrib-swagger-petstore +- npm link node-red-contrib-lower-case - node-red --> You can use swagger-petstore node on Node-RED flow editor. +-> You can use lower-case node on Node-RED flow editor. -Note: Currently node generator supports GET and POST methods using JSON format without authentication. +## Documentation +- [Use cases](docs/index.md#use-cases) ([Japanese](docs/index_ja.md#use-cases)) +- [How to use Node generator](docs/index.md#how-to-use-node-generator) ([Japanese](docs/index_ja.md#how-to-use-node-generator)) +- [Generated files which node package contains](docs/index.md#generated-files-which-node-package-contains) ([Japanese](docs/index_ja.md#generated-files-which-node-package-contains)) +- [How to create node from Swagger definition](docs/index.md#how-to-create-node-from-swagger-definition) ([Japanese](docs/index_ja.md#how-to-create-node-from-swagger-definition)) +- [How to create node from function node](docs/index.md#how-to-create-node-from-function-node) ([Japanese](docs/index_ja.md#how-to-create-node-from-function-node)) +Note: Currently node generator supports GET and POST methods using JSON format without authentication. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d5943e0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,591 @@ +Node generator +---- +Node generator is command line tool to generate Node-RED node modules from several various sources including Swagger specification and function node's source. +Using this tool, node developers can dramatically reduce their time to implement Node-RED node modules. + +## Use cases +Node-RED is useful for rapid development without coding using existing nodes on flow library. +On the other hand, once Node-RED users develop their original nodes to realize custom processing, JavaScript and HTML coding will be time consuming task. +To solve the problem, Node generator generates original node without coding and packages it. +There are four types of use case for Node generator. + +#### (1) Connection to cloud services +http request node can easily connect to cloud services via REST API. +But in terms of marketing, instead of http request node, original node for the cloud services will be effective to increase the number of users because details of node properties, node information and documents will contribute to usability. +In general, cloud service providers publish Swagger definition with REST API for users to test it on Swagger UI. +Node generator uses this Swagger definition to create nodes for connection to cloud service. +Therefore, cloud service providers can release their original nodes without node development cost. + +#### (2) Reuse of function node as original node +Node-RED users use function node to write simple handling with JavaScript code. +But sometimes they tend to add many JavaScript codes into function node when they gradually improve their flow with try and error style development. +If this function node has useful functionality, reuse of the function node for other Node-RED users will be the best decision because other users do not need to create same functionality and are able to concentrate on the development of their other flow. +In this case, Node generator supports development of original node from existing function node. + +#### (3) Reuse of subflow as original node (future functionality) +In terms of reuse, the unit of subflow is suitable for sharing with other Node-RED users. +In the future, Node generator will support functionality for creating original node from subflow. +Node-RED users can encapsulate their flow as original nodes. +For example, both template node which has authentication header and http request node which has URL is a typical pair which a lot of Node-RED users use to connect to cloud services. +Node generator can generate original nodes from subflow which has the flow. +And Node-RED users can easily share their original nodes with other Node-RED users via flow library. + +#### (4) Connection to devices (future functionality) +Web of Things (WoT) is standard specification to connect IoT devices. +Node generator will support Web of Things description to create original nodes. +Currently, there are [a slide](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/images/Plugfest-Bundang-WoT.pdf) and [screenshot](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/result-hitachi.md) of the prototype implementation on GitHub. + +## How to use Node generator +To install Node generator to local environment, users need to input the following "npm install" command on command prompt (Windows) or terminal (macOS/Linux). +Because the command execution needs root permission, "sudo" is required before "npm install" command on macOS or Linux environment. + + npm install -g node-red-nodegen + +Current version of node generator supports function node and Swagger definition as source file. +Simply, Node generator command, node-red-nodegen converts to node the file which is specified in argument of command as follows. + + node-red-nodegen -> The command tool outputs the node from the source file + +The following documentations explains details of method to create node from two types of source file. + + - [How to create node from Swagger definition](#how-to-create-node-from-swagger-definition) + - [How to create node from function node](#how-to-create-node-from-function-node) + +## Generated files which node package contains +The following is typical directory structure of node package generated by Node generator. +After generating the node, Node-RED users can install it to local Node-RED environment or publish it on flow library without additional development. + + - node.js <- JavaScript file for node processing + - node.html <- HTML file for node property UI + - icons + |-icon.png <- Icon file for node + - package.json <- node package information + - README.md <- Explanation file for node package + - LICENSE <- License information of node + - test + |-node_spec.js <- Test case for node + - locales + |-en-US + |-node.json <- Message catalog for English language + |-ja + |-node.json <- Message catalog for Japanese language + |-zh-CN + |-node.json <- Message catalog for Chinese language + |-de-DE + |-node.json <- Message catalog for German language + +## How to create node from Swagger definition +You can specify URL or file path of Swagger definition as the first argument of node-red-nodegen command. + +(1) Generate node using node-red-nodegen command + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json + +Node-RED users typically import generated node to pallet of Node-RED flow editor using the following procedures. + +(2) Change directory to generated node's directory + + cd node-red-contrib-swagger-petstore + +(3) Prepare symbolic link + + sudo npm link + +(4) Change current directory to Node-RED home directory (Typically, Node-RED home directory is ".node-red" under home directory) + + cd ~/.node-red + +(5) Create symbolic link + + npm link node-red-contrib-swagger-petstore + +(6) Start Node-RED + + node-red + +After starting Node-RED, you can see generated node on palette of Node-RED flow editor. +If you want to customize generated node, the following procedures and command line options will be helpful. + +#### Module name +Node generator uses "node-red-contrib-" as default prefix of module name. +Therefore, module name is "node-red-contrib-swagger-petstore" when node name is "swagger-petstore". +If you want to change the default module name, you can specify module name using --module or --prefix option. + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --module node-red-node-swagger-petstore + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --prefix node-red-node + +#### Node name +In the case of node generated from Swagger definition, "info.title" value in Swagger definition is used as generated node's name. +Node generator will replace upper case characters and spaces with hyphen to convert appropriate name for npm module and Node-RED node. + +##### Example of swagger definition +``` +{ + "swagger": "2.0", + "info": { + "description": "This is a sample server Petstore server.", + "version": "1.0.0", + "title": "Swagger Petstore", <- Node generator converts this value to "swagger-petstore" and uses it as node name. + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "host": "petstore.swagger.io", + "basePath": "/v2", + ... +} +``` + +If you want to change the default name, you can set node name using --name option. +Especially, user needs to specify node name using --name option when "info.title" value contains a double-byte character instead of alphabet and number because Node generator cannot create node correctly. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --name new-node-name + +#### Version +As the default, Node generator uses "info.version" value as the module version number. + +##### Example of swagger definition +``` +{ + "swagger": "2.0", + "info": { + "description": "This is a sample server Petstore server.", + "version": "1.0.0", <- Node generator uses this version number as the module version number. + "title": "Swagger Petstore", + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "host": "petstore.swagger.io", + "basePath": "/v2", + ... +} +``` + +When you update the version number of module without incrementation of swagger definition version number, you need to specify --version option. +Especially, conflict error will occur when you publish the module which has same version number as previous published module using "npm publish" command. +In this case, the --version option need to be specified to update the version number of module. + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --version 0.0.2 + +#### Keywords +--keywords is useful option for keywords of module on flow library. +On flow library website, visitors will search the module using the keywords. +For example, if you want use "petstore" as a keyword, you can specify the word using --keywords option. +As the default, node generator uses "node-red-nodegen" as keyword. + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore + +To add more than two keywords, you can also use comma separated keywords. + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore,petshop + +When "--keywords node-red" is specified before publishing the generated node, your node will be registered on flow library and you can install the node via Node-RED flow editor. + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore,petshop,node-red + +#### Category +On palette of Node-RED flow editor, generated node is in function category as the default. +To change the category or use product name, you can use --category option. +For example, the generated node which the following command outputs will be in "analysis" category on Node-RED flow editor. + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --category analysis + +#### Node icon +Currently, node generator does not support --icon option to specify icon file for generated node. +Therefore, you need to change icon file manually. +(--icon option will be supported in the future version of Node generator) +Because the default icon file is in "icons/icon.png", you need to overwrite the icon file. + + mv new-icon.png node-red-contrib-swagger-petstore/icons/icon.png + +As official documentation explains, icon should have white on a transparent background. +And icon size should also be 20 x 30. + +#### Node color +Current version of node generator does not also support --color option to specify color of the generated node. +Because of that, you need to modify color setting of generated node manually. +(--color option will be supported in the future version of Node generator) + + vi node-red-contrib-swagger-petstore/node.html + +```html: + +``` + +#### README +To explain details of node, you need to write documentation in README.md file. +The documentation will be used in flow library web site if you publish your node on flow library. +Because node generator outputs template of README.md, you just modify the file. + + vi node-red-contrib-swagger-petstore/README.md + +``` +node-red-contrib-swagger-petstore +===================== + +Node-RED node for swagger-petstore + +This is a sample server Petstore server. + +Install +------- + +Run the following command in your Node-RED user directory - typically `~/.node-red` + + npm install node-red-contrib-swagger-petstore +``` + +#### Test cases +Test cases are the most important to maintain the quality of generated node in production use. +Node generator outputs template file of test cases into the file, "test/node_spec.js" under generated directory. +You need to modify three lines, (1),(2) and (3) in the test case file. +If Swagger definition does not contain host name in "info" value, you need to write host name as (4) in each test case manually. + + vi node-red-contrib-swagger-petstore/test/node_spec.js + +```JavaScript: + it('should handle addPet()', function (done) { + var flow = [ + { id: 'n1', type: 'swagger-petstore', name: 'swagger-petstore', + method: 'addPet', + addPet_body: '', // (1) define node properties + wires: [['n3']] + }, + { id: 'n3', type: 'helper' } + ]; + helper.load(node, flow, function () { + var n3 = helper.getNode('n3'); + var n1 = helper.getNode('n1'); + n3.on('input', function (msg) { + try { + msg.should.have.property('payload', { "id": 4513 }); // (3) define output message + done(); + } catch (e) { + done(e); + } + }); + n1.receive({ payload: { "id": 4513 } }); // (2) define input message + }); + }); +``` + +In this example, the generated node send data, "{ "id": 4513 }" to pet store REST API. +And then, REST API returns same data, "{ "id": 4513 }". +Therefore, input and output messages are same. +You can run the test cases using "npm test" command under the generated directory. + + cd node-red-contrib-swagger-petstore + npm install + npm test + +#### Message catalogs +As default, Node generator outputs template files of English, Japanese, Chinese and German languages. +When you want to support internationalization of node properties, you need to add language messages of parameters into the files. + + vi node-red-contrib-swagger-petstore/locales/ja + +``` +{ + "SwaggerPetstore": { + "label": { + "service": "サービス", + "method": "メソッド", + "host": "ホスト", + "header": "ヘッダ", + "value": "値", + "isQuery": "クエリ" + }, + "status": { + "requesting": "要求中" + }, + "parameters": { + "addPet": "addPet", + "body": "body", + "updatePet": "updatePet", + "findPetsByStatus": "findPetsByStatus", + ... + "optionalParameters": "任意項目" + } + } +} +``` + +If your node does not support some languages, you can delete the language directory. +(For example, delete "zh-CN" directory, if you do not want to support Chinese language) + +## How to create node from function node +After writing JavaScript code in function node, you can export the JavaScript code as js file using "Save to Library..." menu in function node. +Because node generator uses function node name as generated node's name, it is better to input node name before exporting the function node. +Node-RED saves the js file to the directory, "/.node-red/lib/functions/". +Therefore, you need to specify the directory and file path as the argument of command line. + +(1) Export function node as js file + +![Export function node](library.png) + +(2) Generate node using node-red-nodegen command + + node-red-nodegen ~/.node-red/lib/function/lower-case.js + +Node-RED users typically import generated node to pallet of Node-RED flow editor using the following procedures. + +(3) Change current directory to generated node's directory + + cd node-red-contrib-lower-case + +(4) Prepare symbolic link + + sudo npm link + +(5) Change directory to Node-RED home directory (Typically, Node-RED home directory is ".node-red" under home directory) + + cd ~/.node-red + +(6) Create symbolic link + + npm link node-red-contrib-lower-case + +(7) Start Node-RED + + node-red + +After starting Node-RED, you can see generated node on palette of Node-RED flow editor. +If you want to customize generated node, the following procedures and command line options will be helpful. + +#### Module name +Node generator uses "node-red-contrib-" as default prefix of module name. +Therefore, module name is "node-red-contrib-lower-case" when node name is "lower-case". +If you want to change the default module name, you can specify module name using --module or --prefix option. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --module node-red-node-lower-case + node-red-nodegen ~/.node-red/lib/function/lower-case.js --prefix node-red-node + +#### Node name +In the case of function node, node name in function node is used as generated node's name. +If you want to change the default name, you can set node name using --name option. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --name new-node-name + +#### Version +As the default, the version number of module is always "0.0.1". +When you update the version number of module, you need to specify --version option. +Especially, conflict error will occur when you publish the module which has same version number as previous published module using "npm publish" command. +In this case, the --version option need to be specified to update the version number of module. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --version 0.0.2 + +#### Keywords +--keywords is useful option for keywords of module on flow library. +On flow library website, visitors will search the module using the keywords. +For example, if you want use "lower-case" as a keyword, you can specify the word using --keywords option. +As the default, node generator uses "node-red-nodegen" as keyword. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --keywords lower-case + +To add more than two keywords, you can also use comma separated keywords. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --keywords lower-case,function + +When "--keywords node-red" is specified before publishing the generated node, your node will be registered on flow library and you can install the node via Node-RED flow editor. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --keywords lower-case,function,node-red + +#### Category +On palette of Node-RED flow editor, generated node is in function category as the default. +To change the category or use product name, you can use --category option. +For example, the generated node which the following command outputs will be in "analysis" category on Node-RED flow editor. + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --category analysis + +#### Node icon +Currently, node generator does not support --icon option to specify icon file for generated node. +Therefore, you need to change icon file manually. +(--icon option will be supported in the future version of Node generator) +Because the default icon file is in "icons/icon.png", you need to overwrite the icon file. + + mv new-icon.png node-red-contrib-lower-case/icons/icon.png + +As official documentation explains, icon should have white on a transparent background. +And icon size should also be 20 x 30. + +#### Node color +Current version of node generator does not also support --color option to specify color generated node. +Because of that, you need to modify color setting of generated node manually. +(--color option will be supported in the future version of Node generator) + + vi node-red-contrib-lower-case/node.html + +```html: + +``` + +"RED.nodes.registerType()" has color setting, "color:"#C0DEED"". +To change the node's color, you need to change "#C0DEED" to other hexadecimal numbers which represent node's color. + +#### Node's information in info tab +Node generator outputs template of node information into node.html file. +You need to modify the template along with your node. +(Node developer will be able to use node description property to use node information in the future version of Node-RED and node generator) + + vi node-red-contrib-lower-case/node.html + +```html: + +``` + +In the template, there are summary of node and three sections. +Inputs section has properties information of inputted messages. +Outputs section has properties explanation of outputted messages. +Details section will contain additional information of the generated node. + +#### README +To explain details of node, you need to write documentation in README.md file. +The documentation will be used in flow library web site if you publish your node on flow library. +Because node generator outputs template of README.md, you just modify the file. + + vi node-red-contrib-lower-case/README.md + +``` +node-red-contrib-lower-case +===================== + +Node-RED node for lower case + +Install +------- + +Run the following command in your Node-RED user directory - typically `~/.node-red` + + npm install node-red-contrib-lower-case +``` + +#### Test cases +Test cases are the most important to maintain the quality of generated node in production use. +Node generator outputs template file of test cases into the file, "test/node_spec.js" under generated directory. +You need to modify two lines, (1) and (2) in the test case file. + + vi node-red-contrib-lower-case/test/node_spec.js + +```JavaScript: + it('should have payload', function (done) { + var flow = [ + { id: "n1", type: "lower-case", name: "lower-case", wires: [["n2"]] }, + { id: "n2", type: "helper" } + ]; + helper.load(node, flow, function () { + var n2 = helper.getNode("n2"); + var n1 = helper.getNode("n1"); + n2.on("input", function (msg) { + msg.should.have.property('payload', 'abcd'); // (2) define output message + done(); + }); + n1.receive({ payload: "AbCd" }); // (1) define input message + }); + }); +``` + +In this example, the generated node converts upper case characters to lower case characters. +Therefore, input message is "AbCd" and output message is "abcd". +You can run the test cases using "npm test" command under the generated directory. + + cd node-red-contrib-lower-case + npm install + npm test diff --git a/docs/index_ja.md b/docs/index_ja.md new file mode 100644 index 0000000..e89afa8 --- /dev/null +++ b/docs/index_ja.md @@ -0,0 +1,598 @@ +ノードジェネレータ +---- +ノードジェネレータは、SwaggerやfunctionノードなどのソースコードからNode-REDのノードを生成するためのコマンドラインツールです。 +このツールを使用すると、ノード開発者はNode-REDノードの実装時間を大幅に短縮できます。 + + +## 利用ケース +Node-REDは、フローライブラリに用意されているノードを使用し、コーディングすることなく迅速な開発ができることが利点です。 +しかし、独自の処理を実現するために、Node-REDユーザがノードを開発すると、JavaScriptとHTMLのコーディングに時間がかかり、迅速な開発ができるNode-REDの利点が薄れてしまいます。 +この問題を解決するために、ノードジェネレータはコーディングなしで独自のノードを自動生成し、パッケージ化します。 +以下の通り、ノードジェネレータには4つの利用ケースがあります。 + +#### (1) クラウドサービスへの接続 +httpリクエストノードは、REST API経由でクラウドサービスに簡単に接続できます。 +しかし、マーケティングの観点から考えると、httpリスエストの代替として、クラウドサービス向けに専用に独自に開発したノードを公開することは、クラウドサービスのユーザ数を増やすために効果的です。 +なぜなら、クラウドサービスとの接続方法を詳細に解説したのノードプロパティ、ノード情報、ドキュメントがユーザビリティに貢献するためです。 +一般的に、クラウドサービスプロバイダは、ユーザーがSwagger UIでREST APIをテストできるよう、Swagger定義を公開しています。 +ノードジェネレータは、このSwagger定義を使用して、クラウドサービスへの接続用のノードを生成します。 +従って、クラウドサービスプロバイダーは、ノード開発コストなしで独自のノードを公開できるようになります。 + +#### (2) functionノードを独自のノードとして再利用 +Node-REDユーザは、functionノードにJavaScriptコードを記述し、簡単な処理を動作させています。 +しかし、試行錯誤を繰り返す開発を行い、フローを徐々に改善すると、大量のJavaScriptコードをfunctionノードに追加してしまうことがあります。 +この時、functionノードに便利な機能が備わっている場合、他のNode-REDユーザにこのfunctionノードを共有し、再利用をしてほしいというニーズが挙がってきます。 +なぜなら、ノードを再利用することで、他のNode-REDユーザは同じ機能を開発する必要がなく、フローの開発に集中できるためです。 +ノードジェネレータは、この様なニーズを満たすために、既存のfunctionノードから独自のノードの開発する作業を助けます。 + +#### (3) サブフローを独自のノードとして再利用（将来機能） +他のNode-REDユーザーとフローを共有するには、サブフローの単位で行うのが最適です。 +将来、ノードジェネレータは、サブフローから独自のノードを生成する機能をサポートします。 +Node-REDユーザは、サブフローを独自のノードとしてカプセル化できるようになります。 +例えば、認証ヘッダーを持つtemplateノードとURLを持つhttp requestノードは、多くのNode-REDユーザーがクラウドサービスに接続するために使用する典型的なペアです。 +ノードジェネレータは、この様なフローを含むサブフローから独自のノードを生成できます。 +そして、Node-REDユーザは、フローライブラリを介して、生成したノードを他のNode-REDユーザと容易に共有できます。 + +#### (4) デバイスへの接続（将来機能） +Web of Things（WoT）は、IoTデバイスを接続するための標準仕様です。 +ノードジェネレータはWeb of Thingsの記述から独自のノードを開発することを支援します。 +現在のところ、GitHub上にプロトタイプ実装の[スライド](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/images/Plugfest-Bundang-WoT.pdf)と[スクリーンショット](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/result-hitachi.md)があります。 + + +## ノードジェネレータの使い方 +ノードジェネレータをローカル環境にインストールするには、コマンドプロンプト（Windows）またはターミナル（macOS / Linux）で次の「npm install」コマンドを入力します。 +コマンド実行にはroot権限が必要なため、macOSまたはLinux環境では "npm install"コマンドの前に "sudo"が必要です。 + + npm install -g node-red-nodegen + +ノードジェネレータの現在のバージョンは、functionノードとSwagger定義をソースファイルとしてサポートしています。 +ノードジェネレータのコマンド、node-red-nodegenは、以下のようにコマンドの引数で指定されたファイルをノードに変換します。 + + node-red-nodegen -> コマンドツールは、ソースファイルからノードを出力します + +以降のドキュメントでは、2種類のソースファイルからノードを生成する方法の詳細について説明します。 + + - [Swagger定義からノードを生成する方法](#how-to-create-node-from-swagger-definition) + - [functionノードからノードを生成する方法](#how-to-create-node-from-function-node) + + +## ノードパッケージに含まれる生成ファイル +ノードジェネレータによって自動生成されるノードパッケージの典型的なディレクトリ構造は以下の通りです。 +Node-REDユーザは、自動生成されたノードをローカルNode-RED環境にインストールしたり、追加開発なくフローライブラリに公開したりできます。 + + - node.js <- ノード処理用のJavaScriptファイル + - node.html <- ノードプロパティUIのHTMLファイル + - icons + |-icon.png <- ノードのアイコンファイル + - package.json <- ノードパッケージ情報 + - README.md <- ノードパッケージの説明ファイル + - LICENSE <- ノードのライセンス情報 + - test + |-node_spec.js <- ノードのテストケース + - locales + |-en-US + |-node.json <- 英語のメッセージカタログ + |-ja + |-node.json <- Message catalog for Japanese language + |-zh-CN + |-node.json <- 日本語のメッセージカタログ + |-de-DE + |-node.json <- ドイツ語のメッセージカタログ + + +## Swagger定義からノードを生成する方法 +node-red-nodegenコマンドの最初の引数として、Swagger定義のURLまたはファイルパスを指定できます。 + +(1) node-red-nodegenコマンドを使用してノードを生成する + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json + +Node-REDユーザは通常、以下の手順で生成されたノードをNode-REDフローエディタのパレットにインポートします。 + +(2) 生成されたノードのディレクトリにディレクトリを変更する + + cd node-red-contrib-swagger-petstore + +(3) シンボリックリンクを準備する + + sudo npm link + +(4) カレントディレクトリをNode-REDのホームディレクトリに変更します（通常、Node-REDのホームディレクトリは、ホームディレクトリの下の".node-red"です） + + cd ~/.node-red + +(5) シンボリックリンクを作成する + + npm link node-red-contrib-swagger-petstore + +(6) Node-REDを起動する + + node-red + +Node-REDを起動すると、Node-REDフローエディタのパレットに生成されたノードが表示されます。 +生成されたノードをカスタマイズする場合は、次の手順やコマンドラインオプションが役立ちます。 + +#### モジュール名 +ノードジェネレータは、モジュール名のデフォルトのプレフィックスとして "node-red-contrib-"を使用します。 +従って、ノード名が "swagger-petstore"の場合、モジュール名は "node-red-contrib-swagger-petstore"となります。 +デフォルトのモジュール名を変更したい場合は、--moduleまたは--prefixオプションを使用してモジュール名を指定できます。 + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --module node-red-node-swagger-petstore + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --prefix node-red-node + +#### ノード名 +Swagger定義から生成されたノードの場合、Swagger定義の "info.title"値が生成ノードの名前として使用されます。 +ノードジェネレータは、npmモジュールとNode-REDノードで利用できる適切な名前を変換するために、大文字とスペースをハイフンに置き換えます。 + +##### Swagger定義の例 +``` +{ + "swagger": "2.0", + "info": { + "description": "This is a sample server Petstore server.", + "version": "1.0.0", + "title": "Swagger Petstore", <- ノードジェネレータはこの値を「swagger-petstore」に変換し、ノード名として使用します。 + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "host": "petstore.swagger.io", + "basePath": "/v2", + ... +} +``` + +デフォルト名を変更する場合は、--nameオプションを使用してノード名を設定できます。 +特に、"info.title"の値にアルファベットと数字の代わりに2バイト文字が含まれる場合、ノードジェネレータがノードを正しく生成できないため、--nameオプションを使用してノード名を指定する必要があります。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --name new-node-name + +#### バージョン +デフォルトでは、ノードジェネレータはモジュールのバージョン番号として "info.version"値を使用します。 + +##### Swagger定義の例 +``` +{ + "swagger": "2.0", + "info": { + "description": "This is a sample server Petstore server.", + "version": "1.0.0", <- ノードジェネレータはこのバージョン番号をモジュールバージョン番号として使用します。 + "title": "Swagger Petstore", + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "host": "petstore.swagger.io", + "basePath": "/v2", + ... +} +``` + +Swagger定義のバージョン番号をインクリメントせずにモジュールのバージョン番号を更新する場合は、--versionオプションを指定する必要があります。 +特に、"npm publish"コマンドを使用して、以前公開したモジュールと同じバージョン番号を持つモジュールを公開すると、競合エラーが発生します。 +この場合、モジュールのバージョン番号を更新するには、--versionオプションを指定する必要があります。 + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --version 0.0.2 + +#### キーワード +--keywordsは、フローライブラリ上のモジュールのキーワードのために用いる便利なオプションです。 +フローライブラリのWebサイトで、訪問者はこのキーワードを使用してモジュールを検索します。 +例えば、 "petstore"をキーワードとして使用する場合は、--keywordsオプションを使用して単語を指定できます。 +デフォルトでは、ノードジェネレータは "node-red-nodegen"をキーワードとして使用します。 + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore + +2つ以上のキーワードを追加するには、コンマ区切りのキーワードを使用することもできます。 + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore,petshop + +生成されたノードを公開する前に "--keywords node-red"を指定すると、ノードはフローライブラリに登録され、Node-REDフローエディタでノードをインストールできます。 + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore,petshop,node-red + +#### カテゴリ +Node-REDフローエディタのパレットでは、生成されたノードはデフォルトとして機能カテゴリに配置されます。 +カテゴリを変更したり、カテゴリ名に製品名を使用したりしたい場合は、--categoryオプションを用います。 +例えば、次のコマンドが出力するノードは、Node-REDフローエディタの「分析」カテゴリに配置されます。 + + node-red-nodegen http://petstore.swagger.io/v2/swagger.json --category analysis + +#### ノードアイコン +現在、ノードジェネレータは、生成されたノードのアイコンファイルを指定するための--iconオプションをサポートしていません。 +従って、アイコンファイルを手動で変更する必要があります。 +（--iconオプションは、将来のバージョンのノードジェネレータでサポートされます） +デフォルトのアイコンファイルは "icons/icon.png"にあるため、このアイコンファイルを上書きします。 + + mv new-icon.png node-red-contrib-swagger-petstore/icons/icon.png + +公式ドキュメントで説明されているように、アイコンは透明な背景上に白色で表示する必要があります。 +アイコンのサイズも20 x 30でなければなりません。 + +#### ノードの色 +現在のバージョンのノードジェネレータは、生成されたノードの色を指定する--colorオプションもサポートしていません。 +そのため、生成されたノードの色設定を手動で変更する必要があります。 +（--colorオプションは、ノードジェネレータの将来のバージョンでサポートされます） + + vi node-red-contrib-swagger-petstore/node.html + +```html: + +``` + +#### README +ノードの詳細を説明するには、README.mdファイルにドキュメントを書く必要があります。 +フローライブラリにノードを公開すると、ドキュメントはフローライブラリのWebサイトで使用されます。 +ノードジェネレータはREADME.mdのテンプレートを出力するので、ファイルを変更するだけです。 + + vi node-red-contrib-swagger-petstore/README.md + +``` +node-red-contrib-swagger-petstore +===================== + +Node-RED node for swagger-petstore + +This is a sample server Petstore server. + +Install +------- + +Run the following command in your Node-RED user directory - typically `~/.node-red` + + npm install node-red-contrib-swagger-petstore +``` + +#### テストケース +テストケースは、本番環境で利用するノードの品質を維持するために最も重要です。 +ノードジェネレータは、生成されたディレクトリの下にあるファイル "test/node_spec.js"にテストケースのテンプレートファイルを出力します。 +テストケースファイルでは、以下の（1）、（2）、（3）の3行を変更する必要があります。 +もし、Swagger定義の "info"値にホスト名が含まれていない場合は、各テストケースに手動でホスト名を（4）に記述する必要があります。 + + vi node-red-contrib-swagger-petstore/test/node_spec.js + +```JavaScript: + it('should handle addPet()', function (done) { + var flow = [ + { id: 'n1', type: 'swagger-petstore', name: 'swagger-petstore', + method: 'addPet', + addPet_body: '', // (1) ノードのプロパティを定義する + wires: [['n3']] + }, + { id: 'n3', type: 'helper' } + ]; + helper.load(node, flow, function () { + var n3 = helper.getNode('n3'); + var n1 = helper.getNode('n1'); + n3.on('input', function (msg) { + try { + msg.should.have.property('payload', { "id": 4513 }); // (3) 出力メッセージを定義する + done(); + } catch (e) { + done(e); + } + }); + n1.receive({ payload: { "id": 4513 } }); // (2) 入力メッセージを定義する + }); + }); +``` + +この例では、生成されたノードはペットストアのREST APIにデータ"{ "id": 4513 }"を送信します。 +そして、REST APIは同じデータ"{ "id": 4513 }"を返します。 +従って、入力メッセージと出力メッセージは同じです。 +テストケースを実行したい場合は、ノードが生成されたディレクトリの下で"npm test"コマンドを実行します。 + + cd node-red-contrib-swagger-petstore + npm install + npm test + +#### メッセージカタログ +デフォルトでは、ノードジェネレータは英語、日本語、中国語、ドイツ語のテンプレートファイルを出力します。 +ノードプロパティの多言語対応をしたい場合は、パラメータの言語メッセージをこれらのファイルに追加します。 + + vi node-red-contrib-swagger-petstore/locales/ja + +``` +{ + "SwaggerPetstore": { + "label": { + "service": "サービス", + "method": "メソッド", + "host": "ホスト", + "header": "ヘッダ", + "value": "値", + "isQuery": "クエリ" + }, + "status": { + "requesting": "要求中" + }, + "parameters": { + "addPet": "addPet", + "body": "body", + "updatePet": "updatePet", + "findPetsByStatus": "findPetsByStatus", + ... + "optionalParameters": "任意項目" + } + } +} +``` + +ノードが一部の言語をサポートしない場合は、言語ディレクトリを削除します。 +（例えば、中国語をサポートしたくない場合は、「zh-CN」ディレクトリごと削除してください） + + +## functionノードからノードを生成する方法 +functionノードにJavaScriptコードを記述した後、functionノードの "ライブラリへ保存..."メニューを使用して、JavaScriptコードをjsファイルとして書き出します。 +ノードジェネレータはfunctionノード名を生成ノードの名前として使用するため、functionノードをエクスポートする前にノード名を入力する方がよいでしょう。 +Node-REDは、jsファイルを"/.node-red/lib/functions/"ディレクトリに保存します。 +従って、このディレクトリとファイルパスをコマンドラインの引数として指定する必要があります。 + +(1) functionノードをjsファイルとしてエクスポートする + +![Export function node](library_ja.png) + +(2) node-red-nodegenコマンドを使用してノードを生成する + + node-red-nodegen ~/.node-red/lib/function/lower-case.js + +Node-REDユーザは通常、以下の手順で生成されたノードをNode-REDフローエディタのパレットにインポートします。 + +(3) 生成されたノードのディレクトリにディレクトリを変更する + + cd node-red-contrib-lower-case + +(4) シンボリックリンクを準備する + + sudo npm link + +(5) カレントディレクトリをNode-REDのホームディレクトリに変更します（通常、Node-REDのホームディレクトリは、ホームディレクトリの下の".node-red"です） + + cd ~/.node-red + +(6) シンボリックリンクを作成する + + npm link node-red-contrib-lower-case + +(7) Node-REDを起動する + + node-red + +Node-REDを起動すると、Node-REDフローエディタのパレットに生成されたノードが表示されます。 +生成されたノードをカスタマイズする場合は、次の手順やコマンドラインオプションが役立ちます。 + +#### モジュール名 +ノードジェネレータは、モジュール名のデフォルトのプレフィックスとして "node-red-contrib-"を使用します。 +従って、ノード名が "lower-case"の場合、モジュール名は "node-red-contrib-lower-case"になります。 +デフォルトのモジュール名を変更したい場合は、--moduleまたは--prefixオプションを使用してモジュール名を指定できます。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --module node-red-node-lower-case + node-red-nodegen ~/.node-red/lib/function/lower-case.js --prefix node-red-node + +#### ノード名 +functionノードの場合、functionノード内のノード名を、生成されるノードのノード名として使用します。 +もしデフォルトのノード名を変更したい場合は、--nameオプションを使用してノード名を設定します。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --name new-node-name + +#### バージョン +デフォルトでは、モジュールのバージョン番号は常に"0.0.1"です。 +モジュールのバージョン番号を更新するときは、--versionオプションを指定する必要があります。 +特に、"npm publish"コマンドを使用して、以前公開したモジュールと同じバージョン番号を持つモジュールを公開すると、競合エラーが発生します。 +この場合、モジュールのバージョン番号を更新するには、--versionオプションを指定する必要があります。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --version 0.0.2 + +#### キーワード +--keywordsは、フローライブラリ上のモジュールのキーワードを指定できる便利なオプションです。 +フローライブラリのWebサイトでは、訪問者はこのキーワードを使用してモジュールを検索します。 +例えば、キーワードとして"lower-case"を使用する場合は、--keywordsオプションを使用してこの単語を指定できます。 +デフォルトでは、ノードジェネレータは"node-red-nodegen"をキーワードとして使用します。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --keywords lower-case + +2つ以上のキーワードを追加するには、コンマ区切りのキーワードを使用することもできます。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --keywords lower-case,function + +生成されたノードを公開する前に "--keywords node-red"を指定すると、ノードはフローライブラリに登録され、Node-REDフローエディタでノードをインストールできます。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --keywords lower-case,function,node-red + +#### カテゴリ +Node-REDフローエディタのパレットでは、生成されたノードはデフォルトとして機能カテゴリに配置されます。 +カテゴリを変更したり、カテゴリ名に製品名を使用したりしたい場合は、--categoryオプションを用います。 +例えば、次のコマンドが出力する生成ノードは、Node-REDフローエディタの「分析」カテゴリに配置されます。 + + node-red-nodegen ~/.node-red/lib/function/lower-case.js --category analysis + +#### ノードアイコン +現在、ノードジェネレータは生成されたノードのアイコンファイルを指定するための--iconオプションをサポートしていません。 +従って、アイコンファイルを手動で変更する必要があります。 +（--iconオプションは、将来のバージョンのノードジェネレータでサポートされます） +デフォルトのアイコンファイルは "icons/icon.png"にあるため、このアイコンファイルを上書きします。 + + mv new-icon.png node-red-contrib-lower-case/icons/icon.png + +公式ドキュメントで説明されているように、アイコンは透明な背景上に白色で表示する必要があります。 +アイコンのサイズも20 x 30でなければなりません。 + +#### ノードの色 +現在のバージョンのノードジェネレータは、ノードの色を指定する--colorオプションもサポートしていません。 +そのため、生成されたノードの色設定を手動で変更する必要があります。 +（--colorオプションは、ノードジェネレータの将来のバージョンでサポートされます） + + vi node-red-contrib-lower-case/node.html + +```html: + +``` + +"RED.nodes.registerType()"は、"color:"#C0DEED""という色の設定を持っています。 +ノードの色を変更するには、 この"#C0DEED"をノードの色を表す他の16進数に変更する必要があります。 + +#### 情報タブ内のノードの情報 +ノードジェネレータはノード情報のテンプレートをnode.htmlファイルに出力します。 +ノードとともにテンプレートを変更する必要があります。 +（将来のバージョンのNode-REDとノードジェネレータでは、ノード開発者はノード記述プロパティを使用して、ノード情報を指定できます） + + vi node-red-contrib-lower-case/node.html + +```html: + +``` + +テンプレートには、ノードの説明と3つのセクションのサマリーがあります。 +Inputセクションには、入力されたメッセージの情報を記載します。 +Outputセクションには、出力されたメッセージの情報を記載します。 +Detailsセクションには、生成されたノードの追加情報を記載します。 + +#### README +ノードの詳細を説明するには、README.mdファイルにドキュメントを書く必要があります。 +フローライブラリにノードを公開すると、ドキュメントはフローライブラリのWebサイトで使用されます。 +ノードジェネレータはREADME.mdのテンプレートを出力するので、ファイルを変更するだけです。 + + vi node-red-contrib-lower-case/README.md + +``` +node-red-contrib-lower-case +===================== + +Node-RED node for lower case + +Install +------- + +Run the following command in your Node-RED user directory - typically `~/.node-red` + + npm install node-red-contrib-lower-case +``` + +#### テストケース +テストケースは、本番環境で使用するノードの品質を維持するために最も重要です。 +ノードジェネレータは、生成されたディレクトリの下にあるファイル"test/node_spec.js"にテストケースのテンプレートファイルを出力します。 +テストケースファイルでは、（1）と（2）の2行を修正する必要があります。 + + vi node-red-contrib-lower-case/test/node_spec.js + +```JavaScript: + it('should have payload', function (done) { + var flow = [ + { id: "n1", type: "lower-case", name: "lower-case", wires: [["n2"]] }, + { id: "n2", type: "helper" } + ]; + helper.load(node, flow, function () { + var n2 = helper.getNode("n2"); + var n1 = helper.getNode("n1"); + n2.on("input", function (msg) { + msg.should.have.property('payload', 'abcd'); // (2) 出力メッセージを定義する + done(); + }); + n1.receive({ payload: "AbCd" }); // (1) 入力メッセージを定義する + }); + }); +``` + +この例では、生成されたノードは大文字を小文字に変換します。 +従って、入力メッセージは「AbCd」であり、出力メッセージは「abcd」です。 +テストケースを実行したい場合は、ノードが生成されたディレクトリの下で"npm test"コマンドを実行します。 + + cd node-red-contrib-lower-case + npm install + npm test