Using liferay-learn:message Tags

You can link to resources, such as Liferay Learn articles, using the liferay-learn:message tag. For example, the Click to Chat app links to the Chatwoot Liferay Learn article.

Users can click on liferay-learn:message tag generated links, like the one above, to get help.

The links have two parts:

1. A JSON file that specifies the resource you're linking to.

2. A liferay-learn:message tag that references the JSON file and one of its resources.

Specifying resources in a JSON file separate from the JSP facilitates adding locale translations and updating link labels and URLs.

Note: If a liferay-learn:message tag references a missing JSON file or unspecified resource entry, there's no ugly error--the tag simply doesn't render anything.

Start with specifying a resource.

Adding Resources in a JSON File

Here are the steps:

1. In this folder (i.e., learn-resources), create a JSON file named after the module you're embedding links in.

2. Create an element for each resource you're linking to. For example, the learn-resources/marketplace-store-web.json file has these resource entries:

   {
   	"download-app": { // Resource key
   		"en_US": {
   			"message": "How can I download an app?", // Link label
   			"url": "https://learn.liferay.com/dxp/latest/en/system-administration/installing-and-managing-apps/installing-apps/downloading-apps.html" // Resource URL
   		}
   	},
   	"purchase-app": {
   		"en_US": {
   			"message": "How can I purchase an app?",
   			"url": "https://learn.liferay.com/dxp/latest/en/system-administration/installing-and-managing-apps/getting-started/using-marketplace.html"
   		}
   	}
   }

The example resource entries have the keys download-app and purchase-app. The keys are unique within the JSON file. You can provide each resource in multiple locales. For example, the resources above are in the en_US locale. For each locale, assign the url to the resource location and the message to a label for the resource link.

Adding liferay-learn:message Tags to a JSP

In your module's JSP, link to the resources using liferay-learn:message tags. For example, the marketplace-store-web module's view.jsp file can reference the learn-resources/marketplace-store-web.json file's download-app resource with this code:

<%@ taglib uri="http://liferay.com/tld/learn" prefix="liferay-learn" %>

<liferay-learn:message
    key="download-app"
    resource="marketplace-store-web"
/>

The first line above includes the liferay-learn tag library. The liferay-learn:message tag links to the download-app resource in the learn-resources/marketplace-store-web.json file. When the JSP renders, the text How can I download an app? links to the resource located at https://learn.liferay.com/dxp/latest/en/system-administration/installing-and-managing-apps/installing-apps/downloading-apps.html.

That's how you link to Liferay Learn resources!

A CDN server hosts the JSON files. For example, here's how the <liferay-learn:message key="download-app" resource="marketplace-store-web" /> tag works:

1. The tag checks for the resource file (JSON file with prefix marketplace-store-web) on the local CDN server at https://learn-resources.liferay.com/marketplace-store-web.json.
2. The local server checks the global server at http://s3.amazonaws.com/learn-resources.liferay.com/marketplace-store-web.json for updates to the resource.
3. If the local resource is valid, it's served immediately. Otherwise, the local server serves the resource after refreshing the local resource cache with the latest update from the global server.

Note: The cache refreshes every four hours by default, per the learn.resources.refresh.time portal property.

Adding a Resource Link to a React Component

For example, to use the search-experiences-web.json file's advanced-configuration resource key:

1. In the JSP, use the LearnMessageUtil.getReactDataJSONObject Java method to retrieve the resource data to pass into the React component.

   <%@ page import="com.liferay.learn.LearnMessageUtil" %>
   
   <react:component
   	module='path/to/component'
   	props='<%=
   		HashMapBuilder.<String, Object>put(
   			"learnResources", LearnMessageUtil.getReactDataJSONObject("search-experiences-web")
   		).build()
   	%>'
   />

   To retrieve multiple resources, a string array can be passed into getReactDataJSONObject. For example: LearnMessageUtil.getReactDataJSONObject(new String[] {"portal-search-web", "search-experiences-web"})

2. In the React component, use LearnResourcesContext to provide the resource and the LearnMessage component to display the link.

   import {LearnMessage, LearnResourcesContext} from 'frontend-js-components-web';
   
   <LearnResourcesContext.Provider value={learnResources}>
   	<LearnMessage
   		resource='search-experiences-web'
   		resourceKey='advanced-configuration'
   	/>
   </LearnResourcesContext.Provider>

   The LearnMessage component renders a ClayLink and additional props will be passed into it.

Guidelines

Here are some guidelines for writing the JSON files and tags.

Name the JSON Files After the Web Modules That Will Use the Resources

For example, if want the foo-web module's JSPs to link to resources, create the resources in a JSON file called liferay-resources/foo-web.json.

Make Resource Keys Unique Per JSON File

Don't duplicate resource keys in the same JSON file.

Name Lone Resource Keys general

If a JSON file has only one resource key, name the key general.