Reworked Flow Development Guide #163
Conversation
* Pages to discuss chapter composition of flow dev guide * Modified pages to discuss chapter composition
* Pages to discuss chapter composition of flow dev guide * Modified pages to discuss chapter composition * Renamed 'Practiec'->'Developing Flows'
|
I have removed the separate Handling Errors section of the guide as I realised we already have a section on how to do error handling in the main user guide. Instead, I have added a smaller section to the Flow Structure guide that talks about how to layout the error handling and not about how to do error handling. |
|
#107 is part of the node development guideline. Therefore, it can be removed from this flow development guideline. |
|
@kazuhitoyokoi you are right - #107 is not included in this PR. I listed it by mistake. To make it easier to review this guide, I have set https://new.nodered.org - which is the The flow developer guide can be found here: https://new.nodered.org/docs/developing-flows/ |
|
Made some minor updates to reflect the comments from @dceejay - have updated https://new.nodered.org/docs/developing-flows/ with the latest |
|
I have now added the Message section to the guide - https://new.nodered.org/docs/developing-flows/ This completes my first full pass through of the guide. Question: is there any more content from the Hitatchi guide that should be added to the guide? I would like to remove the extra Hitachi content before opening it for wider review with the community. |
|
Thank you for your confirmation. I checked the website. This pull request contains all of the contents from Hitachi. |
|
@kazuhitoyokoi I need to clarify what I plan to do as I'm not sure from your reply if it is clear. Yes this PR contains all of the content from Hitachi. But the plan is to delete all of the pages from Hitachi because the information has been rewritten and included in the three sections I have been working on.
I want to make sure you are happy that the three sections I have written cover everything you think it should and that we are okay to delete the hitachi pages. |
| The messages that pass through a flow are plain JavaScript objects that can have | ||
| properties set on them. | ||
|
|
||
| They usually have a payload property - this is the default property that most nodes |
There was a problem hiding this comment.
do we want to emphasise payload - eg like below - or maybe just bold
| This section looks at some of the choices you need to make when deciding how to | ||
| stucture the messages in your flows. | ||
|
|
||
| ### Working with the payload |
There was a problem hiding this comment.
should this be msg.payload to link to the msg.topic heading below
|
|
||
| This highlights an important principle: nodes should not modify or remove properties on messages that are not related to their functionality. | ||
|
|
||
| For example, in most cases, a Function node should send on the same message object it received rather than create a new message object. |
There was a problem hiding this comment.
just a Function node ? (Ok I get for most users yes... but...)
There was a problem hiding this comment.
The Function node is the only node a user can explicitly create a new message object which is why it is singled out here.
| As with programming in general, the choice of good property names is also important. They should be self-describing to help with later debugging and understanding of the flow. For example, `msg.temperature` is much more understandable than `msg.t`. | ||
|
|
||
|
|
||
| ## |
| There is a balance to be considered here. The longer the label, the more space it needs in the flow. The shorter the label, the less information it can share. | ||
|
|
||
| For some nodes, it might be appropriate to hide the label altogether to minimise the horizontal space it uses in the flow - giving more room to other nodes. | ||
|
|
There was a problem hiding this comment.
maybe an image of the "appearance tab" in config to show how to get to shorten the name
|
|
||
| For example, the Switch node provides default labels for its outputs that are shown when the mouse hovers over them. They can help quickly identify the purpose of each branch in the flow. | ||
|
|
||
| Whilst the default labels may be sufficient in the context of the flow itself, it is also possible to custom labels to provide more detailed information. |
There was a problem hiding this comment.
... also possible for custom ...
|
|
||
| ### Grouping nodes | ||
|
|
||
| A more explicit arrangement of the flows can be achieved by grouping related nodes together. |
There was a problem hiding this comment.
Link to grouping docs ? Or cut/paste blog post info to here ?
|
In intro para 3 - I think it is also worth adding a link to the YouTube introduction channel - as that is a good resource. |
|
@knolleary I misunderstood your question. Because today is a holiday in Japan, I will answer it on Monday after checking a little with Hitachi colleagues. Please wait a moment. 🙏 |
|
No rush - want to make sure we get this right. I hope this plan does not come as a surprise - I have been saying since the start of reviewing the flow dev guide that I felt the best approach was to take the information from the Hitachi content and rework it into a slightly different shape. |
|
@knolleary Thank you for waiting. Today, I talked about it with Hitachi colleagues. Because three sections contain key points, we agree with your decision. You can delete the Hitachi pages. |
|
Thanks @kazuhitoyokoi And please do remember, this is not a 'finished' guide - we can add extra content at any time. So if there are other topics you think it should cover in the future, then open an issue/pr and we can discuss. |
|
@knolleary I appreciate your consideration. Okay, we will suggest a discussion if we have feedback from the Japanese community. 😁 |
|
I've updated flow dev guide to remove the extra pages. I'm going to share a link for the wider community to provide some feedback before we publish. In terms of content, we still need to:
|
|
Going to merge this content as it currently stands. I'm sure there's more to add, particularly around Performance, but I'd rather get this material published and available. |
This PR represents the working copy of the Flow Development Guide. It is still being written - the PR is to share progress and get feedback.
This PR contains the changes from the following PRs:
The content from those PRs has provided the starting point for the guide. Not all of the content from those PRs will be in the final guide.
The working draft of the guide contains the sections:
Error handling (not yet written)see my comment belowThe current version of this branch can be viewed here: https://new.nodered.org/docs/developing-flows/