LFUG #20 Meetup | React Workshop

Workshop: Build and deploy a React app in Liferay.

The goal is to display a list of blogs published in Liferay. We will use GraphQL APIs to fetch this list, and use Apollo as a GraphQL client. We will use Basic authentication during development, and use Session authentication when deployed to Liferay. We will display blogs as cards using Clay components library. In each card, we want to diplay the title, subtitle, author and date. It should look something like this:

Getting Started

From scratch

To do this workshop step by step, clone this repo on develop using HTTPS or SSH:

git clone -b develop https://github.com/lgdd/lfug20-react-workshop.git
# or
git clone -b develop [email protected]:lgdd/lfug20-react-workshop.git

Then, verify the requirements and go the steps section.

Final result

If you want to try the final result, clone this repo on master using HTTPS or SSH:

git clone https://github.com/lgdd/lfug20-react-workshop.git
# or
git clone [email protected]:lgdd/lfug20-react-workshop.git

Then, verify the requirements. Initialize your Liferay bundle and start it. Add some blog posts or generate them with the Dummy Factory plugin. Go to modules/lfug-react-app, create a file named .env.local and add your environment variables. Run yarn or npm install. Finally to test the app you can run yarn start or npm run start and it should open automatically a page to http://localhost:3000 when started. You can also deploy this app to Liferay using yarn deploy:liferay or npm run deploy:liferay, login to your Liferay instance and add lfug-react-app widget to a page (e.g. Home by default).

Table of Contents

• Getting Started
  • From scratch
  • Final result
• Table of Contents
• Requirements
  • System
  • Tools
    • Blade (optional)
    • Yeoman
    • Liferay JS Yeoman Generator
    • Dummy Factory (optional)
• Steps
  • Git
  • Overview
• Cheat Sheet
  • Using a local archive to initialize Liferay Bundle
  • Initialize Liferay Bundle
  • Start Liferay
  • Stop Liferay
  • Display Liferay logs
  • Create React app
  • Start React app
  • Add dotenv dependencies
  • Add environment variables
  • Access environment variables
  • Add Clay dependencies
  • Add GraphQL & Apollo dependencies
  • Truncate text
  • Add Moment.js dependencies
  • Adapt your app for Liferay
  • Build your app for Liferay
  • Deploy your app to Liferay
  • Encode credentials to Base64
  • Access Liferay JavaScript object
• Docs
• License

Requirements

System

• JDK 1.8
• Node.js >= 10.18
• npm >= 6.13 or Yarn >= 1.22

If you have any issue with permissions or to manage multiple Node.js / npm versions, I would recommend that you use nvm.

Tools

Altair (GraphQL client for testing)

https://altair.sirmuel.design/docs/

Blade (optional)

https://portal.liferay.dev/docs/7-2/reference/-/knowledge_base/r/installing-blade-cli

Yeoman

npm install -g yo

Liferay JS Yeoman Generator

npm install -g generator-liferay-js

Dummy Factory (optional)

curl -o bundles/deploy/liferay.dummy.factory-7.2.3.jar https://raw.githubusercontent.com/yasuflatland-lf/liferay-dummy-factory/master/latest/liferay.dummy.factory-7.2.3.jar
# or
wget -O bundles/deploy/liferay.dummy.factory-7.2.3.jar https://raw.githubusercontent.com/yasuflatland-lf/liferay-dummy-factory/master/latest/liferay.dummy.factory-7.2.3.jar

It will help you test your app by generating dummy Blog posts. To access to this plugin in Liferay, go to Control Panel > Apps > Dummy Factory.

Steps

Git

Each step of this workshop is represented by a git branch (e.g steps/01-create-react-app) and its commits (e.g. Add Blog component).

This will help you to compare your current work with what needs to be achieve, catch up with the group and, of course, allow you to complete this workshop on your own if you didn't attend this event.

Overview

You'll a list of useful commands in the Cheat Sheet section to help you complete the steps described below.

• Initialize your dev environment (check system requirements, clone this repo).
• Start your Liferay Bundle and login with [email protected] / test.
• Create or generate at least 2 blog posts.
• Create your React app under a subfolder modules.
• Remove the following files that we won't be using: App.test.js, logo.svg, index.css.
• Add a Blog component using Clay.
• Add a BlogList component.
• Add a GraphQL client in App.js using Apollo.
• Update your BlogList to fetch blog posts from your Liferay instance. You will need the id, title, body and published date. Use Moment.js to enhance date display.
• Adapt your React app for Liferay (use liferay-js:adapt, use Liferay session for the authentication and update your code to check if the user is logged in and condition the rendering).

Cheat Sheet

Using a local archive to initialize Liferay Bundle

If you have already downloaded the Liferay CE 7.2 GA2 Tomcat Bundle, you can customise your Gradle properties to avoid the next step to download it again. Create a file named gradle-local.properties to the root folder and add:

# Example
liferay.workspace.bundle.url=file:///home/user/Downloads/liferay-ce-portal-tomcat-7.2.1-ga2-20191111141448326.tar.gz

Where /home/user/Downloads/liferay-ce-portal-tomcat-7.2.1-ga2-20191111141448326.tar.gz is the location of your downloaded bundle.

Initialize Liferay Bundle

blade gw initBundle
# or
./gradlew initBundle

Start Liferay

blade server start
# or
./bundles/tomcat-9.0.17/bin/startup.sh

Stop Liferay

blade server stop
# or
./bundles/tomcat-9.0.17/bin/shutdown.sh

Display Liferay logs

tail -f bundles/tomcat-9.0.17/logs/catalina.out

Create React app

npx create-react-app modules/lfug-react-app

Start React app

yarn start
# or
npm run start

Add dotenv dependencies

yarn add dotenv
# or
npm install dotenv

See dotenv.

Add environment variables

REACT_APP_LIFERAY_USER='[email protected]'
REACT_APP_LIFERAY_PASSWORD='test'
REACT_APP_LIFERAY_HOST='http://localhost:8080'
REACT_APP_LIFERAY_GRAPHQL_ENDPOINT='/o/graphql'

Access environment variables

const nodeEnv = process.env.NODE_ENV;
const user = process.env.REACT_APP_LIFERAY_USER;
const password = process.env.REACT_APP_LIFERAY_PASSWORD;
const host = process.env.REACT_APP_LIFERAY_HOST;
const endpoint = process.env.REACT_APP_LIFERAY_GRAPHQL_ENDPOINT;

Add Clay dependencies

yarn add @clayui/css @clayui/alert @clayui/button @clayui/card @clayui/loading-indicator
# or
npm install @clayui/css @clayui/alert @clayui/button @clayui/card @clayui/loading-indicator

Add GraphQL & Apollo dependencies

yarn add graphql @apollo/react-hooks apollo-boost apollo-link-context
# or
npm install graphql @apollo/react-hooks apollo-boost apollo-link-context

Truncate text

React text truncate:

yarn add react-text-truncate
# or
npm install react-text-truncate

Snippet:

import TextTruncate from 'react-text-truncate';

<TextTruncate
  line={3}
  element="span"
  truncateText="…"
  text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas hendrerit urna a dolor blandit suscipit. Aenean non turpis nec ex vestibulum tempor."
/>;

We will truncate the blog post body.

Add Moment.js dependencies

yarn add moment react-moment
# or
npm install moment react-moment

Adapt your app for Liferay

yo liferay-js:adapt

Build your app for Liferay

yarn build:liferay
# or
npm run build:liferay

Deploy your app to Liferay

yarn deploy:liferay
# or
npm run deploy:liferay

Encode credentials to Base64

JavaScript:

const credentials = new Buffer(`${user}:${password}`).toString('base64');

Shell:

openssl base64 <<< [email protected]:test

Warning: Encoding a string as shown here does not encrypt the resulting string. The encoded string can easily be decoded by executing base64 <<< the-encoded-string, which returns the original string. Anyone listening to your request could therefore decode the Authorization header and reveal your user name and password. To prevent this, ensure that all communication is made through HTTPS, which encrypts the entire message (including headers).

Access Liferay JavaScript object

export function Liferay() {
  return window['Liferay'];
}

See Liferay JavaScript APIs

Docs

• https://github.com/liferay/liferay-js-toolkit/wiki
• https://portal.liferay.dev/docs/7-2/frameworks/-/knowledge_base/f/get-started-discover-the-api
• https://portal.liferay.dev/docs/7-1/tutorials/-/knowledge_base/t/liferay-javascript-apis
• https://www.apollographql.com/docs/tutorial/queries/#fetching-a-list
• https://clayui.com/docs/components/card.html
• https://github.com/motdotla/dotenv#dotenv
• https://reactjs.org/docs/getting-started.html
• https://graphql.org/learn/

License

MIT