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 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
FTAOD I see this as a community project by the "regulars" and not for the core devs
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.
In my particular case - wish I'd know about small buttons before I pressed go on a node PR 10 minutes ago #Timing
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)
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.
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
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.
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 )
As someone new to writing NodeRed nodes and just completed writing my first node here's things I wished were documented better:
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.
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?
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?
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.
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.
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!
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/
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.
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.
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.
and willing to do any work needed
[/edit]