To create a Contributed Fragment Collection, a developer must,
-
Create a module which will contain the necessary logic and the fragments.
-
Extend the class
BaseFragmentCollectionContributor
with all the logic for reading the contributed fragments. -
Add fragments as resources in the module.
Once you deploy the module, any fragments contained in it will be available for use.
To better understand Contributed Fragment Collections, create one called
DemoFragmentCollectionContributor
.
Create a Module
First you must create the module in your development environment. Follow the instructions in Creating a Project.
Create the Java Class
Next, you must create the Java package and class to handle the logic for the contributed collection:
-
Create a package in your module named
com.liferay.fragment.collection.contributor.demo
-
Inside of that package, create a Java class named
DemoFragmentCollectionContributor
that extendsBaseFragmentCollectionContributor
. -
Above the class declaration, add the
@Component
annotation to set the service class:@Component(service = FragmentCollectionContributor.class)
-
Create the variable for the servlet context:
private ServletContext _servletContext;
-
Define the
getFragmentCollectionKey()
andgetServletContext()
methods:@Override public String getFragmentCollectionKey() { return "DEMO"; } @Override public ServletContext getServletContext() { return _servletContext; }
-
Below that use the
@Reference
annotation to define your module’s symbolic name:@Reference( target = "(osgi.web.symbolicname=com.liferay.fragment.collection.contributor.demo)" )
-
Organize your imports and save.
Create the Resources
Next you need to include the fragments that you want to contribute in your module:
-
In your module’s
resources/
folder, create the folder structure/com/liferay/fragment/collection/contributor/demo/dependencies
. -
Copy the Fragments you want to distribute into the folder. You can learn how to create a Fragment in the Creating Fragments section.
-
Create a file named
collection.json
in the same folder with this format:{ "fragments": [ "[fragment-1]", "[fragment-2]", "[fragment-3]", ... ], "name": "[collection-name]" }
If a fragment is not listed in
collection.json
, it will not be available in the Contributed Collection, even if the files are included in the module.
Next, you’ll configure the module’s metadata so the fragments are imported.
Configuring the Metadata
Follow these steps:
-
Open your bundle’s
bnd.bnd
file and add theWeb-ContextPath
header to point to your bundle’s folder so the fragment resources are loaded properly:Web-ContextPath: /my-fragment-collection-contributor
-
Add the
-dsannotations-options
instruction and set it to use theinherit
option. This specifies to use DS annotations found in the class hierarchy of the component class:-dsannotations-options: inherit
Next, you’ll dive into providing thumbnail images and language keys/translations.
Providing Thumbnail Images
You can also provide thumbnail images for reference for your fragments:
-
Under
resources/META-INF/resources
create a folder namedthumbnails
. -
Copy thumbnail images into the folder with the format
[fragment-name].png
for each fragment.
Providing Language Keys
Providing language keys in your Fragment gives you the option for translating the text you display. Here’s how to do it:
-
You must define your language keys in the Fragment’s collection folder. Create the
[COLLECTION]/src/main/resources/content/Language.properties
file. -
Add your language keys. For example,
applied-style=Applied Style this-is-the-style-that-will-be-applied=This is the style that will be applied. dark=Dark light=Light
You can learn more about providing translations in the Localizing Your Application article.
Deploy the Contributed Fragment Collection
Now that you have created the necessary pieces of the module, you can build it and deploy it to Liferay DXP. After it’s deployed, the Fragments will be available for use. This can also be done by using the Fragments Toolkit. Contributed Fragments cannot be edited with Liferay, and can only be updated by editing the fragments in your module and the building and redeploying them.