Hello Magnolia - with content via REST

On this page we describe how you can create and use a component whose content is retrieved through REST from an external API.

The page is an extension to Hello Magnolia, an introductory Magnolia tutorial showing how to leverage the Magnolia light module functionality to create a web page.

Hello Magnolia tutorial - a quick recap

The product of the Hello Magnolia tutorial is a light module called hello-magnolia that contains a component used on a page called hello. When published to the public instance, the page displays two elements in addition to the page title: a quotation and the quotation’s author. On the author instance, editors can change the content of both these elements in a dialog called quotation:

Hello Magnolia Quotation dialog

Prerequisite: A Magnolia setup

Let’s proceed from here, but first make sure that:

Magnolia CLI is installed on your system.
If it isn’t, please install it by following the instructions on the Magnolia CLI page.
You have a running Magnolia instance.
If you don’t have Magnolia installed and running, go to the page called Installing Magnolia through npm CLI and complete the steps described on it.
The hello-magnolia light module is installed in Magnolia.
You can get a copy of the hello-magnolia light module by cloning it from a branch in our Documentation repository to the folder defined by the magnolia.resources.dir property. If you installed Magnolia using CLI, it is the light-modules folder, located in the root of your Magnolia installation:
```
<your-Magnolia-installation-folder>
├── apache-tomcat/
├── downloads/
└── light-modules/
    └── hello-magnolia/
```
Clone the module to the light-modules folder by executing this command:
```
git clone --branch lmo-tutorial-base/6.1 https://bitbucket.org/magnolia-cms/hello-magnolia.git
```

Enhancements

In the steps that follow you:

Create and configure a REST client in the hello-magnolia light module for GET requests to the https://programming-quotes-api.herokuapp.com API. This particular API service is convenient in that it doesn’t require an API key.
Create a new page component called Random Programming Quotation, which will retrieve and render the English quotations from the API service.

The tree structure of the hello-magnolia light module before and after the enhancements:

Before
After

hello-magnolia/
├── decorations/
├── dialogs/
│ ├── components/
│ │ └── quotation.yaml
│ └── pages/
│ └── hello.yaml
├── templates/
│ ├── components/
│ │ ├── quotation.ftl
│ │ └── quotation.yaml
│ └── pages/
│ ├── hello.ftl
│ ├── hello.html
│ ├── hello.yaml
│ └── index.html
└── webresources/
    └── css/
        └── hello-style.css

hello-magnolia/
├── decorations/
├── dialogs/
│ ├── components/
│ │ └── quotation.yaml
│ └── pages/
│ └── hello.yaml
├── restClients/
│ └── programming-quotations.yaml
├── templates/
│ ├── components/
│ │ ├── quotation.ftl
│ │ ├── quotation.yaml
│ │ ├── random-programming-quotation.ftl
│ │ └── random-programming-quotation.yaml
│ └── pages/
│ ├── hello.ftl
│ ├── hello.html
│ ├── hello.yaml
│ └── index.html
└── webresources/
    └── css/
        └── hello-style.css

After the changes, the module contains one new subfolder and three new files:

Lines 8 and 9: The subfolder and a YAML template file containing a REST client configuration for the quotation API service.
Lines 14 and 15: An FTL template script and a YAML template definition for the new Random Programming Quotation component.

Creating a REST client configuration file

In the root of the hello-magnolia module, create a new subfolder called restClients. In this subfolder, save the following configuration to a new file called programming-quotations.yaml:

/hello-magnolia/restClients/programming-quotations.yaml

baseUrl: https://programming-quotes-api.herokuapp.com
restCalls:
  random:
    method: get
    entityClass: com.fasterxml.jackson.databind.JsonNode
    path: /Quotes/random/

After saving the file, you can check in the Definitions app that this client configuration has been registered:

Definitions app

Creating a RESTful component

Stay in the root of the hello-magnolia module. Use the following Magnolia CLI command to create the random-programming-quotation component. The command will make it available in the main area of the page template:

mgnl create-component random-programming-quotation -a pages/hello@main

The command creates the following files:

/hello-magnolia/dialogs/components/random-programming-quotation.yaml
You don’t need this file for the present use case. Delete it.
/hello-magnolia/templates/components/random-programming-quotation.yaml
This template definition gives the component a name and makes the component available to the system.
/hello-magnolia/templates/components/random-programming-quotation.ftl
The template script renders the content of the component.

Edit the component’s template definition

Open the random-programming-quotation.yaml file and:

Delete the line referring to the dialog template.
Rename the component’s title to Random Programming Quotation. The title will be displayed in the list of templates when you choose a template for a new page.

The result to be saved should look like this:

/hello-magnolia/templates/components/random-programming-quotation.yaml

title: Random Programming Quotation
renderType: freemarker
templateScript: /hello-magnolia/templates/components/random-programming-quotation.ftl

Edit the component’s template script

Open the random-programming-quotation.ftl template script and save it with the following code:

/hello-magnolia/templates/components/random-programming-quotation.ftl

${ctx.response.setHeader("Cache-Control", "no-cache")}
[#assign randomQuote = restfn.call("programming-quotations", "random")]

[#if randomQuote?has_content]

<blockquote>
    <p>${randomQuote.en.textValue()}</p>
    <cite>${randomQuote.author.textValue()}</cite>
</blockquote>

[#else]

<pre>An error occurred. The endpoint may be offline or returns null values.</pre>

[/#if]

Notes

Line 1: Without the no-cache setting, the changing content of the REST response would not be accessible when reloading the page since the server by default caches the rendered HTML page.

Lines 7 and 8: The expressions randomQuote.en.textValue() and randomQuote.author.textValue() will print what is stored in the en and author properties, respectively.

All the necessary changes in the code are now done. In the next steps you:

Create a new page called hello-rest, using the Hello template.
Add the new Random Programming Quotation component to the page, save the page and publish it to the public instance.
On the public instance, check that the hello-rest page is accessible and that it displays random quotations and their attributions whenever you reload the page.

Creating a new page

Go to the App launcher and click the Pages tile to open the Pages app.
To add a new page, click Add page from the Action bar on the right-hand side.
In the Add page dialog:
1. Use hello-rest for Page name.
2. Choose the Hello template as the page template.
3. Click Next.
In the Page properties dialog, enter RESTful Hello Magnolia into the Title field.
Click Save changes.

Adding the RESTful component

Open the hello-rest page in the Pages app.
Click the New Main Component + button.
Select the Random Programming Quotation component:

Click Next.
At this point, you should be already receiving some content from the quotation API service. For example, a quotation by Joseph Yoder:
Preview the page by clicking Preview page in the Action bar on the left. The Preview action should fetch a new quotation from the API.
Publish the page to the public instance by clicking Publish.

Seeing the result on the public instance

Finally, access the web page on the public instance: http://localhost:8080/magnoliaPublic/hello-rest.html. The following screenshot shows a quotation by Bob Carr, fetched from the quotations API:

Result on Public instance