Creating a Contributed Fragment Set

Contributed fragment sets are deployable modules containing page fragments. Fragments in a contributed set can be used 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 sets using your own tools or the Liferay Fragments Toolkit. They can also be modified through the UI and include image resources.

This example runs on Liferay 7.3+.

Note

All fragments added through a contributed fragment set are available globally to all sites.

To add a contributed fragment set, extend the BaseFragmentCollectionContributor Class, which itself implements the FragmentCollectionContributor interface.

Note

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.132-ga132

Sign in to Liferay at http://localhost:8080. Use the email address [e-mail] 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:

1. Download and unzip the example:

   curl https://resources.learn.liferay.com/examples/liferay-l3m9.zip -O
   

   unzip liferay-l3m9.zip
   

2. From the module root, build and deploy the contributed Set’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.

3. 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]
   

4. 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";
}

Note

Collection keys must not contain dashes (-). Use underscores (_) instead to avoid issues when copying fragments between sets.

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 the Bundle-SymbolicName in the bnd.bnd file.
• The Web-ContextPath header indicates the module folder that contains the set, so the ServletContext 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, modify the project to include another fragment in the contributed set.

Add Fragment Resources

1. Move the example’s l3m9-impl/l3m9-jumbotron folder into the l3m9-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/
   

   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 sets do not support included resources.

2. Build the updated contributed Set’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.

3. 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.

Related Information

• Using the Fragments Toolkit
• Using the Fragments Editor