💾 Archived View for rawtext.club › ~sloum › geminilist › 004921.gmi captured on 2024-03-21 at 16:47:09. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Proposal: Simple structured form specification

Russtopia rmagee at gmail.com

Tue Jan 26 07:17:29 GMT 2021

- - - - - - - - - - - - - - - - - - -

Hi all,I have just started to get into Gemini, now running a simple server locallywith the Kristal client to test things out.

Reading the draft spec, I see there are only two ways to obtain input fromtheuser -- via responses 10 and 11 (INPUT and SENSITIVE INPUT).

While this allows simple single-field entry of values to the server, thereappears to be no facility to allow users to enter multi-field, structureddata in a single operation -- that is, simple forms.

If it does not violate the fundamental tenets of the Gemini project, Ihumblysuggest an extension to the syntax of gemtext in the following manner toenable structured multi-field forms. The logic and work here would be ~90%onthe client side, as it is mostly a convention for encoding structured formswithin .gmi documents, parsed and acted on by the client. Form submissionwould require no additional core server-side logic; interpretation ofsubmitted form values would follow the standard patterns of request handlingwith URL query parameters.No client or server state would be introduced.

I have used an encoding similar to what follows successfully in a past'minimal HTML' project, to generate simple forms dynamically (but on theserver-side). I hope it might serve well to allow Gemini users a moreconvenient way to interface with back-end programs, whilst preserving theoverall ethos of minimalism and privacy.

If the idea of adding a new link type to the gemtext specification isanathema,please consider the proposal as a purely client-side convention,displayed but otherwise ignored by existing clients as part of the<USER-FRIENDLY LINK NAME> portion of the existing '=

' syntax instead.

PROPOSAL5.5.4 Link line form encoding

Lines beginning with the two characters "?

" are form-link lines, whichfollowthe same rules as standard Link lines [5.4.2], plus a <FORM-SPEC> sectionpreceding the <USER-FRIENDLY LINK NAME>:

[<whitespace>]<URL>[<whitespace>]<FORM-SPECS><whitespace>[<USER-FRIENDLYLINK NAME>]

where:

<whitespace

is any non-zero number of consecutive spaces or tabsSquare brackets indicate that the enclosed content is optional.<URL> is a URL, which may be absolute or relative.<FORM-SPEC> is a list of one or more <form-field-specifier> items, separated by the Unicode/ASCII forward-slash '/'. The client uses <FORM-SPEC> tobuild a form entry popup, dialog, or series of input prompts to gather structured user input.

Each <form-field-specifier> follows the form

T#VAR#DEFVALUE#LABEL

where T ∊ [ s | c | b ]

's' denotes a string (freeform data) field;'x' denotes a string/number SENSITIVE field, which the client MUST shroud as password-type data;'c' denotes a choice (dropdown/one-of) field;'b' denotes a boolean ( checkbox, yes/no ) field

's' fields are freeform text, and may be used for numbers, text, or freeform data. It is the server's responsibility to validate submitted data.For 'c' fields, the first choice is the default, all following choices being delimited from it and each other by the pipe '|' character.For 'b' fields, allowable DEFVALUEs are [0 | 1], [yes | no], or [on | off].The client is responsible for detecting these and returning sensible counterparts to the DEFVALUE if the user chooses their opposites.

VAR denotes the name of the form variable when submitting back to the server upon submission.DEFVALUE denotes the default value to be displayed in the form. For choice type fields, the first item in the choice list is the default.LABEL is text to be displayed by the client explaining the form field.Clients MUST use the VAR field as a default LABEL if the .gmi link omits one.

A valid <FORM-SPEC> field is of the form

<form-field-specifier>{/<form-field-specifier>/...}

Example - three field form requesting a string, a choice, and a boolean

s#DELAY#5#Delay in seconds/c#SIZE#small|big|huge#Size ofsomething:b#DEBUG#1#

Note the above example has no LABEL for the final form field, so the client should render a default label using the form variable's name, 'DEBUG'.This would instruct the client to display a form, popup or series of prompts (in the case of a text-based client) to enter three items.The choice field would default to 'small', the first item in its set.The client would return a URI upon submission with the query parameters

?DELAY=5&SIZE=small&DEBUG=1

if the user submitted with default values.

A fully-realized example of this proposed syntax would thus be

gemini://example.org/formSubmit s#DELAY#5#Delay inseconds:c#SIZE#small|big|huge#Size of something:b#DEBUG#1# Please fill outthis handy form

Suggested limits on form structure and data

Max <form-field-specifiers>: 8Max <form-field-specifier> sub-field lengths (VAR, DEFVALUE, LABEL): 255 Unicode charactersMax 'c' type choice length per item: 64 Unicode charactersMax 'c' type choices: 64Max 's' value: enforced by server-side endpoint handler-------------- next part --------------An HTML attachment was scrubbed...URL: <https://lists.orbitalfox.eu/archives/gemini/attachments/20210125/f3a3aeec/attachment.htm>