Adding a Form

Let’s continue with Tutorial Project and add a form to it. We need a page to display the HTML of our form to our users. So, first let’s make a template for our form.

Name: New User Form Template

Description: The template for the new user form.

Content:

<form action="/users" method="POST">
  <label for="user_name">Name</label>
  <input type="text" name="name">

  <label for="user_email">Email</label>
  <input type="text" name="email">
  
  <input type="submit" value="Submit" />
</form>

Now let’s make a page with that template:

Name: New User Form Page

Description: The page that displays the new user form.

Route: /users/new

Metadata:

{
  "title": "New User"
}

Template: New User Form Template

Layout: Basic Layout

Request definition: None

Ok, great now we can create our form. Navigate to the New Form page by clicking “Forms” in the left menu and then clicking the “New Form” button. Fill the form in with the following:

Name: New User Form

Description: Form to create a new user.

Route: /users

The route should match the action attribute of the HTML form in your template.

Method: POST

Method should match the method attribute of the HTML form in your template.

Mutation definition type: Generate Default

Again, we can use the “Generate Default” option here because the endpoint we want to hit on our service is the same as our form endpoint.

Service: JSONPlaceholder

Success response type: Redirect

The success response type determines what happens when your form submits successfully. It can either render a template or it can redirect to a page. We want to redirect to the Show User page of the user we just created so we select “Redirect” here.

Redirect page: Show User

You may wonder how we can redirect to the Show User page since it doesn’t have a static route, the route is /users/{id}. By default variables in redirect page routes will be filled with data from the service response. This means that Pageous will look for id in the response from JSONPlaceholder and reify the route before redirecting to it. This works in our case but the are more advanced ways to configure this.

Failure response type: Redirect

Like the success response type but for submission failures.

Redirect page: New User Form Page

Click the “Create Form” button.

Final Touches

We’ve created our form now we just need to do a couple more things before we’re finished. Let’s add a link to the New User Form Page from our Show User Template. Navigate to “Templates” and click “Edit” on the Show User Template. Add the following line to the bottom of the content:

<a href="/users/new">New User</a>

If you preview the Show User Page now, you’ll see the new link. Clicking it will bring up the “Preview Not Found” page. This is because we haven’t created a preview for the New User Form Page yet. We can quickly do that, it’s easy since there is no request for this page.

After creating the new preview we can refresh the Show User Page preview. Clicking on the “New User” link will now take us to the New user Form Page preview. If you have more than one preview of a page you can control which preview gets shown when clicking on links by marking a preview as “Default” using the checkbox on the “Edit Preview” page. Also, clicking the submit button will take you to the preview of the success redirect page of the form.

Of course at the moment these are just previews. How do we get this running live making real requests to JSONPlaceholder? That’s what we’ll cover next to finish off this tutorial.