While HTML, CSS, and JavaScript are universal tools for building websites, Liferay DXP includes some additional tools to make fragments more powerful. One tag can make text editable not just in the HTML editor, but also at the time of publishing. The other enables you to embed Liferay portlets into your fragment in the form of “Widgets.”
Making Text Editable
Making text editable allows the marketer or web admin to modify the text before publishing it. This way, you can reuse a single fragment with different headings or different text for different pages. Fragments make creating content easy and this feature can save you the work of duplicating work just to change the text.
You can make any text of a fragment editable by enclosing it in an
<lfr-editable>
tag like this:
<lfr-editable id="unique-id" type="text">
This is editable text!
</lfr-editable>
The lfr-editable
tag doesn’t render without a unique id
.
The following three type
options are available inside of of lfr-editable
tag:
text
: Creates a space for plain text that can be edited before publishing.
image
: Must contain a valid <img>
tag which can then be replaced with any
image before publishing—including those from Documents and Media.
rich-text
: Provides rich text formatting, such as bold, italics, underline,
links, and predefined styles.
Now add editable text to a Fragment, add the Fragment to a Content Page, and then edit the text before publishing:
-
Go back into the Fragment you were working on before.
-
Inside the
<h1>
in the HTML pane, surround the text with<lfr-editable>
tags so that it looks like this.<h1> <lfr-editable id="heading" type="text"> This text is styled, so it will look pretty! </lfr-editable> </h1>
-
Click Publish.
Now your fragment contains editable text. Add it to a Content Page to be published:
-
Go to Navigation → Site Pages.
-
Select the Page Templates tab at the top.
-
Create a new Collection named Templates for Developing Fragments and a New Page Template inside of it named Editable Page Template.
-
From the menu on the right, add your fragment to the page.
-
Click on the text that you defined as editable and change it.
Figure 1: You can edit text in the Page Template editor.
Similarly, the rich-text
type provides the same functionality with additional
features in the editor.
The template saves automatically, and when it is turned into a page, the new text is displayed.
Making Images Editable
Like text, you can set images images as editable. An editable image can be selected from the user’s local files or from the Documents and Media Library. You must be careful with defining styles for editable images since an image that without the proper dimensions or that is forced into a poorly sized space can have major negative effects on your layout.
Images use the same <lfr-editable>
tag as text, but with the image
type, like
this:
<lfr-editable id="unique-id" type="image">
<img src="...">
</lfr-editable>
After you add the lfr-editable
tag with the type image
to a Fragment, when
you add that Fragment to a page, you can then click on the editable image and
select a replacement.
Including Widgets Within A Fragment
You can add more dynamic behavior to a Fragment by including a widget. Currently, you can only embed a portlet as a widget, but other types of widgets will be available in the future.
To include a widget you need to know its registered name. For example, the Site
Navigation Menu portlet is registered as nav
. Each portlet which is registered
has an lfr-widget-[name]
tag that’s used to embed it. For example: the Navigation
Menu tag is <lfr-widget-nav />
. You could embed it in a block like this:
<div class="nav-widget">
<lfr-widget-nav>
</lfr-widget-nav>
</div>
Implement this in your Fragment:
-
Go to the Fragments page.
-
Go to the Developing Fragments collection and add a new Fragment inside of it named Widget Fragment.
-
Insert the following code in the main
<div>
in the HTML pane:<div class="container-fluid"> <div class="row"> <div class="col-md-10"> <lfr-widget-nav> </lfr-widget-nav> </div> </div> </div>
-
Click Publish.
Now you need to add it to a Content Page to display it.
-
Go to Navigation → Site Pages.
-
Select the Page Templates tab at the top.
-
Go to the Templates for Developing Fragments Collection.
-
Create a new Page Template named Widget Page Template.
-
In the new Page Template, from the menu on the right, add your fragment to the page.
-
Exit the template editor and it saves automatically.
-
Go to the Pages tab.
-
Click the
+
icon to create a new page. -
Select the Widget Page Template and save.
-
Now go back to your site, and select your new page.
For the full list of widgets that can be imbedded, see the Embedding Widgets in Page Fragments reference article.
Embedding Your Widget in a Fragment
If you have a custom widget that you want to embed in a fragment, you can
configure that widget to be embeddable. In order to embed your widget, it must
be an OSGi Component. Inside the @Component
annotation for the portlet class
that you want to embed, add this property:
"com.liferay.fragment.entry.processor.portlet.alias=app-name"
When you deploy your widget, it’s available to add. The name you specify in the
property must be appended to the lfr-widget
tag like this:
<lfr-widget-app-name>
</lfr-widget-app-name>
Embedding widgets in Fragments opens a world of options. Now that you’ve explored some of the power of Fragments, next you’ll learn about best practices for development.