Створення власних вузлів

JavaScript file

Файл .js вузла означує поведінку в режимі виконання.

Node constructor

Вузли означуються функцією конструктора, яку можна використовувати для створення нових екземплярів вузла. Функція реєструється під час виконання, тому її можна викликати, коли вузли відповідного типу розгорнуті в потоці.

Об’єкту передається функція, що містить властивості, встановлені в редакторі потоків.

Перше, що потрібно зробити, це викликати функцію RED.nodes.createNode, щоб ініціалізувати функціональність, якою користуються всі вузли. Після цього виконується код, характерний для конкретного вузла.

function SampleNode(config) {
    RED.nodes.createNode(this,config);
    // специфічний для вузла код поичнається звідси

}

RED.nodes.registerType("sample",SampleNode);

Отримання повідомлень

Щоб отримувати повідомлення від приєднаних вузлів потоку, вузли реєструють слухача (listener) події input.

З Node-RED 1.0 був введений новий стиль слухача, що дозволяє вузлу повідомляти середовище виконання, коли він закінчив обробляти повідомлення. Це додало два нові параметри до функції слухача. Необхідна певна обережність для того, щоб вузол все-таки міг бути встановлений у Node-RED 0.x, який не використовує цей новий стиль слухача.

this.on('input', function(msg, send, done) {
    // що небудь робити з 'msg'

    // як тільки закінчить, викличе 'done'.
    // Цей виклик загорнутий у перевірку того, що 'done' існує 
    // тому вузол буде працювати в попередніх версіях Node-RED (<1.0) 
    if (done) {
        done();
    }
});

Обробник помилок

Якщо вузол зіткнувся з помилкою під час обробки повідомлення, він повинен передати деталі помилки функції done .

Це запустить будь-які вузли Catch, що знаходяться на одній вкладці, дозволяючи користувачеві створювати потоки для обробки помилки.

Знову ж таки, певний догляд потрібен у випадку, якщо вузол встановлений у Node-RED 0.x, який не забезпечує функцію done. У цьому випадку він повинен використовувати node.error:

let node = this;
this.on('input', function(msg, send, done) {
    // що небудь робити з 'msg'

    // якщо виникла помилка, звітувати до середовища виконання
    if (err) {
        if (done) {
            // Node-RED 1.0 сумісне
            done(err);
        } else {
            // Node-RED 0.x сумісне
            node.error(err, msg);
        }
    }
});

Відправка повідомлень

Якщо вузол знаходиться на початку потоку і видає повідомлення у відповідь на зовнішні події, він повинен використовувати функцію send об’єкту Node:

var msg = { payload:"hi" }
this.send(msg);

Якщо вузол хоче відправити зсередини слухача подій input у відповідь на отримання повідомлення, він повинен використовувати функцію ` send`, передану функції слухача:

let node = this;
this.on('input', function(msg, send, done) {
    // Для максимальної зворотної сумісності перевірте, чи існує 'send'. 
    // Якщо цей вузол встановлено в Node-RED 0.x, його потрібно буде 
    // обробити з використанням `node.send` 
    send = send || function() { node.send.apply(node,arguments) }

    msg.payload = "hi";
    send(msg);

    if (done) {
        done();
    }
});

Якщо msg є null, не відправляти повідомлення.

Якщо вузол надсилає повідомлення у відповідь на отримане, він повинен використовувати повторно отримане повідомлення, а не створювати новий об’єкт повідомлення. Це забезпечує наявні властивості повідомлення збереженими для решти потоку.

Декілька виходів

Якщо вузол має більше одного виходу, до send передається масив повідомлень , причому кожне з них буде відправлено на відповідний вихід.

this.send([ msg1 , msg2 ]);

Декілька повідомлень

Можна надіслати декілька повідомлень на певний вихід, передавши масив повідомлень у цей масив:

this.send([ [msgA1 , msgA2 , msgA3] , msg2 ]);

Закривання (Closing) вузлу

Щоразу, коли розгортається новий потік, існуючі вузли видаляються. Якщо в цей час комусь із них потрібно провести якісь дії (“прибирання”), наприклад, відключитися від віддаленої системи, він повинен зареєструвати слухача на подію close .

this.on('close', function() {
    // інструкції 'прибирання'
});

Якщо для завершення “прибирання” вузла необхідно виконати будь-яку асинхронну операцію, зареєстрований слухач повинен прийняти аргумент, який може викликати функцію, коли вся робота завершена.

this.on('close', function(done) {
    doSomethingWithACallback(function() {
        done();
    });
});

Починаючи з Node-RED 0.17

Якщо зареєстрований слухач приймає два аргументи. Першим буде булевий прапорець removed, що вказує на те, що вузол закривається у зв’язку з видаленням. Якщо removed == false, це значить що він просто перезапускається.

this.on('close', function(removed, done) {
    if (removed) {
        // цей вузол видаляється
    } else {
        // цей вузол перезапускається
    }
    done();
});

Поведінка таймаута (Timeout behaviour)

Починаючи з Node-RED 0.17

До Node-RED 0.17, середовище виконання чекає нескінченно довго зворотного виклику функції done. Це призведе до зависання середовища виконання, якщо вузол не зможе її викликати.

Починаючи з версії 0.17 середовище виконання буде очікувати не більше 15 секунд. Якщо цей час буде перевищено, буде зареєстрована помилка, а середовище виконання продовжить працювати.

Журналювання подій

Якщо вузлу потрібно щось записати в консоль, він може використовувати одну з наступних функцій:

this.log("Що-небудь сталося");
this.warn("Що-небудь сталося ти повенен про це знати");
this.error("Ой ні, що-небудь сталося!");

// Починаючи з Node-RED 0.17
this.trace("Запишіть якусь внутрішню деталь, не потрібну для нормальної роботи");
this.debug("Занотуйте щось детальніше для налагодження поведінки вузла");

Повідомлення warn та errorтакож надсилаються на вкладку налагодження редактора потоків.

Виставлення статусу

Під час роботи вузол може обмінюватися інформацією про стан з інтерфейсом редактора. Це робиться за допомогою виклику функції status :

this.status({fill:"red",shape:"ring",text:"disconnected"});

Деталі про api вузла status може бути знайдено тут.

Користувацькі налаштування вузла

Вузол, можливо, захоче використовувати параметри конфігурації, які знаходяться у файлі користувача settings.js .

Назва будь-якого налаштування повинна відповідати наступним вимогам:

ім’я має мати префікс назви відповідного типу вузла.
для налаштування потрібно використовувати camel-case - для отримання додаткової інформації див. нижче.
вузол не повинен вимагати, щоб користувач його встановив, він повинен мати налаштування за замовченням.

Наприклад, якщо тип вузла sample-node хоче використовувати налаштування під назвою colour, ім’я параметра має бути sampleNodeColour. Протягом часу виконання вузол може посилатися на налаштування якRED.setting.sampleNodeColour.

Визначення параметрів у редакторі

Починаючи з Node-RED 0.17

За деяких обставин, вузол може захотіти викласти значення параметра редактору. Якщо так, вузол повинен зареєструвати налаштування як частину його виклику до registerType:

RED.nodes.registerType("sample",SampleNode, {
    settings: {
        sampleNodeColour: {
            value: "red",
            exportable: true
        }
    }
});

value поле вказує значення за замовчуванням, яке має прийняти налаштування.
exportable повідомляє середовищу виконання, щоб зробити його доступним для редактора.

Як і у випадку виконання, вузол в редакторі може потім посилатися на параметр як на RED.settings.sampleNodeColour .

Якщо вузол намагається зареєструвати параметр, який не відповідає вимогам іменування, буде записана помилка.