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 newtaxonomy-vocabularies/
folder. -
Navigate into the new
taxonomy-vocabularies/
folder and add agroup/
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 namedfruits.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 }
TipYou 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 theheadless-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 calledfruits/
.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 calledapple.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.
To deploy your client extension to Liferay SaaS, use the Liferay Cloud Command-Line Tool to run lcp deploy
.
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.
Next Steps
You have successfully used a Site Initializer client extension to create a new site. Next, try deploying other client extension types.
Related Topics
Exporting/Importing Data Working with Client Extensions Site Initializer YAML Configuration Reference