Documentation

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

Note

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:

Note

For Liferay DXP 7.4+, Fragment Collections are called Fragment Sets in the Liferay UI.

Deploy a Contributed Fragment Set

First, deploy an example to see what a contributed Fragment Set looks like:

  1. Run the command below to start the Docker container:

    docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.22-ga22
    
  2. Download 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
    
  3. 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.

  4. 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]
    
  5. Verify the contributed Fragment Set is available. Open the Site Menu (Site Menu) and go to DesignFragments. The Set should appear in the Default Sets list.

    Verify the contributed Fragment Set appears 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 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 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:

  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/
    

    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 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 DesignFragments. The L3M9 Jumbotron Fragment appears in the L3M9 Set.

    The custom Jumbotron Fragment is included in the contributed Set.

Congratulations! You now know how to create a contributed Fragment Set, and have added a new contributed Fragment Set to Liferay.