Creating Custom Fragments for Clarity

Liferay offers a wide range of out-of-the-box fragments and configurations to help streamline website development. However, when these options don't satisfy your design requirements, you can quickly create or import custom fragments using HTML, CSS, and JavaScript. In addition to these core web development languages, you can leverage Clay utilities, define configuration options using JSON, and add Liferay-specific tags and attributes. These elements empower you to define editable sections, embed widgets, reuse available classes, and more.

Liferay DXP includes the fragments editor UI for creating and managing fragments in your site. Additionally, you can export fragment sets and work on them locally, using your preferred tools. Then, once your local work is complete, you can import the set back into Liferay. Additionally, you can instantiate React components within your page fragments using static JavaScript imports, expanding the range of functionalities you can integrate into your custom fragments.

When creating a fragment, you can copy and modify existing fragments or start from scratch. You can also create custom fragments by saving container compositions in the page editor. Saving container compositions offers a convenient way to recreate specific arrangements of fragments on other pages. However, you cannot edit compositions via the Fragments Editor UI.

In these exercises, you'll create and import custom fragments for Clarity's site.

Exercise: Creating Custom Fragments

Page fragments are reusable drag-and-drop elements for designing page layouts, displaying content, building forms, and more. While Liferay provides a variety of fragments out-of-the-box, you can build custom components to provide specific structures and targeted functionality.

The course workspace includes a set of custom fragments called Clarity components. This set includes most of what Clarity needs, but they still need a custom Search Button fragment. Here, you'll create it using the Fragments Editor UI as Walter Douglas.

1. Sign in using these credentials:

   • Email: walter.douglas@clarityvisionsolutions.com
   • Password: learn

2. Open the Site Menu (), expand Design, and click Fragments.

3. Under Fragment Sets, click Clarity Components.

4. Click New, select Basic Fragment, and click Next.
   

5. For name, enter Search Button and click Add.

6. Go to the Configuration tab.

   NOTE
   Use the Configuration tab's JSON editor to define customizable fragment options, leveraging conditional visibility to display specific inputs only when they are relevant. Available types include text, checkbox, colorPicker, and more. 

7. In your course workspace, open the exercises/module-5/search-button-configuration.json file and copy its contents.

8. Navigate back to the Search Button fragment and replace the placeholder text in the editor with the copied .json content.

   

   This defines four configuration options for the fragment: iconName, iconSize, hideLabel, and buttonLabel. You can reference these options in the fragment's code.

9. In your course workspace, open the exercises/module-5/search-button.ftl file and copy its contents.

10. Navigate back to the Search Button fragment, go to the Code tab, and replace the placeholder HTML code with the copied .ftl content.

    

    Notice this includes references to the configuration options you defined in the previous step, such as the configuration.iconSize and configuration.iconName. This enables site builders to configure the icon's appearance and label visibility when adding the fragment to a page.

    NOTE
    This fragment uses dynamic field visibility to contextually show or hide the label option. The Hide Label checkbox is enabled by default to show only the search icon. Unchecking it reveals a new field to customize the button's text next to the icon.

11. Click Publish.

Great! You’ve created a custom fragment with included configuration options, which can now be added to pages. Next, you’ll import additional fragments that you'll use in later exercises.

Exercise: Importing Fragments

When building pages with fragments, you can save any container and its contents as a composition for reuse. Clarity's team has provided pre-built fragment compositions to wireframe the Home page, FAQ page, and Leadership Profile display page. 

Here, you’ll import these fragments as Walter Douglas so they can be used across the site.

1. While in the Fragments application, click Clarity Page Compositions under Fragment Sets.

2. Click Actions () for the fragment set and select Import.

   

3. Click Select File, navigate to the course workspace's exercises/module-5/ folder, and select the page-composition-faq.zip file.

4. Click Import.

5. Click Done when finished.
   This adds the FAQ Page composition to the currently selected fragment set.

6. Repeat the above steps to import these compositions to the correct fragment set folders:

   Fragment Set Folder	File
   Clarity Page Compositions	page-composition-home.zip
   Clarity Display Compositions	display-composition-leadership-profile.zip

   
   

Great! You've imported Clarity's custom fragment compositions.

Exercise: Adding Custom Fragments to Master Pages

After creating fragments, you can add them to master pages. Clarity wants to add the Search Button fragment to their primary and secondary master pages.

Here, you’ll adjust these templates as Walter Douglas.

1. Open the Page Templates application and begin editing Primary Master Page.

2. Add the Search Button fragment to the Header User Actions container.

   

3. Select the Search Button fragment and configure these settings in the right side panel’s General tab:

   Field	Value
   Link	Page
   Page	Search

   Now, users are directed to Clarity's Search page when they click this button.

4. Click Publish Master and confirm with Ok.

5. Repeat these steps to update Secondary Master Page.

Great! You’ve added the custom search button fragment to both page templates.

Exercise: Adding Fragment Compositions to Pages

Fragment compositions are reusable arrangements of page elements saved within a fragment container. You can use them to quickly duplicate layouts between site pages to accelerate development and achieve consistent designs.

Here, you'll add fragment compositions to their corresponding pages as Walter Douglas.

1. Go to and begin editing the Leadership Profile display page template.

2. Drag and drop the Leadership Profile Display fragment composition into the central content area.

   

3. Click Publish.

4. Open the Site Menu (), expand Site Builder, and click Pages.

5. Repeat steps 1-3 to add the Home Page composition to Home and FAQ Page composition to FAQ. For the Home page, remove its default content before adding the fragment composition.
   

Well done! You’ve quickly populated Clarity's pages using fragment compositions.

Conclusion

Custom fragments and compositions provide powerful tools to complement Liferay’s native design capabilities and quickly create complex page layouts. Next, you'll apply Clarity's styling to finalize the site's design before moving on to managing and displaying content on these pages.

Additional Resources

See official documentation to learn more about creating and managing Liferay fragments:

• Using Fragments
• Page Fragment Editor Interface Reference

• Fragment Configuration Types Reference