Your First Page
Once you’ve signed up for an account you’ll be able to create you first project. You can name it whatever you want but “Tutorial Project” is fine for our purposes. The first thing we can set up is a new service. Our Tutorial Project will be based on the JSONPlaceholder service.
New Service
Navigate to the New Service form by clicking the “Services” option in the side menue and then clicking the “New Service” button. Enter the following information into the New Service form:
Name: JSONPlaceholder
Description: Free fake and reliable API for testing and prototyping.
These are just descriptors for your own bennefit.
Hostname environment variable: JSONPLACEHOLDER_HOSTNAME
The hostname environment variable is the name of the environment variable that the Pageous runtime will use to lookup the hostname of this service. This can be whatever you want but when you are running the build of your project you will need to pass this environment variable set with the hostname of the service, which in this case is jsonplaceholder.typicode.com.
For this service you can leave “REST headers” blank but this would be the place where you can set HTTP headers that will be sent with every request. For example setting REST headers to the following can be useful if the service can respond with multiple content types:
Content-Type: application/json
Accept: application/json
Finally select the protocols that this service supports. For JSONPlaceholder we can just select https.
Clicking the “Create Service” button should successfully create the service.
New Layout
Now we can create a layout, navigate to the New Layout form by clicking “Layouts” in the left menu and then clicking the “New Layout” button. Enter the following information into the the New Layout form:
Name: Basic Layout
This should autofill the reference to basic_layout. This is fine, we don’t need to worry about the reference for now.
Description: The basic layout for the application.
Again this is just a decription to help you maintain your application.
Content:
<html>
<head>
<title>
{{metadata.title}}
</title>
</head>
<body>
{{{content}}}
</body>
</html>
This is a very simple layout, the most important things to know are that layouts use the Mustache template language.
{{{content}}} is where the page template content will be inserted.
The {{metadata.title}} tag means that this content will be populated from the title key of the page’s metadata.
More on this later.
Click the “Create Layout” button to create your new layout.
New Template
A template is this next thing we want to create so click “Templates” in the left menu and click the “New Template” button. This form should look familiar. Let’s fill it out:
Name: Show User
Description Show the user details.
Content:
<h2>{{root.name}}</h2>
<p>Username: {{root.username}}</p>
<p>Email: {{root.email}}</p>
<p>Phone: {{root.phone}}</p>
<p>Website: {{root.website}}</p>
Here we’re introduced to a new data namespace: root. Under root you can access the data that has been requested from the service.
We’ll be making a page to display user details so you can look at https://jsonplaceholder.typicode.com/users/1 to see the shape of the data we’ll be dealing with for this page.
New Page
Ok, now we get to pull all the pieces we’ve created so far into a page. Click “Pages” on the left menu and click the “New Page” button. Fill this form in as follows:
Name: Show User
Description: Show a user’s details.
Route: /users/{id}
The route here is the path that this page will be displayed at when navigated to in the browser.
Routes can contain variables like {id} here.
This route will match /users/1, /users/jim, etc.
The contents of the variable will be captured and can be used later.
Metadata:
{
"title": "Show User"
}
As mentioned earlier, metadata from the page will be available to the templating language when rendering the layout and the template. Setting this will set the content of the title element in the layout.
Template: Show User
Select the template we created earlier.
Layout: Basic Layout
Select the layout we created earlier.
Request definition type: Generate Default
This dropdown determines how our new page will request data. None means that the page will make no requests, it will essentially be a static page. Select Existing will allow you to select requests from a list of requests that you have defined via the New Request form. Since we have not defined any requests yet let’s choose Generate Default. This option will generate a request definition automatically for this page. This will generate a request definition that uses the same route as the page to make a request to the service.
Service: JSONPlaceholder
Click “Create Page” to submit the form. This will redirect you back to the Page details where you can see the generated request definition under “Requests”. Feel free to click into it to understand what was generated.
Time to Test
On the page details of “Show User” there’s a section called “Previews”, click the “New Preview” button. Since this is the first preview on a page with a single request most of the fields will be autofilled for you. This is fine, scroll down to the JSON field and paste some sample data from JSONPlaceholder:
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "[email protected]",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
}
Click the “Create Preview” button and this will redirect you back to the page details. Notice that there’s now an entry under the “Previews” header. Click the “Render” option on the preview and this will open the preview of the page we created.
Congratulations!! You’ve just created your first functional Pageous project. Of course this is just the basics and there are still more features to explore but this is already enough to get started.