Re[2]: Doc - Adding new protocols missing guacamole-client

[David Haukeness <da...@hauken.us>]

Chris, Nick, and Mike - thanks for the quick guidance.  I'll work 
through this and do a writeup for doc improvement!

Appreciate you all.

David

------ Original Message ------
From "Michael Jumper" <mj...@apache.org>
To user@guacamole.apache.org; "David Haukeness" <da...@hauken.us>
Date 7/6/2022 12:55:33 PM
Subject Re: Doc - Adding new protocols missing guacamole-client

>On Wed, Jul 6, 2022 at 11:30 AM David Haukeness <da...@hauken.us> 
>wrote:
>>Hello,
>>     I'm working through the documentation and have worked through the 
>>"adding new protocols" section that covers guacd, however there's no 
>>guidance on what/where needs to be modified on guacamole-client to get 
>>the new protocols to show up in the "Add new connection" screen, or 
>>demo the connection.
>>     Is there a resource available that explains this part somewhere? 
>>alternatively is there someone willing to offer guidance, and i'm 
>>willing to write it up and PR the manual?
>
>The existence of a protocol and its parameters are defined by JSON 
>files that separate each parameter into a typed field within a named 
>group of fields called a form. Built-in definitions can be found here:
>
>https://github.com/apache/guacamole-client/tree/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole-ext/src/main/resources/org/apache/guacamole/protocols
>https://github.com/apache/guacamole-client/blob/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole-ext/src/main/java/org/apache/guacamole/environment/LocalEnvironment.java#L56-L65
>
>The built-in field types correspond to the types defined within 
>guacamole-ext and the webapp itself:
>
>https://guacamole.apache.org/doc/guacamole-ext/org/apache/guacamole/form/package-summary.html
>https://github.com/apache/guacamole-client/blob/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole/src/main/frontend/src/app/form/services/formService.js#L33-L210
>
>Extensions can define their own field types if needed. In practice, 
>this most often happens for authentication extensions (the Duo, TOTP, 
>and SAML extensions all do this), but can be also used for protocol 
>definitions.
>
>Additional, third-party definitions can be added by creating the same 
>sort of JSON files within "GUACAMOLE_HOME/protocols/". If JSON for a 
>built-in protocol is found within this directory, that JSON takes 
>precedence over the built-in copy.
>
>The human-readable text for the name of the protocol and for each 
>parameter and form are defined with translation strings. Each of these 
>strings will be derived from the protocol name and parameter name, 
>canonicalized to UPPERCASE_WITH_UNDERSCORES. For example:
>
>https://github.com/apache/guacamole-client/blob/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole/src/main/frontend/src/translations/en.json#L789-L860
>
>In the above, the protocol ("vnc") determines the name of the namespace 
>containing the relevant strings ("PROTOCOL_VNC"). Within that 
>namespace, each parameter (like "audio-servername") is transformed to 
>the translation string for the field header 
>("FIELD_HEADER_AUDIO_SERVERNAME"), and each form (like 
>"authentication") is transformed to the translation string for the 
>section header ("SECTION_HEADER_AUTHENTICATION").
>
>- Mike
>