[Doc feature request]A more complex contrib node example

Having battled (and still battling as we speak) with adding extra features to an existing simple contrib node, I think it would be a REALLY good idea to have a slightly (just a bit) more complex example than just the current lower-case one.

I.e - one with fields and properties etc

If you've been following my trials and tribulations - you'll know I'm not the person for the job but by golly , I'm a good ideas person and an excellent critic :slight_smile: and willing to do any work needed

Not quite at the ready to be at the helping out stage yet until I've beaten my present project into submission but just putting this out there now :slight_smile:

FTAOD I see this as a community project by the "regulars" and not for the core devs :slight_smile:

1 Like

Can you expand a bit more on what else you think it should cover?

I appreciate the lower-case example is very limited in terms of features, but it does show the core mechanism of how node properties relate to edit dialog fields and how those properties are accessed in the runtime side of the node.

The hard part is figuring out what is the next thing budding node authors should get exposed to. We're not going to have a complete guide to writing JavaScript UIs with jQuery, but I'm sure we could cover a bit more ground.

As part of the 1.1.0 doc updates, I did add this page that covers some more detail on the edit dialog of a node - including inline examples of the button css styles, typedInput and ACE editor component. Lots more it could cover, but at least it's a start.

2 Likes

Having checkboxes/choices/dropdowns/special NR fields etc

Not intended to be JS tutorial - just give boiler plate UI examples with stuff like onEditPrepare etc

[edit] aah - just scanned your link - let me digest it and get back to you tomorrow :slight_smile: [/edit]

1 Like

That looks excellent info :slight_smile:

In my particular case - wish I'd know about small buttons before I pressed go on a node PR 10 minutes ago #Timing :slight_smile:

So I'd like to revise my suggestion to getting some examples (maybe called node-red-contrib-exampleX etc or maybe node-red-examples-exampleX ??) that incorporate those snippets into fully working (but ultimately not actually doing anything real) examples

Or maybe there is an existing node in node-red-nodes (or elsewhere) that could be better documented and pointed at ? ( or does that risk hundreds of dodgy copycat clones ? Lowercase-syndrome)

1 Like

I think something like that would have been useful for me too. I have developed a couple of nodes previously but much has changed since I did that (typed inputs etc) so I was almost starting again when I came to build another one. A working example that I could have taken as a template to build on would have been great.

That'd be good as long as the real code to do the processing of the message wasn't too complex.

I'll have a look around

Yeah problem is if you want to demonstrate lots of UI options, it’ll probably then be more complex inside as well.

I guess you are mostly concerned about the editor?

What about finding some nodes that implement advanced features and then strip them down until only the core functionality remains. With core functionality I mean the editor feature you want to have and not any functionality of the original node itself. Then we can collect a list of those stripped-down nodes somewhere.
I also think that it should not be a single node that shows every option, since even without message processing it would then hard again for a beginner to find the relevant part of the code.

One also has to distinguish between:

  • Features Node-RED provides
  • General jQuery
  • General html/css (mixed with css already provided by Node-RED)

Although I think the goal should not be to explain jQuery in detail, but there are some patterns that come up very often in nodes, like populating dropdown menus, making ajax calls to the runtime, hiding some configuration options depending on the configuration etc.

Some while ago I did such a stripped down version for the typed-input widget TypedInput Widget (hopefully not obsolete by now) and I have it laying around on my disc for future reference

3 Likes

Dare I point out that I have a test node on GitHub? Not published to npm of course and may be slightly dated in a couple of places but I use it to help me remember where everything goes and why things need to happen in certain ways. It is extensively documented because my memory isn't brilliant.

I'll admit that it is more about the .js file than the .html but that could be addressed. It does, however, cover creating config nodes & sharing code between nodes.

1 Like

you may indeed dare - I do now recall you mentioning it.

Link dear Henry, dear Henry....

1 Like

I see that I haven't updated it for a while. I might need to see if I made any local changes that haven't been pushed back.

I've updated a couple of minor things. Last main update was last year so this version probably doesn't have any of the changes for Node-RED v1.

Let me know if you find any mistakes or if you think something should be added/removed.

#Eeek - that's Second Stage Lensman stuff :slight_smile:

I'm thinking of something that incorporates Nick's html file example stuff as a progression from the basic lowercase.html (along with how adding in extra fields is accessed in the matching .js file - especially dealing with default properties (or lack of them when adding to exisiting nodes :slight_smile: )

Ha ha. E.E.Smith reference, like it.

Most of it is comments. It should make sense if you have a play with it.

As someone new to writing NodeRed nodes and just completed writing my first node here's things I wished were documented better:

  1. How to properly log information. I used console.log everywhere, and then only later learned the node has log methods, as does the global RED object, which seem to be more appropriate to use.

  2. How to properly structure a project that's beyond a simple file. When you start to do more than just basic lower-case, it makes sense to break code into separate files. If you're a TypeScript kinda person (like me) you'll have separate files for classes, interfaces, etc. I see many projects use "lib" and "node" as folders, but what's the best practice?

  3. More information on project magic. I think if I name a file called nodename.js and have it live alongside nodename.html it will automatically get included at edit page display time, and provides a way to split all the javascript code (like oneditcreate) out of the HTML page?

  4. A full TypeScript example. I wound up digging through GitHub repos of the people who made the @types/node-red definition on DefinitelyTyped to figure out how to use it.

  5. How to leverage the express server to shove server requests to the back-end instead of the UI end. I was fortunate that a couple of people here pointed me to great examples of calling back to the underlying node via express endpoints, but had I not asked and been given the example I would have had no idea it was possible.

  6. How to set up debugging with VSCode. I'm not new to VSCode and was able to find enough info here and there to get debugging the node code working but I was never able to get Chrome/Edge debugging of the UI to work. No matter how I tried to attach I could never get breakpoints to get hit in the UI's Javascript. Made for a lot of painful console.log debugging sessions!

I will say that this forum was invaluable even though I only posted two questions. The answers I got were exactly what I needed to get unblocked!

1 Like

Hi,
as none of the core developers use typescript and tend to use atom over vscode, then we have to rely on community contributions for those. Happy to consider adding them, but will need folk to step up. Julian does have a good page on vscode debug here - https://it.knightnet.org.uk/kb/nr-qa/vscode-debugger/

1 Like

No, that is no correct. The .js file that lives alongside the .html file is the Node.js runtime component of the node. All of the node's editor content should be in the .html file. It is possible to move it to an external .js file, but you have to add custom express routes in the runtime side in order to serve up the extra files. There are examples of that (such as the geofence node), but it is also something on the one-day-to-do list to make easier for a node to declare what extra resources should be made available in the editor.

Yup - that's been on the todo list for ages. This StackOverflow answer I wrote from 3.5 years ago remains my go to reference when ppl ask about it: https://stackoverflow.com/questions/41567175/send-data-on-configuration/41567832#41567832

That's the configuration I have, however that's showing how to debug the node process, not the UI in the browser which is what I was never able to get working.

That would have been immensely helpful :slight_smile:

For my node I was running all fine and happy in local development and I assumed all was good. I published the node, then installed it in my NodeRed instance that's running on Home Assistant and... it didn't work. The leading slash was the problem, which you point out:

here the url must not begin with a / . That ensures the request is made relative to wherever the editor is being served from - you cannot assume it is being served from / .

Anyway, I think that's the point I'm trying to make. I did get everything working eventually but only by a ton of trial and error looking at random samples on StackOverflow, in other repos, and in this forum.

I understand the concern about NodeRed documentation expanding to cover everything about how to write HTML and use jQuery, but I don't think that's really what's missing. The missing pieces are around best practices for building complete notes: how to set up the project structure; logging status to users; debugging in commonly used dev environments; and communication between external services, the node, and the UI.