Improving documentation on how to interact with a patch

[Reinissance]

Hi, Congrats for your hard work, on macOS Ventura I was able to install and run it. Would you please give me some further hints? I found '// sendMsgToWebPd('n_0_1', '0', ['bang']) // sendMsgToWebPd('n_0_2', '0', [123])' in the example page created in terminal but I'm not yet deep enough into node.js or webAssembly to get way this could help me sending or receiving messages from or to pd... Would be awesome and maybe I could help out with the planned documentation. Regards, Reini

[sebpiq]

Hi @Reinissance !

I totally agree with you ! The documentation on how to interact with a patch is lacking. Here are all the details of the problem, so maybe you're more able to understand how to do it yourself, and to help me explain it to others ;)

In the process of compiling a patch with WebPd, all pure data objects are assigned a unique ID which allows to address connections, send messages to the patch from JS, etc ... These IDs are the 'n_0_2', ... you see in the examples in your generated html file.

These IDs are somewhat arbitrary and not really human-friendly. There isn't really a good way to map it back to an object you see in your patch.

In the generated html file I added the list of all object IDs to which you can send messages in the patch. I also added the object type to help with identification. I have other type of data that could be added (e.g. the [x,y] position, the label if a label was added, etc ...). But identifying the right object is still a little difficult.

The example given in the html file sendMsgToWebPd('n_0_2', '0', [123]) shows you how to call the function to send a value to your patch. You would need to add a control on your web page (a button, a slider, etc.), and then connect that control with JavaScript so that everytime it is activated by the user, the function sendMsgToWebPd is called with the right parameters (object ID, Inlet ID, value to send).

I could have added a fully working example with a simple button that sends values to the patch, instead of writing an example in the comments the way I did. However, the issue with that is I have no way to know what type of values the control is expecting (what range, numbers or text ? ...). Therefore it is a bit hard to provide an example that works out-of-the-box for all cases. It would be good on the other hand to do that so that people that are beginners in JavaScript could have something to build on.

What I am going to do at least :

• Write on the HTML page a message to "open the html file to see examples of interaction".
• Any ideas how to improve that ? Should I try working on a full example that would work in all cases ? Any ideas on how to do it ?
• Did you figure out by the way how to send values to your patch ?

[Reinissance]

Ah, just found what's wrong: You declare 'const sendMsgToWebPd = (nodeId, portletId, message) => { ... }' in the htmlFile created by the CLI, which gives the error 'TypeError: "x" is not a function'. So when declaring 'function sendMsgToWebPd (nodeId, portletId, message) { ... }', then it works. 😃

[Reinissance]

We could add the send and receive names to the hint, where you give the type of the node for identification, that would make it far more easy when having multiple toggles or sliders etc. in the patch. Or maybe take these as IDs? Btw, how could we receive messages from the patch in the htmlFile? is there already something like 'receiveMsgFromWebPd (nodeId, portletId, message)'?

[Reinissance]

Concerning the type of values the control is expecting (what range, numbers or text ? ...): If I myself cteated the patch I should know this or be able to figure out my mistake if I sent the wrong type with the browsers console when testing, right? I think, this is something not too bad to deal with.

[sebpiq]

@Reinissance

Ah, just found what's wrong: You declare 'const sendMsgToWebPd = (nodeId, portletId, message) => { ... }

Hmm I don't think that's an issue ! This is a perfectly valid way of declaring a function. It's tested in Firefox and it works fine ! You didn't manage to run it ?

We could add the send and receive names to the hint

Yes that could be done if you think it'd make things clearer ! Did you understand the hint in the first place ? Did you understand you had to find the right node id and call the function with it ? Or was even that unclear ?

Btw, how could we receive messages from the patch in the htmlFile

Everything is in place for that, it could already work now, but I haven't yet implemented a simple way to declare message receivers. I'll add that the roadmap.

if I sent the wrong type with the browsers console when testing, right?

I think you should already see an error message from the patch when the object receives the wrong type. But if that's not your case, that might be a bug !

[samuelealbani]

I cannot find the list of the nodes' ids in the template. Can you help me?

[sebpiq]

@samuelealbani did you generate the appTemplate with the CLI ? If you open the generated html file, you will get some documentation ;)

Let me know if that helps !

[samuelealbani]

@samuelealbani did you generate the appTemplate with the CLI ? If you open the generated html file, you will get some documentation ;)

Let me know if that helps !

Yes I did but I realized that my list was empty because I didn't create any gui object!

Thank you for your reply

[sebpiq]

Ah right ! That's a good point ! I should write that only GUI objects can be interacted with. Let me know if you have more issues ;)

[sebpiq]

Hey @Reinissance !

I have improved the docs a bit (it is not yet pushed to npm) ! Actually I didn't remember but it is more complicated than I thought to add hints, as I don't have the data at hand (it would require more work).

I let you have a look at the full diff here : https://github.com/sebpiq/WebPd/commit/2442525eb5bc10eda30bf83854f9e7e3147b5f9c

1. I added hint that people should open the index.html file in the CLI
2. I added more exhaustive comments in to explain how the function to send messages work.

Let me know if you think this is an improvement, and if you have some feedback !

Thanks ;)

[samuelealbani]

Ah right ! That's a good point ! I should write that only GUI objects can be interacted with. Let me know if you have more issues ;)

Yes, this would be definitely helpful! Thank you

[Reinissance]

Hmm I don't think that's an issue ! This is a perfectly valid way of declaring a function. It's tested in Firefox and it works fine ! You didn't manage to run it ?

Sorry, it was my fault. Btw, thanks for helping noops like me out so patiently!

Yes that could be done if you think it'd make things clearer ! Did you understand the hint in the first place ? Did you understand you had to find the right node id and call the function with it ? Or was even that unclear ?

Actually I think, with the new additions and maybe also send & receive names in the documentation should be clear enough, thanks for the improvement anyway!

Everything is in place for that, it could already work now

Found your hint in the roadmap, I will give myself a try with receiving masseges from pd ;-)

[sebpiq]

@Reinissance I closed this for now ! I added new hints to make it easier to find the node id : node args and label. Should look like this now :

            //  - nodeId "n_1_13" portletId "0"
            //      * type "hsl"
            //      * args [0,0.4,1,0,"",""]
            //      * label "swing"
            //  - nodeId "n_1_17" portletId "0"
            //      * type "floatatom"
            //      * args [30,300,"",""]
            //      * label "bpm"

send and receive are too hard to get for the simple reason that their position is not standardized in pd file format, and therefore it is not easy to extract them in a generic manner (for all node types).

Thanks for the help with this, and don't hesitate to re-open a ticket if this really doesn't do the trick !

[Reinissance]

Dazu okay, der name is completely sufficient for orientation. is the update push to npm already? And one more time thanks for the quick help! Regards, Reini

Am 28.04.2023 um 18:57 schrieb Sebastien Piquemal @.***>:

 @Reinissance I closed this for now ! I added new hints to make it easier to find the node id : node args and label. Should look like this now :

        //  - nodeId "n_1_13" portletId "0"
        //      * type "hsl"
        //      * args [0,0.4,1,0,"",""]
        //      * label "swing"
        //  - nodeId "n_1_17" portletId "0"
        //      * type "floatatom"
        //      * args [30,300,"",""]
        //      * label "bpm"

send and receive are too hard to get for the simple reason that their position is not standardized in pd file format, and therefore it is not easy to extract them in a generic manner (for all node types).

Thanks for the help with this, and don't hesitate to re-open a ticket if this really doesn't do the trick !

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[sebpiq]

No! Not yet! I'll push this in a few days. It's less work to batch releases.

[Reinissance]

I don’t have clue how to receive messages from pd, in fact I‘m not deep enough into js, could you please give me a little snippet to get me goin? Would be very nice…

Am 28.04.2023 um 20:49 schrieb Sebastien Piquemal @.***>:  No! Not yet! I'll push this in a few days. It's less work to batch releases.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[sebpiq]

@Reinissance right now you can't do it yourself. I'd love some input though on how it should work, and I can implement quickly ;) See #133