Skip to content

Node Guideline Contents

Jump to bottom Edit New page
LEEHYUKJOO edited this page Dec 13, 2018 · 1 revision

status: work in progress

This documentation shows practices, tips and know-how to effectively develop nodes.

Creating an original node

Creating node definitions for Node-RED (node generator)

The node generator is a tool that can automatically generate an original node by using one command. If you specify a source file as an argument of a command as described below, a file group for an original node in a package is automatically output.

node-red-nodegen \<source file\> -> Automatically output files of original node in package format

Using this tool enables automatic generation of the following files that make up an original node. For this reason, the node developer can drastically reduce the man-hours for node development.

  • Original node (the node's js file, html file, node icon file, and language file)
  • Files required to package an original node (README.md, package.json, LICENSE)
  • Test cases

The latest information about the node generator can be obtained from the GitHub project for the node generator (https://github.com/node-red/node-red-nodegen).

Flow for developing an original node from a Swagger file

The flow for generating a node from a Swagger file is as follows:

  1. Generate an original node by using a node generator command.
  2. Add a description of the node, test cases, and the like.

The following describes the procedure for developing an original node from a Swagger file.

1. Generate an original node by using a node generator command.

By executing the following command, you can generate an original node. In this example, the Swagger definitions on the HTTP server are obtained directly. However, you can also specify a Swagger definition file stored in the local file system.

node-red-nodegen http://petstore.swagger.io/v2/swagger.json

Specifiable command line arguments are as follows:

Module name

The node generator uses "node-red-contrib-" as the default prefix for module names. Therefore, if the node name is "swagger-petstore", the module name is "node-red-contrib-swagger-petstore". If you want to change the default module name, you can use the --module option to specify the module name. If you want to change the prefix only, you can use the --prefix option to specify the prefix only.

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

If you want to change the default node name, you can use the --name option to specify the node name.

node-red-nodegen http://petstore.swagger.io/v2/swagger.json --name new-node-name
Version

The node generator uses the version defined in Swagger as the node version. When updating the version of a module, you need to use the --version option to specify the version. In particular, when updating a module on the npm library, you need to use this option to increment the version number because the same version number as that of a module registered in the past cannot be used and registered in npm.

node-red-nodegen http://petstore.swagger.io/v2/swagger.json --version 0.0.2
Keyword

The keyword is information used when a module is searched on the npm repository. For example, if you want to specify "petstore" as a keyword, you can use the '--keywords' option to specify this word.

node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore

If you want to add two or more keywords, specify multiple keywords by using a comma to separate them.

node-red-nodegen http://petstore.swagger.io/v2/swagger.json --keywords petstore
Category

By default, original nodes generated by the node generator are inserted in the function category on the flow editor palette. If you want to change this category, you can use the --category option to specify the category. For example, if you want to insert a node into the "analysis" category, specify as follows.

node-red-nodegen http://petstore.swagger.io/v2/swagger.json --category analysis

2. Add a node description, test cases, etc.

Information about the nodes displayed in the information tab, and README

If you generate an original node from Swagger definitions, information to be described in the information tab and README.md is automatically generated from the content of the Swagger definitions. For this reason, it is preferable to modify node.html and README.md as required.

README

To enable users to understand details about the node, you need to write an explanation of the node in the README.md file. This README.md can be viewed on the npmjs site when nodes are made public on the public npmjs. Because the node generator outputs a template of README.md, you can edit this file.

node-red-contrib-swagger-petstore/README.md

node-red-contrib-swagger-petstore
=====================

Node-RED node for swagger petstore

Install
-------

Run the following command in your Node-RED user directory - typically `~/.node-red`

        npm install node-red-contrib-swagger-petstore
Test case

For test cases, a test case template is generated for each endpoint. Because the node generator outputs a test case template to "test/node_spec.js" in the generated directory, you can edit this file. Set the property values for the node in addition to the input message and the output message. For example, in the following case, write the property value in the section of findPetsByStatus_status.

node-red-contrib-swagger-petstore/test/node_spec.js

    it('should handle findPetsByStatus()', function (done) {
        var flow = [
            { id: "n1", type: "swagger-petstore", name: "swagger-petstore", wires: [["n2"]],
                method: "findPetsByStatus",
                findPetsByStatus_status: "<node property>", // (1) define node properties
                service: "n3" },
            { id: "n2", type: "swagger-petstore-service" },
            { 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', '<output message>'); // (3) define output message
                    done();
                } catch (e) {
                    done(e);
                }
            });
            n1.receive({ payload: "<input message>" }); // (2) define input message
        });
    });

If you want to execute a test case, execute it by executing "npm test" in the generated directory.

cd node-red-contrib-lower-case
npm install
npm test
Support for multiple languages

The node generator automatically generates templates of language files corresponding to English, Japanese, and Chinese. You only need to translate the values in the parameters of each file. If you cannot translate all languages, delete a higher-level directory (delete the zh-CN directory if you do not create the Chinese language file).

node-red-contrib-swagger-petstore/locales/ja

{
    "SwaggerPetstore": {
        "label": {
            "service": "<Service>",
            "method": "<Method>",
            "host": "<Host>",
            "header": "<Header>",
            "value": "<Value>",
            "isQuery": "<Query>"
        },
        "status": {
            "requesting": "Requesting"
        },
        "parameters": {
            "addPet": "addPet",
            "body": "body",
            "updatePet": "updatePet",
            "findPetsByStatus": "findPetsByStatus",
            ...
            "optionalParameters": "<Option>"
        }
    }
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally