Creating a Contributed Fragment Set
Contributed Fragment Sets are deployable modules containing Page Fragments. Fragments in a contributed Set can be used just like regular Fragments, but aren’t contained in the database and can’t be modified directly through the UI. If you’re running Liferay 7.3+, it’s better to use Automatically deployed Fragments created in compressed ZIP Sets. You can create these with your own tools or the Liferay Fragments Toolkit, and they can be modified from the UI and can include image resources.
This example runs on Liferay 7.3+.
All Fragments added through a Contributed Fragment Set are available globally to all Sites.
To add a contributed Fragment Set, you extend the BaseFragmentCollectionContributor
Class, which itself implements the FragmentCollectionContributor
interface.
Here, you’ll learn how to contribute a Fragment Set:
- Deploy a Contributed Fragment Set
- Contributed Fragment Set Logic and metadata
- Add Fragment Resources
- Related Information
For Liferay DXP 7.4+, Fragment Collections are called Fragment Sets in the Liferay UI.
Deploy a Contributed Fragment Set
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.
Then, follow these steps to deploy an example to see what a contributed Fragment Set looks like:
-
Download and unzip the example:
curl https://resources.learn.liferay.com/dxp/latest/en/site-building/developer-guide/developing-page-fragments/liferay-l3m9.zip -O
unzip liferay-l3m9.zip
-
From the module root, build and deploy the contributed Set’s JAR.
cd liferay-l3m9
./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
noteIf testing on Windows, you may need to build the module first with
./gradlew build
and then manually copy the JAR todocker cp docker-container-name:/opt/liferay/osgi/modules
directly if deployment fails. -
Confirm the deployment to the Liferay Docker container console. The log message below should appear in the Docker console:
INFO [fileinstall-directory-watcher][BundleStartStopLogger:46] STARTED com.acme.l3m9.impl_1.0.0 [1824]
-
Verify the contributed Fragment Set is available. Open the Site Menu (
) and go to Design → Fragments. The Set should appear in the Default Sets list.
Great! You successfully deployed a contributed Fragment Set.
As you can see, the contributed Fragment Set appears with the default Fragment Sets, and the Fragments can’t be modified from the UI. The only way to modify the Set is to update the module they came from or copy the Fragment to another Set and modify the Fragment copy.
Contributed Fragment Set Logic and metadata
The Fragment Set contributor overrides two methods in the *FragmentCollectionContributor
Class to provide information about the Set.
The getFragmentCollectionKey()
method returns the key/name of the Fragment Set where these fragments are contributed:
@Override
public String getFragmentCollectionKey() {
return "l3m9";
}
The getServletContext()
method returns the servlet context for the contributed Fragment Set module:
@Override
public ServletContext getServletContext() {
return _servletContext;
}
The ServletContext
points to the bundle’s symbolic name so it can find the Fragment resources:
@Reference(
target = "(osgi.web.symbolicname=com.liferay.learn.fragments)"
)
private ServletContext _servletContext;
The bnd.bnd
file includes a few properties that must be defined for the Set:
- The
osgi.web.symbolicname
matches theBundle-SymbolicName
in thebnd.bnd
file. - The
Web-ContextPath
Header indicates the module folder that contains the Set, so theServletContext
is correctly generated. - The
-dsannotations-options
enables the Declarative Service annotations found in the class hierarchy of the Component class.
See the example project’s bnd.bnd
for a reference of these values.
Now you’ll modify the project to include another Fragment in the contributed Set.
Add Fragment Resources
Follow these steps to add a new packaged Fragment to the contributed Fragment Set:
-
Move the example’s
l3m9-impl/l3m9-jumbotron
folder into thel3m9-impl/src/main/resources/com/acme/l3m9/internal/fragment/contributor/l3m9/dependencies
folder.cp -r l3m9-impl/l3m9-jumbotron l3m9-impl/src/main/resources/com/acme/l3m9/internal/fragment/contributor/l3m9/dependencies/
See Developing Page Fragments with the Fragments Toolkit for more information on creating Fragments.
notePackaged Fragments go in the
dependencies
folder, and the class package name and resources package name must match (e.g.[class.package.path].dependencies
).noteContributed Fragment Sets do not support included resources.
-
Build the updated contributed Set’s JAR.
cd liferay-l3m9
./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
noteIf deployment fails on Windows, you may need to bind mount Liferay in the container, build the module JAR with
.\gradlew jar
, and copy the JAR to the appropriate bind-mounted folder. -
Verify that the updated Fragment is included in the contributed Set. Point your browser to
https://localhost:8080
, and under the Site Menu on the left side of the screen, go to Design → Fragments. The L3M9 Jumbotron Fragment appears in the L3M9 Set.
Congratulations! You now know how to create a contributed Fragment Set, and have added a new contributed Fragment Set to Liferay.