@smclab/create-react-app-liferay-proxy NPM

Liferay Proxy for Create React App

A JavaScript module that allows you to develop your adapted create-react-app in development mode without deploying the application to Liferay.

With this module you can use Liferay resources as theme style, translations, user name and so on.

Getting Started

Adapt your Create React App application

This module works for adapted applications, that means that you need to first adapt your Create React App application by following the official guide.

Install this module

Add this module to your development dependencies:

npm install --save-dev @smclab/create-react-app-liferay-proxy

Or if you use Yarn:

yarn add --dev @smclab/create-react-app-liferay-proxy

Proxy setup

If you don’t have a proxy already create a src/setupProxy.js file in your application folder, and add the following code to it:

module.exports = require("@smclab/create-react-app-liferay-proxy");

If you already have that setup file, or if you need some custom proxy along side the one created by this module then you need something similar to the following code:

const setupLiferayProxy = require("@smclab/create-react-app-liferay-proxy");

module.exports = app = {
  // Your custom code here that uses 'app'

  setupLiferayProxy(app);
};

This configuration enables a new development-only route /proxy-liferay-environment.js that can be used to initialize the proxy on the client side.

Proxy activation

We now need to statically include the proxy on the client. To do so modify the public/index.html file to use the new available route, by adding the following code to your head code in your <head>:

 <head>
   ...
   <title>React App</title>
+  <script src="/proxy-liferay-environment.js"></script>
 </head>
 <body>
   ...

Proxy environment configuration

In order to use the benefits of this module, we need to create a environment file in which we specify all the Liferay Portal CE / Liferay DXP information.

If you don’t have it already, create a .end file in the root of your project.

Then add to .env the following content, and edit it with your porject’s default values.

PORTAL_URL=http://localhost:8080
PORTAL_AVAILABLE_LANGUAGE_IDS=
PORTAL_USER_ID=
PORTAL_COMPANY_ID=
PORTAL_THEME_SERVLET_CONTEXT_NAME=
PORTAL_USER_LANGUAGE_ID=it_IT
PORTAL_USERNAME=
PORTAL_PASSWORD=
PORTAL_SCOPE_GROUP_ID=12345

⚠️ Attention! Do not store IDs and credentials on this file!
Please use the .env.local or .env.development.local files as suggested by the official Create React App documentation! And do not forget to add them to your .gitignore!
Heads-up! You need to restart the development server (by stopping and running yarn dev or npm run dev again) if you modify these configurations.

The available properties are:

PORTAL_URL: The url of your local portal.
For example: http://localhost:8080
PORTAL_AVAILABLE_LANGUAGE_IDS: A list of languages defined in your portal separated by a comma.
For example: en_US,it_IT
PORTAL_USER_ID: The ID of your user.
You can get this information here: “Control Panel” › “Users and organizations” › Your user › “Information” › “User ID” field
PORTAL_COMPANY_ID: The ID of your portal / DXP instance.
You can get this information here from the master instance: “Control Panel” › “System” › “Virtual Instances” › Your instance › “Instance ID”.
Otherwise, if you have access to a JavaScript Console on the web front-end of your portal / DXP you can simply run window.themeDisplay.getCompanyId().
PORTAL_THEME_SERVLET_CONTEXT_NAME: The name of your theme. You can find the value in the theme package.json (the property is "name").
For example: classic-theme
PORTAL_USER_LANGUAGE_ID: The language of your user. You can get this information: “Control Panel” › “Users and organizations” › Your user › “Information” › “Personal Informations” › “Language”.
Note: enter the language ID and not the language name.
For example: it_IT
PORTAL_USERNAME: The username/user ID/email that you use when you log into the portal
PORTAL_PASSWORD: The cleartext password that you use when you log into the portal
PORTAL_SCOPE_GROUP_ID: The ID of the site you are targeting for development. You can get this information in: “Site Administration” › “Configuration” › “Site Settings” › “Site Configuration” › “Site ID”.

Now you can start using the module resources inside your application.

Usage

When you install this module, if you have set the PORTAL_THEME_SERVLET_CONTEXT_NAME property, you can already see Liferay Theme style in your application.

Table of content for `window.themeDisplay`

Method of window.themeDisplay	Implemented	Note
getLayoutId()	❌
getLayoutRelativeControlPanelURL()	❌
getLayoutRelativeURL()	❌
getLayoutURL()	❌
getParentLayoutId()	❌
isControlPanel()	❌
isPrivateLayout()	❌
isVirtualLayout()	❌
getBCP47LanguageId()	❌
getCanonicalURL()	❌
getCDNBaseURL()	✅	Depends on PORTAL_URL
getCDNDynamicResourcesHost()	❌
getCDNHost()	❌
getCompanyGroupId()	❌
getCompanyId()	✅	Depends on PORTAL_COMPANY_ID
getDefaultLanguageId()	❌
getDoAsUserIdEncoded()	❌
getLanguageId()	✅	Depends on PORTAL_USER_LANGUAGE_ID
getParentGroupId()	❌
getPathContext()	❌
getPathImage()	✅
getPathJavaScript()	✅
getPathMain()	✅
getPathThemeImages()	✅	Depends on PORTAL_THEME_SERVLET_CONTEXT_NAME
getPathThemeRoot()	✅	Depends on PORTAL_THEME_SERVLET_CONTEXT_NAME
getPlid()	❌
getPortalURL()	✅
getScopeGroupId()	✅ (1.1.0+)	Depends on PORTAL_SCOPE_GROUP_ID
getScopeGroupIdOrLiveGroupId()	✅ (1.1.0+)	Depends on PORTAL_SCOPE_GROUP_ID
getSessionId()	❌
getSiteAdminURL()	❌
getSiteGroupId()	✅ (1.1.0+)	Depends on PORTAL_SCOPE_GROUP_ID
getURLControlPanel()	❌
getURLHome()	❌
getUserEmailAddress()	❌
getUserId()	✅	Depends on PORTAL_USER_ID
getUserName()	✅	Depends on PORTAL_USERNAME
isAddSessionIdToURL()	❌
isImpersonated()	❌
isSignedIn()	❌
isStateExclusive()	❌
isStateMaximized()	❌
isStatePopUp()	❌

Table of content for `window.Liferay`

Available in window.Liferay	Implemented	Note
Language.get(KEY_NAME)	✅	Enter KEY_NAME in Language.properties.
Language.available	✅
authToken	✴️	Requires the user to provide one through a prompt.
all the rest	❌

Note Language.properties file is included in features/localization folder which is automatically created when the application is created. For example, if you want to include a properties file to Italian language, you can create the file Language_it.properties in the same folder.

A note on `Liferay.Language.get`

Do not use dynamic or computed keys in Liferay.Language.get()! The portal substitutes occurences at minification time by statically analyzing your JavaScript code.

  ✅ This is good

+ isFolder
+   ? Liferay.Language.get("delete-folder")
+   : Liferay.Language.get("delete-article");

  🚫 This is bad
  This will work in development and break in production!

- Liferay.Language.get("delete-" + (isFolder ? "folder" : "article"));

Example

To test if your proxy is correctly set up, copy this code in your features/localization/Language.properties:

delete-folder=Cancella cartella

And then somewhere in your application do something like this:

export default function App() {
  return (
    <dl>
      <dt>User ID:</dt>
      <dd>{window.themeDisplay.getUserId()}</dd>

      <dt>User Name:</dt>
      <dd>{window.themeDisplay.getUserName()}</dd>

      <dt>Company ID:</dt>
      <dd>{window.themeDisplay.getCompanyId()}</dd>

      <dt>Language ID:</dt>
      <dd>{window.themeDisplay.getLanguageId()}</dd>

      <dt>Theme Path Root:</dt>
      <dd>{window.themeDisplay.getPathThemeRoot()}</dd>

      <dt>Theme Path Images:</dt>
      <dd>{window.themeDisplay.getPathThemeImages()}</dd>

      <dt>CDN Base URL:</dt>
      <dd>{window.themeDisplay.getCDNBaseURL()}</dd>

      <dt>Translate words with key delete-folder:</dt>
      <dd>{window.Liferay.Language.get("delete-folder")}</dd>
    </dl>
  );
}

License

This library, @smclab/create-react-app-liferay-proxy, is free software ("Licensed Software"); you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; including but not limited to, the implied warranty of MERCHANTABILITY, NONINFRINGEMENT, or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

http-auth-utils http-proxy-middleware language-name-map properties

@everything-registry/sub-chunk-846 @zalastax/nolb-_smc

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago