A Detailed Guide On How To Access EzContent on Gatsby

EzContent is a powerful tool for managing content, but when combined with a leading front-end framework like Gatsby, it shines the brightest.

Gatsby is an open-source site generator; it renders the views in advance to reduce the burden on  APIs and other backend systems. It fetches data from EzContent and then uses it to generate pages at build time. This practice ensures faster speed, ease of deployment, easy update process in the CMS, and user-friendly editorial interface. Gatsby is an all-inclusive framework that allows you to build and manage your digital content and modern experiences on the fly.

In our previous blog, How To Setup EzContent on Platform.sh - Part 1, we learned how to deploy EzContent on Platform.sh to access its demo content. 

Through this blog, we will learn how to access the same demo content on a decoupled application (Gatsby). 

How to Access EzContent on Gatsby

EzContent article components are built and maintained for Drupal front-end (coupled) and decoupled front-ends on Angular, React, and Gatsby. 

We have created an NPM module - ezcontent_jsonapi, which acts as a JSON API translator. This library works with EzContent only. It deserializes the exposed JSON API from EzContent and alters the response to make it consumable for its different front-ends.

To access EzContent on Gatsby:

1. Create another empty project on your platform.sh dashboard. You can name it EzContent-Gatsby and deploy it in the US region:
   
   

Meanwhile, take a step back and make some quick configurations in the Drupal backend.

2. Check whether the EzContent API module is enabled or not. If it is not enabled, select it and install the module:



Click Install. You might be prompted to enable additional dependency modules, which are required by the EzContent API. Click Continue to proceed:


3. You can now find a new auto-generated user by the name of ezcontent.api. Create the password for this user, select the API user role, and Save. This user enables the communication between your decoupled application and the Drupal backend.

4. You now have to generate the keys. Go to Configuration > People > Simple OAuth > Settings and select Generate Keys. Select the directory where you want to store the keys. Also, You can select the tmp folder and add the public key and private key. Click Save to continue:

5.  The back-end configurations have been completed successfully. Now, you have to set up the EzConten-Gatsby project. You will notice on the dashboard that the EzContent-Gatsby project has been successfully created:



Now that the EzContent-Gatsby project is visible in the dashboard, select the project and follow the steps in blog 1 to set it up on your local machine.

6. You now have to add the application code to the project. Visit platformsh-ezcontent to access the Gatsby folder and obtain the Gatsby application code.

7.  Add routes.yaml and services.yaml inside the .platform folder:



They can be left empty.

8. The folder structure should look like this:



Add some environment variables for decoupled applications to communicate with the backend. You can use the commands mentioned below to add the values to platform.sh. Replace XXXXXXXXXX  with the actual values. When you type the commands, you will be prompted with certain questions:

API_HOST and DRUPAL_HOST values are the URLs that enable access to the backend, as displayed in the image below:

platform variable:create --level project --name API_HOST --value XXXXXXXXXX --visible-build true --visible-runtime true


platform variable:create --level project --name DRUPAL_HOST --value XXXXXXXXXX --visible-build true --visible-runtime true

AUTH_USERNAME and AUTH_PASSWORD

platform variable:create --level project --name AUTH_USERNAME --value ezcontent.api --visible-build true --visible-runtime true

platform variable:create --level project --name AUTH_PASSWORD --value XXXXXXXXXX --visible-build true --visible-runtime true

 

CLIENT_ID and PREVIEW_SECRET hold the same value.

CLIENT_SECRET is the first 13 characters of your CLIENT_ID.  


For example:

Assume the CLIENT_ID is 7cc8ea2b-1234-567-57ac-e35a3781a11a, then the CLIENT_SECRET  will be 7cc8ea2b-1234.

platform variable:create --level project --name CLIENT_ID --value XXXXXXXXXX --visible-build true --visible-runtime true


platform variable:create --level project --name CLIENT_SECRET --value XXXXXXXXXX --visible-build true --visible-runtime true


platform variable:create --level project --name PREVIEW_SECRET --value XXXXXXXXXX --visible-build true --visible-runtime true

NODE_ENV and NO_MIDDLEWARE

You can execute the commands with the default values:

platform variable:create --level project --name NODE_ENV --value dev --visible-build true --visible-runtime true

platform variable:create --level project --name NO_MIDDLEWARE --value true --visible-build true --visible-runtime true

9.  After providing the environment variable, you can push the code to platform.sh using the platform push CLI command platform. It takes some time to execute, as all the dependencies will be downloaded and the application will be deployed.

10.  You can now access the Gatsby site using the URL provided under the EzContent-Gatsby project - Projects > EzContent-Gatsby (project name) > Master > Overview:

How To Manually Enable Gatsby Live Preview 

By default, Live preview is disabled on master environments. However, you can manually set it up in your development environments. After it is enabled, you can edit content within Drupal. As a result, the content (title, summary, and body) will be automatically updated on Gatsby.

Ensure that there are at least two articles in Drupal, before attempting to update an article's image. Gatsby is temporarily unable to locate the article during the update; sothe environment will have to be redeployed. As long as there is more than one article, you will not face this issue.

Branch off to master a new development environment.

Enable Gatsby modules in Drupal admin, as illustrated in the image below:

Within the Drupal admin section in the specific development environment, click Gatsby Settings in the Configuration/Web Services section.

Update the following fields and save the new configuration:

Gatsby Preview Server URL: the root url for your environment (https://<dev-env-name>-<hash>-<projectId>.<region>.platformsh.site/)

Incremental Build Server Callback Hook(s): <root-url-above>/__refresh

Entity types to send to Gatsby Preview and Build server:

• File
• Content
• URL alias

Update an article. Click on any of your articles and update the fields. Open a new tab to the front-end Gatsby site and view the live updates of the article.

Wrapping up

Unlock the complete potential of EzContent and leverage its out-of-the-box capabilities and enhance the performance of your static Gatsby site, all at the same time. Use EzContent + Gatsby to leverage the features you need for what’s next in the world of open-source. Tell us about your experience in the comments section.