Creating a Contributed Fragment Collection¶
Contributed Fragment Collections are deployable modules containing Page Fragments. Fragments in a contributed Collection 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 Collections. 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+.
Note
All Fragments added through a Contributed Fragment Collection are available globally to all Sites.
To add a contributed Fragment Collection, you extend the BaseFragmentCollectionContributor Class, which itself implements the FragmentCollectionContributor interface.
Here, you’ll learn how to contribute a Fragment Collection:
Deploy a Contributed Fragment Collection¶
First, deploy an example to see what a contributed Fragment Collection looks like:
Run the command below to start the Docker container:
docker run -it -p 8080:8080 liferay/dxp:7.3.10-ga1Download and unzip the example:
curl https://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 Collection’s JAR.
cd liferay-l3m9./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
Note
If testing on Windows, you may need to build the module first with ./gradlew build and then manually copy the JAR to docker 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 that the contributed Collection and Fragment are available. Point your browser to
https://localhost:8080, and under the Site Menu on the left side of the screen, go to Design → Fragments. The Collection appears in the list of Default Collections.
Great! You successfully deployed a contributed Fragment Collection.
As you can see, the contributed Fragment Collection appears with the default Fragment Collections, and the Fragments can’t be modified from the UI. The only way to modify the Collection is to update the module they came from or copy the Fragment to another Collection and modify the Fragment copy.
Contributed Fragment Collection Logic and metadata¶
The Fragment Collection contributor overrides two methods in the *FragmentCollectionContributor Class to provide information about the Collection.
The getFragmentCollectionKey() method returns the key/name of the Fragment Collection where these fragments are contributed:
@Override
public String getFragmentCollectionKey() {
return "l3m9";
}
The getServletContext() method returns the servlet context for the contributed Fragment Collection 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 Collection:
The
osgi.web.symbolicnamematches theBundle-SymbolicNamein thebnd.bndfile.The
Web-ContextPathHeader indicates the module folder that contains the Collection, so theServletContextis correctly generated.The
-dsannotations-optionsenables 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 Collection.
Add Fragment Resources¶
Follow these steps to add a new packaged Fragment to the contributed Fragment Collection:
Move the example’s
l3m9-impl/l3m9-jumbotronfolder into thel3m9-impl/src/main/resources/com/acme/l3m9/internal/fragment/contributor/l3m9/dependenciesfolder.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.
Note
Packaged Fragments go in the dependencies folder, and the class package name and resources package name must match (e.g. ``[class.package.path].dependencies`).
Note
Contributed Fragment Collections do not support included resources.
Deploy and Test¶
You can build and deploy the updated contributed Fragment Collection as you did above:
Build the updated contributed Collection’s JAR.
cd liferay-l3m9./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
Note
If 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 Collection. 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 Collection.
Congratulations! You now know how to create a contributed Fragment Collection, and have added a new contributed Fragment Collection to Liferay.