This document serves as a guide to creating user sign-up forms.
Prerequisites
To follow the steps in this tutorial, you must understand your codebase's required directory structure and the user concept. You are also using the User Profiles created in a previous tutorial.
Steps
Creating a sign-up form is a two-step process:
- Step 1: Create Form Files
- Step 2: Configure Forms
Step 1: Create Form Files
Create a form to sign up developers first. Create a liquid file in the directory, and name it .
After creating the form to sign up developers, construct a form for clients by creating a liquid file in the directory named . Put together, the path to your form would now be .
Step 2: Configure Forms
After creating the two forms, configure them using the article sections below as a guide.
Developer Form
Add the following content to the sign-up form:
Notes
- : the name of the form, written in snake case. It is used to embed the form on a page.
- : defines the root resource in this form. In our example, it is .
- : defines the URL to which the system will redirect the user after success. You can use Liquid. In our example, you will redirect the user to the page.
- : defines which fields should be acceptable by the form; it's possible to define validation of each field. Depending on the , some fields are available without creating . Some of them have pre-defined validation rules due to the backend requirements. In this example, such fields are , with validation that ensures uniqueness (no two users can sign up with the same email address). The email has to be valid and can't be blank. Another field is , which has to be a minimum of six characters long (this is the default validation).
- : When a user signs up and the password is passed to the password field, Insites stores it as an encrypted password in the database. The encryption uses the bcrypt password hashing function. Besides incorporating a (cryptographic) salt to protect against rainbow table attacks, bcrypt is an adaptive function. Over time, the iteration count can be increased to make it slower, so it remains resistant to brute-force search attacks even with increasing computation power.
Configuration
Configure your form using the properties and settings explained below:
- : marked as required.
- : starts the nested form where you can decide which user defined in are accessible through this form. In this example, you added , explained in the previous tutorial.
- : this is a special abstraction to easily create the resource associated with the newly signed up . You'll learn about a similar concept later on. Within , you can specify the names of the profiles created in the directory. In our example, you have two choices: and . The is a resource, so you have access to its field. Since you created the sign-up for developer, this is what you used.
- : a special construction to add special behaviour to the field. Here you used , which provides the default value (i.e. the value that will be used if a user does not fill out this field); , on the other hand, ignores the user's input. Because the system will ignore any input by the user, the default value will always be used. This combination is useful if you want to set something in the background and do not want the user to be able to override it.
The configurations and settings described above might need to be clarified first, like what is the field. All should be clearer once you realize that the last part of the configuration, which is:
can also be represented as an independent form with a configuration like this:
In other words, forms are nested in each other – you can access them as 'nested forms'. In this example, you want to create a and a corresponding simultaneously. The user provides their first name, email, and password, and that's it - the user registers as a developer. This behaviour is desired if your UI, for example, has a page with a button that says 'Sign up as a Developer'.
Alternatively, the UI can split the process into two separate actions. It can first ask the user to register, so the button would be labelled 'Sign up'. After registration, the user is then asked if they want to sign up as a developer or a client. In this scenario, the first form would look like this:
And the second one would be similar to:
On Insites, you can create multiple resources within one form submission. The result would be the same. The configuration might be more complex, but you can enjoy a highly simplified user experience once that is set up.
Rendering Inputs
The second part of the form is the HTML the system will present to the user on the front end. You will want to include the following in every form.
: The form tag renders the tag with set based on the resource provided in the configuration. It also adds a couple of hidden inputs.
The most important ones are the CSRF token (called ) and and depending on whether you want to create or update the resource, it will be either or . To allow users to destroy their resources, you must manually pass the as an argument to the tag with the value .
Another set of hidden inputs is - the one you passed in the if any, and , , and - in case of validation errors, you most likely will need those to be available. Please note: If you want to invoke our write API manually (for example, via AJAX or even from third-party API), please visit the complete API Endpoints documentation.
Optional Inputs
: is used to notify the API which page the system should render if the submission of the form fails (most likely due to validation error). By default, it generates the page from where the user submitted the form. This behaviour allows the re-display of the user's input for all fields and displays validation errors where applicable.
Inputs
Proceeding with rendering proper inputs that the user will be expected to fill:
: utility liquid tag that can save quite a bit of work by default; it is configured to generate HTML compatible with the Bootstrap 3 framework. Moreover, it automatically adds an 'error' CSS class to the input in case of validation errors and renders a validation error message below the input.
A how-to guide is under construction for users who do not use the Bootstrap 3 framework.
Client Form
Add the following content to the sign-up form:
Next Steps
Congratulations! You now know how to create sign-up forms for your users. Now you can embed the sign-up form in a page: Embedding a Sign-Up Form in a Page.
