edgeryders / edgeryders-form Goto Github PK

For some use cases of this software (such as event RSVPs for smaller events such as workshops), everyone posting their response as a new topic to Discourse is a bit … heavy, cluttering the category with topics that are very short and do not get many responses.

For these cases, this software should also support to post the form submission as a new post to the end of an existing topic. One would choose the desired behavior via the configuration file.

We would like to use this software for multiple installations, doing different jobs, in such a way that we don't have to fork or branch the repository for each new use case. In addition, we would like a way to adjust questions and styling without having to add it to the git repository – though to keep everything organized, the option to do so should still be there.

Proposal:

1. Provide a way to use a new sub-folder for each new use case, concentrating everything in there: logo, favicon, the *.json* configuration files, the Vue.js .env.* configuration file and a CSS stylesheet for the form. This way, the sub-folder can be added to the software's one and only Git repo, or to .gitignore. Careful: the auth_key secret in .env.* must not end up in Git. Also, the mechanism of styling a form with a separate CSS stylesheet does not yet exist.

2. Provide a way to build the deployment for a certain use case (= using a certain sub-folder) by adding the sub-folder's name as a parameter to yarn run build.

Currently, when somebody enters only whitespace as their name / nickname into the form, the software will accept that value, trim off the whitespace, append a 1-2 digit suffix like "_12", and send that to the Discourse server. The server will trim the whitespace, and if the username is then long enough, create that user. So the user will have a username like @_12, which is ugly and should not happen.

The same applies to most special characters (excl. "-" for example, which is rather converted to "_") by this software.

Instead, when the username after trimming and before adding the suffix is empty, the user should be requested to correct it. No request should be sent to the server at this point.

There is a Discourse setting "min username length". Trying to create a username with fewer characters will result in status code 422 "Unprocessable Entity" with this response:

{
    "success": false,
    "message": "Username must be at least 3 characters",
    "errors":{
        "username": ["must be at least 3 characters"]
    },
    "values":{
        "name": "ab",
        "username": "ab",
        "email": "[email protected]"
    },
    "is_developer":false
}

This software does not yet react to this case adequately, as it will simply show the error message used for other username related errors, which is:

It seems somebody has already chosen your preferred username / nickname. Please enter a different one and click again on "Send".

So it needs one more error case, and an appropriate message for it.

The form obviously has to include the question in enough detail to answer them, but the generated posts on the Discourse forum only have to include the questions in enough detail to understand what the answer is about.

Currently, it is not yet possible to include two versions of the question in this way. Would be nice to have! The short version for Discourse would be optional. If not provided, the long version will be rendered into the Discourse topic.

Currently, when the cursor is in a text field and one pressed the ← or → arrow key to move the cursor to the next character, that will happen but a split second afterwards the slide will move to the next or previous slide. So cursor navigation in the text is not possible right now and one will have to use the mouse instead.

Proposal: Instead use the Page Up / Page down keys for moving to the next or previous slide. Or just use no keybindings for that at all.

People who use this form but already have an account on the targeted Discourse forum will see this error message when submitting the form in the last step:

It seems you already have an account on our forum using this e-mail address, or have entered an invalid address. Please choose a different e-mail address and click again on "Send".

This is very late to tell them, so we need a solution for this case. Options include:

1. A hint on one of the first slides, telling people where on the Discourse forum to post directly if they already have an account. This can be done with a link that opens a pre-filled editor for a new Discourse topic.

   This solution would be ok at first, but for the medium term, one or more of the following solutions would be better to a have the same, simple flow as the user experience for all users of the form..

2. Providing the questions plus their responses in Markdown format to simply copy & paste into a new topic in Discourse.

3. Allowing people to enter their e-mail address or username, and password, of the targeted Discourse forum, and posting with that information. This is probably difficult to implement as Discourse is not meant to be accessed like that – other applications are supposed to use User API keys, but connecting such an application to ones Discourse account is not a good user experience …

Currently, the title used for the Discourse topic created with a form submission is hardcoded here as:

Rethinking retirement - response by ${formField(form, 'name')}

It should be configurable in the src/assets/data/*.json files.

So far, checkboxes can be included in normal slides, such as in the following example slide object:

{
    "index": 2,
    "title": "Select your events!",
    "body": "Please select the event(s) you want to register for.",
    "fields": [{
      "name": "hack4env",
      "type": "checkbox",
      "placeholder": "Hack 4 Environment",
      "required": false,
      "settings": { "omit": true }
    }]
  }

However, the checkbox answers are not yet included in the generated Discourse post.

This may have to do with the "settings": { "omitFields": true } slide setting or with the "settings": { "omit": true } field setting – to be tested.

The UL element is used for several purposes in this application: the progress dots of the slideshow, form fields etc.. For that, it is styled as:

 ul {
  list-style-type: none;
  margin: 0;
  padding: 0;
}

That however prevents its original use as "unordered list" in field intro texts etc.. So better keep it as styled by the user agent by default, and apply the above changes only when a certain class or attribute value is present.

So far, a quick fix has been added in this commit. However this just re-creates the (approximate) user agent styling of the UL element for the p.body field intro texts. The UL element is still changed by default.

Observed in the configuration of a checkbox field item, but not yet documented in the README.

Currently, one src/assets/data/*.json file is used to provide the complete form for one language, so the form structure is redundantly contained in the .json files. Due to this, the danger of modifying one .json file and getting the settings / structure of the form out of sync with the other translations is somewhat high.

If this software starts seeing heavier use, it would be better to split the structure of a form (what fields it has, how it behaves, what fields are required etc) from the content (what the titles / buttons / fields say in whatever language is selected). This will allow us to throw a translation file up on something like Transifex and allow the community to update translations without needing any technical ability.

To minimize the development effort, this should only be implemented if and when switching to QML as the language to define the user interface.

Some users might not be comfortable to give their real e-mail address, but might still want to fill the form in order to register at an event etc.. The software could facilitate this by providing a checkbox "create and use a disposable e-mail address". Checking it would disable the e-mail address field, as using it is no longer required then.

When that option is checked, the software would generate a random e-mail address for a provider of disposable e-mail addresses. For some providers, this is possible using just random characters and does not require talking to a remote API. Discourse would then send the account confirmation e-mail and all future notification e-mails to that disposable e-mail address. On the confirmation screen, the user would be provided the information how to access that e-mail address: the e-mail address, the associated password, and a link that combines both to "check ones inbox". By copy&pasting that information somewhere, they can use that e-mail address just like a "normal" e-mail address, including for the password-less login, to reset their password etc..

(This is for a future extended version with additional features.)

If a user cannot post to the target Discourse site, they should still not lose their input text – because they probably spent quite some time composing the text. Currently, they could hit the "Back" button multiple times and copy & paste the text field input from the form fields one by one to somewhere external. That works, but is not a comfortable solution, and not all users might get the idea.

Alternative proposal: On the page showing the error message, also provide the Markdown formatted text with questions and answers as it would be posted on Discourse, alongside with a note saying something like this:

Your input is not lost of course! If the error persists, you can also copy out your answers below and post them on the Discourse site after opening an account manually.

See also #8, where the same proposal is made for the more specific failure case of people already having an edgeryders.eu account.

This should go into README.md but is not yet there.

Basically: create a file src/assets/data/{lang}.json for each language. The basename of the file will be displayed in the language chooser on the frontpage of the application. Usually, you'd use a two-letter language code for the basename, so en.json, sl.json etc..

So far, the titles of the Discourse topics generated by this software are automatically generated. When there are many of these topics, it makes for uninviting material in the category overview.

So instead, let's add a field that lets users define the topic title. It can still be adapted by the software using prefix / postfix strings. For that, a simple template string system should be used, allowing to configure the title format in the JSON configuration file. JSON does not support any templating syntax on its own, but the ${varname} JavaScript (ES2015) template literals seem like a good choice.

Currently, the HTML title set in the header is always "edgeryders-form", which is not always adequate 😄

However, there is already a property in the src/assets/data/*.json files in "brand → title" that seems meant for supplying the HTML page title. So let's use that one.

On the last slide (confirmation of submission), it would be very useful to have a way of linking to the topic created on the targeted Discourse site in response to the user's input.

Proposal: This should be a placeholder variable that can be used in the strings in the JSON files. JSON does not support any templating syntax on its own, but the ${varname} JavaScript (ES2015) template literals seem like a good choice.

We already have two different JSON formats for different types of forms, the other one being used in edgeryders/forms. In the medium term, we should try to standardize our language to define forms / use interfaces.

Proposal: Use QML, resp. a subset of QML for the forms builder applications. This could build on one of the existing mechanisms to use QML for web applications (PureQML or qmlweb; see also qmlweb examples).

The forms generated by this software do not include a full "consent funnel" mechanism, and including one would make the form as cumbersome as a full signup. As a workaround, we have checkbox-style consent on the last slide.

However, as a proper solution, that checkbox-style consent should apply to only the form-generated topic posted to edgeryders.eu, not to anything posted directly on Discourse, such as replies and other new topics. This needs a post-level consent mechanism in Discourse, which is not yet present but could be created with a custom field. It should be on the level of posts, not topics, because we might want this form to also be able to generate comments rather than full new topics in Discourse later (see #22).

So far, users only get an e-mail from the communities.edgeryders.eu site that an account has been created for them, and that they should confirm their e-mail address.

In addition, users should get an e-mail with the link to the post published on the Discourse platform, plus information about how to log in, change their post if needed, or reply to comments.

Implementation options:

• A bot sending the users a direct message, similar to the Discourse Narrative Bot plugin.

• An e-mail sent using a new, custom e-mail template (similar to the Welcome User template).

Not sure yet how the software would recognize what topics have been submitted by the form builder software, to trigger the e-mail or direct message sending. For example, these topics could have a custom field set to a certain value.

(This feature will have to be implemented for the most part in Discourse, but is a feature of this software from a user perspective. So let's keep the issue here, and create a corresponding one on Discourse when we get to implementing this.)

After a few days of use, we already manage four forms with this software 🙂 So far, that has to happen with four installations, meaning configuring four domains, adding the CORS origin four times to two Discourse sites etc..

Setting up a new form will be faster and more comfortable when one installation would manage multiple forms, with each form hosted in one sub-folder as proposed in #12. URLs would then look like https://forms.example.com/formname. When opening https://forms.example.com/ instead, one would instead see a selection dialog of all available forms.

In #17 , we plan to have separate links for separate forms, all managed by one installation of this software. In addition, it would be nice to have a way of linking to each language version of such a form directly:

https://forms.example.com/formname/en
https://forms.example.com/formname/pl
...

For outreach efforts, this may be useful, as then for example the Polish version can be linked directly from a Polish tweet etc..

The application is configured via files src/assets/data/*.json. Some of the strings (for example "body": " …") accept HTML, while others don't (for example "subtitle": "…"). To prevent surprises, all strings that are rendered into a webpage at some point should accept HTML.