I like to provide example flows in the package when I publish a node, and I usually include the same example(s) in the README.md file. This has caused some difficulties lately, mainly in keeping the two copies of a flow synchronized. (There does not seem to be a way to include an external text file in a markdown file, which might be the neatest solution.) What I plan to do going forward is to omit the JSON from the README file, include a reminder that the flow can be loaded from the Import menu, and give a link to the examples directory on GitHub. Can anyone see a down side to this or suggest a better way to handle it?
Hi Mike, I mostly put examples in the examples directory & put a message in the built in help...
Also, I have attached an onclick to that <a> icon that calls RED.actions.invoke('core:show-import-dialog'); as a quick action to get the user to the import dialog.
3 Likes
I'm still working through ideas on documentation and examples as uibuilder continues to mature so I share your experiences. Here is what I have in-play at the moment though I realise that I really need to simplify things a bit.
-
The examples folder contains "working" examples - ones that I know will work if the matching version is installed. Two types of example: ones that demonstrate simple concepts and ones that demonstrate complex configurations.
-
The WIKI has traditionally held the uibuilder examples and this has served well but is now too large and complex to really want to continue with. Really, it needs translating to a proper website.
-
The docs folder has taken on a much more important role and the discovery of
docsifyhas meant that I can expose the collection of markdown files as a proper website with minimal effort. That site is now available BOTH from within Node-RED and as the GitHub pages website. So you can access it both online and offline. The GitHub version showing the docs from the development version and the Node-RED version showing the docs from the installed version.The docs do have some code but I try to keep it to a minimum as I know that it must be maintained as versions change.
Using docsify extensions would let you do includes from other files I think.
-
The final part isn't live yet but I am quite excited by - but this is more uibuilder specific I think.
uibuilder already has some front-end templates built in - until the last version, there was only one. But in the latest version, there are a few.
I am going to build in a feature that lets you install templates directly from github which will mean that anyone, not just me, can create example front-end code that will be easy to deploy to a uibuilder node.
Oh, nice! I like that and will shamelessly nick it 
Being added to the project plan as we speak!
Very clever... and I had completely forgotten the built-in help as a place for this information. Thanks.
I doubt I will ever write anything as complex as uibuilder, but I think we have run into similar issues. The detailed documentation is most needed while the user is using Node-RED, but it is not directly accessible from inside NR. The docsify approach doesn't address this directly and may be over-kill for me, but it's a neat tool worth knowing about.
In fact, making the docs available within Node-RED turned out to be really very easy. Since Node-RED already has an admin ExpressJS app server and it is accessible to you as a node author, you can simply add the docs folder as a static resource and link to the docsified index.html page. That's it, your nice docs website is now available from within Node-RED.
If you have the current version of uibuilder installed, give it a go. There is both a button in the editor config panel and a link in the help panel.
Making that folder into the GitHub website for your node is also trivial, just one of the settings in your repo.
This topic was automatically closed 60 days after the last reply. New replies are no longer allowed.
