Creating Clarity's Custom Form Fragment

Liferay fragments are highly customizable web elements with dynamic functionality and styling. Clarity plans to leverage fragments to enhance their Contact Us form with a file uploader field for gathering additional user information. In these exercises, you'll create a file uploader fragment and add it to Clarity's Contact Us form.

Exercise: Creating the Advanced File Uploader Fragment

Here, you'll build a file uploader fragment that displays a loading screen upon file selection.

Open the Site Menu (), expand Design, and click Fragments.
Under Fragment Sets, click Clarity Components.
Click New, select Form Fragment, and click Next.
For Name, enter Advanced File Uploader.
For Supported Field Types, check the File checkbox.
This determines the type of field you can map to the fragment.
Click Add.

This redirects you to the fragment editor menu.
In your course workspace, navigate to the exercises/module-3/file-uploader-fragment-code/ folder and open the fragment.html file in a text editor or IDE.
Copy and paste the contents of this file into the HTML window.

This HTML code contains two main elements: the file uploader component and the loading screen template.
Copy and paste the contents of the fragment-style.css file into the CSS window.
This hides the default HTML input element and styles the file uploader button.
Copy and paste the contents of the fragment-functionality.js file into the JavaScript window.
This implements the custom upload functionality and triggers the loading screen.
Click Publish.

Great! You've created a file uploader fragment. Now you can add it to Clarity's pages.

Exercise: Adding the Fragment to Clarity's Form

Here you'll add the Advanced File Uploader fragment to Clarity's Contact Us form and map it to the object's Shared Files field.

Open the Site Menu (), expand Design, and click Page Templates.
Go to the Display Page Templates tab and select the Contact Us - Step 2 template.
Open the Fragments and Widgets tab in the left side panel.
Drag and drop the Advanced File Uploader fragment below the Comment field.
Select the fragment and configure these settings in the configuration side panel:

Tab Setting Value

General Field Shared Files

Styles Spacing > Padding Bottom Spacer 3 (1rem)
Click Publish.
With the new form field set up, you're ready to test it.
Go to the Contact Us page in Clarity's website.
Test the form by submitting an entry with an attachment.

Tab	Setting	Value
General	Field	Shared Files
Styles	Spacing > Padding Bottom	Spacer 3 (1rem)

Great! Now users can use the custom form fragment to upload files. Next, you'll use FreeMarker to make the fragment more dynamic.

Exercise: Adding Dynamic Functionality to the Fragment

Here, you'll improve the Advanced File Uploader fragment by enabling users to dynamically control its help text visibility and content.

Open the Site Menu (), expand Design, and select Fragments.
Begin editing the Advanced File Uploader form fragment.

In the HTML window, locate this <p> element:

<p class="mb-0 text-secondary text-center" id="${fragmentEntryLinkNamespace}-file-upload-help-text">Accepted File Extensions: .jpeg,.jpg,.pdf,.png</p>

Replace the <p> element with this code:
```
[#if (input.showHelpText && input.helpText?has_content)]
	<p class="mb-0 text-secondary text-center" id="${fragmentEntryLinkNamespace}-file-upload-help-text">${input.helpText}</p>
[/#if]
```
This Freemarker conditional statement dynamically toggles the <p> element's visibility, displaying it only if the fragment's help text is enabled and contains content. Additionally, the inline ${input.helpText} code populates the fragment's content with the value entered in the help text field.
Click Publish.
You can now dynamically control the fragment's help text. Before testing it, you'll propagate these changes to all pages that use the fragment.
Click Actions () for the Advanced File Uploader fragment and select View Usages.
Check all items in the list and click Propagate.

With all pages utilizing the fragment updated, you can now test the new functionality.

NOTE
By default, changes made to a custom fragment need to be manually propagated to all pages that use the fragment. You can configure your instance to propagate fragment changes automatically. However, you should only enable this feature in testing and development environments, since automatic propagation can lead to errors being published. See Propagating Fragment Changes for more information.
Open the Site Menu (), expand Design, and click Page Templates.
Go to the Display Page Templates tab and select the Contact Us - Step 2 template.
Select the Advanced File Uploader fragment and configure these settings:

Tab Setting Value

General Show Help Text Enabled

General Help Text Only upload .jpeg, .jpg, .pdf, and .png files.
Click Publish.

Tab	Setting	Value
General	Show Help Text	Enabled
General	Help Text	`Only upload .jpeg, .jpg, .pdf, and .png files.`

Great! You've used Freemarker to dynamically control the visibility of the fragment's help text. Next, you'll add new configuration options to the fragment for greater flexibility.

Exercise: Adding Fragment Configuration Options

Here, you'll add configuration options to the Advanced File Uploader fragment for modifying the text of the file selection button and loading screen.

Go to the Fragments application in the Site Menu () and start editing the Advanced File Uploader form fragment.
Go to the Configuration tab.
This page contains the fragment's supported field type settings and the custom JSON configuration.
From the exercises/module-3/file-uploader-fragment-code/ folder in your course workspace, copy and paste the contents of the fragment-configuration.json file into the JSON window.

This adds three configuration options for modifying the upload button text, loading screen title, and help text. You can now reference these options in the fragment's code.
Go to the Code tab.

In the HTML window, locate this <button> element:

<button class="btn btn-outline-primary text-nowrap" id="${fragmentEntryLinkNamespace}-file-upload-button" type="button">[@clay.icon className="text-primary" symbol="upload" /] Browse File</button>

Within the <button> element, replace Browse File with ${configuration.buttonText}.
This retrieves the buttonText field's value and displays it as the uploader button's text.

NOTE
When replacing the content, be sure to preserve the @clay.icon element, as it's required for displaying the button's upload icon.

Ensure the element resembles this:

<button class="btn btn-outline-primary text-nowrap" id="${fragmentEntryLinkNamespace}-file-upload-button" type="button">[@clay.icon className="text-primary" symbol="upload" /] ${configuration.buttonText}</button>

Locate this <h4> element:

<h4 class="font-weight-normal mb-0">Upload may take a few seconds</h4>

Replace Upload may take a few seconds with ${configuration.loadingTitle}.
This retrieves the loadingTitle field's value and displays it as the loading screen's title.

Find this <p> element:

<p class="mb-0">Please keep the window open</p>

Replace Please keep the window open with ${configuration.loadingHelpText}.
This displays the loadingHelpText field's value as the loading screen help text.

Both elements should resemble this:

<h4 class="font-weight-normal mb-0">${configuration.loadingTitle}</h4>
<p class="mb-0">${configuration.loadingHelpText}</p>

Click Publish.
Propagate the fragment's changes to all uses.

Now that you've implemented configuration options for the fragment, you can test them.

Exercise: Testing the Fragment's Custom Configuration Options

Here, you'll test your custom configuration options for the Advanced File Uploader fragment.

Open the Site Menu (), expand Design, and click Page templates.
Go to the Display Page Templates tab and select the Contact Us - Step 2 template.
Select the Advanced File Uploader fragment.
Notice there are two new options in the configuration side panel: Upload Options and Loading Options.

Configure these settings for the fragment:

Tab	Setting	Value
General	Button Text	`Select a File`
General	Loading Title	`Uploading File...`
General	Loading Help Text	`This won't take long`

Configure these settings for the fragment.

Click Publish.
Go to the Contact Us page in Clarity's website.
Test the form by submitting an entry with an attachment.

With this, you've implemented new configuration options for customizing the fragment's display text.

Conclusion

Through these exercises, you've successfully created and customized a file uploader fragment, enhancing Clarity's Contact Us form. By adding custom configuration options, you've improved the form's usability while demonstrating the flexibility and power of fragments in tailoring web experiences.

Next, you'll learn about fragment compositions and migrating fragments between Liferay environments.