Using a Site Initializer Client Extension

Liferay 7.4 2023.Q4+/GA100+

Site Initializer client extensions can quickly create a site, complete with configurations and content. Start with the sample workspace to build and deploy your client extension.

Prerequisites

Install a supported version of Java.
Download and unzip the sample workspace:

curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip

unzip com.liferay.sample.workspace-latest.zip

All the necessary tools and a Site Initializer client extension are included in the sample workspace.

Examine the Site Initializer

The Site Initializer client extension is in the sample workspace’s client-extensions/liferay-sample-site-initializer/ folder. It’s defined in the client-extension.yaml file:

liferay-sample-site-initializer:
    name: Liferay Sample Site Initializer
    oAuthApplicationHeadlessServer: liferay-sample-site-initializer-oauth-application-headless-server
    siteExternalReferenceCode: liferaySample
    siteName: Liferay Sample
    type: siteInitializer

This YAML has the ID Liferay-sample-site-initializer and contains the key configurations for a Site Initializer client extension, including the type and the new site’s name (Liferay Sample).

It also contains an OAuth headless server client extension definition, which is necessary to authenticate when you deploy the client extension:

liferay-sample-site-initializer-oauth-application-headless-server:
    .serviceAddress: localhost:8080
    .serviceScheme: http
    name: Liferay Sample OAuth Application Headless Server
    scopes:
        - Liferay.Headless.Site.everything
    type: oAuthApplicationHeadlessServer

The sample client extension also has a site-initializer/ folder containing pre-defined content. The documents/group/ folder contains a single document, and journal-articles/ has a web content article. See Adding Content to a Site Initializer for more information.

Add a New Vocabulary to the Site

To add more content to a Site Initializer, you must add the correct files in a specific location that depends on the asset type.

Add a new vocabulary with a category for the Liferay Sample site.

In your site-initializer/ folder, add a new taxonomy-vocabularies/ folder.
Navigate into the new taxonomy-vocabularies/ folder and add a group/ subfolder in it.

Adding the vocabulary inside a group/ folder ensures the vocabulary is scoped to the new site.
Navigate into the new group/ folder and create a new JSON file named fruits.json.
```
touch fruits.json
```
Open fruits.json and save this JSON into it for a new Fruits vocabulary:
```
{
    "description": "This is a vocabulary for things related to fruits.",
    "externalReferenceCode": "FruitVocabulary",
    "name": "Fruits",
    "numberOfTaxonomyCategories": 1
}
```
Tip

You can get JSON for a new vocabulary like this by creating one on an existing site and exporting it via REST API (at https://[your domain]/o/api), using the headless-admin-taxonomy REST application. Find the vocabulary’s full JSON details by retrieving it (with either the vocabulary ID or the site ID you created it on), then remove the unnecessary information. See here for more information.
Alongside the fruits.json file, create a new folder called fruits/.

Giving the folder the same name as a vocabulary’s JSON file signals that the folder contains that vocabulary’s categories. You can do the same thing by creating folders next to category JSON files to add subcategories.
In the fruits/ folder, add a new file called apple.json.

Open apple.json and save this JSON into it for an Apple category:

{
    "description": "This category is for things related to apples.",
    "externalReferenceCode": "AppleCategory",
    "name": "Apple",
    "numberOfTaxonomyCategories": 0,
    "taxonomyCategoryProperties": []
}

Now you have added enough information to include a new vocabulary, complete with one contained category, with your new site.

Deploy the Site to Liferay

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.112-ga112

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Next, run this command from the client extension project’s folder in the sample workspace:

../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)

This builds your client extension and deploys the zip to Liferay’s deploy/ folder.

Note

To deploy your client extension to Liferay SaaS, use the Liferay Cloud Command-Line Tool to run lcp deploy.

Tip

To deploy all client extensions in the workspace simultaneously, run the command from the client-extensions/ folder.

Confirm the deployment in your Liferay instance’s console:

STARTED liferaysamplesiteinitializer_7.4.13

Find the Site and Vocabulary

Log into your Liferay instance as an administrator.
Click the Applications menu () → Control Panel → Sites.

On the Sites page, the Sample site from the client extension is present on the list.
For the Sample site, click Actions () → Go to Site Settings.
In the site menu on the left, click Categorization → Categories.

On the Categories page, you can see the Fruits vocabulary is added to the site. With the Fruits vocabulary selected, you can also see the contained Apple category.

The Apple category is already present in the Liferay Sample site.