Building a Site with Liferay's WCM

You've just been assigned the task to build a web site for a an innovative new social networking site called Nose-ster. You've decided to take advantage of Liferay Portal and its rapid deployment features as well as its ability to get a fully functional, content-rich web site with integrated social features up and running in little time.

We'll walk through the creation of Nose-ster's web site, starting by creating and publishing some simple content using Liferay's built-in WYSIWYG editor. We'll then take advantage of Liferay's robust structure editor. We'll use templates to display the content and then explore some of the advanced publishing features such as the built-in workflow and Asset Publisher.

Creating content the simple way

As we've stated above, content is the reason web sites exist. Liferay Portal has made it easier than ever to get content published to your site. Because Liferay Portal is so flexible, you can use basic authoring tools right away or take advantage of the more advanced features. It's adaptable to your needs.

We'll begin by creating simple content using Liferay's WYSIWYG Editor and then we'll publish it to the home page of Nose-ster's web site. This a fast and straightforward process that demonstrates how easy it is to create and publish content onto your Liferay Portal. So let's get familiar with the Web Content section of the control panel so we can create and publish our first pieces of content.

Figure 3.1: Choosing a Site in the Content Section

When you manage web content from the control panel, you can select the location where the content resides. For instance, you can add content that's available to a specific site or globally across the portal. The Content section of the control panel displays as its heading the name of the site you're currently working on. This heading is clickable: you can change where you're working by using the drop down attached to the heading. We will add our first piece of content to the Nose-ster site, which we defined earlier in the chapter as the default site.

Rich, WYSIWYG Editing

Once you have the Nose-ster site selected, click on the Web Content link in the control panel. Next, click the Add button under the Web Content tab. This is a highly customizable form that by default has two fields: a title and a powerful WYSIWYG editor. We could customize this form to contain whatever fields our content needs, but let's keep things simple for now. We'll cover more advanced features such as structures, templates, and content scheduling later in this chapter.

For now, type the words Welcome to Nose-ster in the Name field. Notice that content can be localized in whatever language you want. If you click the localize check box, two select boxes appear which allow you to pick the language you're working in and the language that is the default. You can enter translations of your content for any language in the list. The screenshot below shows this interface but for now, we won't be using it, so you can leave it unchecked. In the content field, add a short sentence announcing that the web site is up and running.

Figure 3.2: The Web Content Editor

Getting a new web site up and running is an exciting step for anyone, whether it is a large corporation or a small non-profit charity. To celebrate this momentous achievement at Nose-ster, let's give our announcement some of the pomp and circumstance we think it deserves!

Using the editor, select all the text and then change the style to Heading 1 and the color to dark blue.

You could insert an image here as well as more text with a different style, as demonstrated in the screenshot below. You can also add bullets, numbering, links to another site, or custom images. You can even add an emoticon. Let's add a smiley face at the end of our announcement.

Figure 3.3: Customizing Content

The WYSIWYG editor is a flexible tool that gives you the ability to add text, images, tables, links, and more. Additionally, you can modify the display to match the purpose of the content. Plus it's integrated with the rest of Liferay Portal: for example, when you upload an image to be added to a page, that image can be viewed and manipulated in the Documents and Media portlet.

If you're HTML savvy, Liferay WCM doesn't leave you out in the cold. You can click the Source button and write your own HTML if you wish.

Assigning Permissions

Permissions in Liferay WCM work the same way they do everywhere else in Liferay. By default, content is viewable by Anyone (Guest Role). You can limit viewable permissions by selecting any Role from the drop-down or in the list. Additionally, Liferay Portal provides the ability to customize permissions in more detail. Select the More Options link next to the drop down button, and you'll find the different activities you can grant or deny to your web content.

Figure 3.4: Permissions for Web Content

For this piece of web content, we don't need to change anything. After you're finished with permissions, click Save. This saves the content in draft form. Once you're satisfied with the your changes, select Publish. This makes the content available for display, but we still have some work to do to enable users to see it. In Liferay WCM, all content resides in a container, which is one of two portlets: Web Content Display or Web Content List. By far the most frequently used is the Web Content Display portlet.

Localization

Previous versions of Liferay had the ability to create and manage different translations of your web content, but with Liferay 6.1 we've added several improvements.

When you create a new piece of Web Content, you have the ability to choose a default language. If you click Change you can select your default language from a large number of languages that Liferay supports. Before you can create a translation, you must finish creating the content in your default language and save it. Once you've done that, editing the content provides you with the option to Add Translation.

Figure 3.5: Adding a translation

After you click Add Translation, you can select a language, either by scrolling through the list or by entering the language you want to use in the search box. When you select a language, a lightbox opens within your browser window, enabling you to easily compare the original with the new translation. Once you are done with the translation, click Save, and the translation is added to the list of Available Translations.

Figure 3.6: Adding a translation

The ability to completely delete a translation in one step has also been added. Instead of simply disabling a translation or having to go through a multistep process to remove it, you can now simply open the translation that you don't want and click Remove Translation.

When you create a new web content structure, each field you create has a Localizable checkbox displayed next to it. This enables you to control what can and can't be changed in the translation process. For example, if you don't want images or content titles to be changed when the content is translated, you can make sure that those fields aren't listed as localizable. When you follow the steps above to localize content, only fields within the structure that had the Localizable box checked appear within the translation window.

Let's go back to the page where we want the content displayed and add the Web Content Display portlet (in this case, the Welcome page).

Publishing Content with the Web Content Display Portlet

Now that we've created and published our first piece of web content for Nose-ster, it's time to display it. First, add the Web Content Display portlet to our Welcome page, by selecting Add → Web Content Display from the Dockbar.

Figure 3.7: Adding the Web Content Display Portlet

Once the portlet appears, drag it to the position on the page where you want your content to appear. You can have as many Web Content Display portlets on a page as you need, which gives you the power to lay out your content exactly the way you want it.

To add existing web content, select the gear icon on the lower left of the portlet. You will see the message Please select a web content from the list below. You have several options here.

Naturally, if your content appears in the list, you can simply select it. If there is lots of published content available, you could search for the content by name, ID, type, version, content, and site (click the Advanced link to see all the options). You can also show the available locales for your content. If you're working on the page for a particular language, you can select the translation of your content that goes with your locale.

Figure 3.8: Publishing web content is a snap. At a minimum, you only have to select the content you wish to publish. You can also enable lots of optional features to let your users interact with your content.

If you have enabled OpenOffice.org integration with your portal, you can also enable document conversion for your content. This gives your users the ability to download your content in their format of choice. This is especially handy if you are running a research or academically oriented site; users can very quickly download PDFs of your content for their research projects.

Note that you also have other options, such as enabling a Print button, enabling ratings so that users can rate the content, enabling comments, and enabling ratings on comments.

The Print button pops the content up in a separate browser window that contains just the content, without any of the web site navigation. This is handy for printing the content. Enabling ratings shows one of two ratings interfaces Liferay has: five stars or thumbs up and thumbs down. This can be set globally in the portal-ext.properties file. See chapter 12 for further information about this.

Enabling comments creates a discussion forum attached to your content which users can use to discuss your content. Enabling ratings on comments gives your users the ability to rate the comments. You may decide you want one, some, or none of these features, which is why they're all implemented as simple check boxes to be enabled or disabled at need.

If you click the Supported Clients tab, you'll see that you can choose the type of client to which you want to expose content. This lets you target the large screens of users' computers for expansive graphics and lots of special effects, or target the small screens of mobile devices with pertinent information and a lightweight page. For now, leave both checked and click the Save button. You can now close the configuration window.

To publish new content, select the page and green plus icon on the lower left of the portlet. This launches the same full-featured editor you've already seen in the control panel, which lets you add and edit content in place as you are working on your page.

This is another example of the flexibility that Liferay Portal offers. At times, you may want to add content directly into the Web Content Display portlet of the page you're managing, especially if you are in the process of building the page. At other times, you may want to use the control panel to create content, because at that moment you're more concerned with the creation of the content and not where the content will later be displayed. Liferay WCM supports both processes.

Editing content that's already been published is just as easy as creating new content is. You'll use the same exact tools.

Editing Content

Once the content is displayed--whether you've selected content or created it in the Web Content Display portlet--you can edit the content directly from the Web Content Display portlet or from the control panel. To edit it from the Web Content Display portlet, select the pencil icon to the lower left of the portlet. This launches the WYSIWYG editor and from there you can make any necessary changes.

Figure 3.9: Edit, Select, and Add Icons of Web Content Display Portlet

When you publish your content this way, it becomes available immediately (unless, of course, you have a workflow enabled, which we'll see below). This happens whether you edit it in place or in the control panel.

Note: if you want to view your page the way your users will see it (i.e., without all those portlet controls and icons), go up to the Dockbar and select Toggle Edit Controls. This makes all those extra controls you see as a portal administrator disappear. If you need to use those controls again, just select Toggle Edit Controls again.

That's pretty much all there is to simple content creation. Whole sites have been created this way. But if you want to take advantage of the full power of Liferay's WCM, you'll want to use structures and templates. Next, we'll see how they work and how you can use them to make your site more dynamic.

Advanced Content Creation

If you've ever launched a web site, you know that as it grows, you can experience growing pains. This is the case especially if you've given lots of people access to the site to make whatever changes they need to make. Without preset limitations, users can display content in any order and in any manner they desire (think huge, flashing letters in a font nobody can read). Content can get stale, especially if those responsible for it don't maintain it like they should. And sometimes, content is published that should never have seen the light of day.

Thankfully, Liferay WCM helps you handle all of those situations. You can use Structures to define which fields are available to users when they create content. These are coupled with Templates that define how to display that content. Content won't get stale, because you can take advantage of the Scheduling feature to determine when content is displayed and when it's removed. Additionally, you can configure Liferay's built-in Workflow system to set up a review and publishing process so that only what you want winds up on the live site. Liferay Portal gives you the management tools you need to run everything from a simple, one-page web site to an enormous, content-rich site.

All of this starts with structures.

Using structures

Structures are the foundation for web content. They determine which fields are available to users as they create new items for display. Structures not only improve manageability for you the administrator, but also make it much easier for users to quickly add content.

For example, say you're managing an online news magazine. All your articles need to contain the same types of information: a title, a subtitle, an author, and one or more pages of text and images that comprise the body of the article. If Liferay only supported simple content as has been described above, you'd have no way to make sure that your users entered a title, subtitle, and author. You might also get articles that don't match the look and feel of your site. If titles are supposed to be navy blue and they come in from your writers manually set to light blue, you need to spend time reformatting them before they are published.

Structures give you the ability to provide a format for your content so that your users know what needs to be entered to have a complete article. Using structures, you can provide a form for your users which spells out exactly what is required and can be formatted automatically using a template.

To create a structure, you add form controls such as text fields, text boxes, text areas (HTML), check boxes, select boxes, and multi-selection lists, as well as specialized, Liferay-specific application fields such as Image Uploader and Documents and Media right onto the structure. Furthermore, you can move the elements around by dragging them where you want them. This makes it easy for you to prototype different orders for your input fields. Additionally, elements can be grouped together into blocks which can then be repeatable. Template writers can then write a template which loops through these blocks and presents your content in innovative ways, such as in sliding navigation bars, content which scrolls with the user, and more.

Let's look at how we edit a structure.

Editing a Structure

Go back to the control panel and select Web Content from the Site section. Click Add from the Web Content page to add another piece of content to your portal. Instead of going right for the content this time, however, we'll create a structure instead. To edit a structure, simply click on the Edit icon next to the Structure heading near the top of the page.

It's very easy to edit structures: all you have to do is drag elements into the structure and then give them names. For instance, select the Checkbox element under the Form Controls tab and drag it onto the structure. You can do the same with any of the elements. To remove it from the structure, simply select the Delete icon (black circle with X) in the upper right corner of the element. Take a moment to add, delete, and rearrange different elements.

Figure 3.10: Structure Elements

Liferay supports the following elements in structures:

FORM FIELDS

Text Field: Used for items such a titles and headings. Text Box: Used for the body of your content or long descriptions. Text Area (HTML): An area that uses a WYSIWYG editor to enhance the content. Checkbox: Allows you to add a checkbox onto your structure. Template developers can use this as a display rule. Selection List: Allows you to add a select box onto your structure. Multi-selection List: Allows you to add a multi-selection list onto your structure.

APPLICATION FIELDS

Image Uploader: Allows you to add the upload image application into your structure. Documents and Media: Allows you to add the Documents and Media folder hierarchy to your structure.

MISCELLANEOUS

Link to Page: Inserts a link to another page in the same site. Selection Break: Inserts a break in the content.

These form elements provide all you need to model any information type that you would want to use as web content. Liferay customers have used structures to model everything from articles, to video metadata, to databases of wildlife. You're limited only by your imagination. To fire that imagination, let's look more closely at the form elements.

Editing form elements

When creating a new structure it is essential that you set variable names that template writers can use to refer to elements on your form. If you don't do this, Liferay generates random variable names, and these can be difficult for a template writer to follow. For example, consider a field called Author. You might create this field in your form, but the underlying variable name in the structure might look something like TextField4882. The template writer needs to create markup for your structure and place the Author field in a certain spot in the markup. How will he or she know which field is Author, when they're all named randomly?

To solve this problem, all you need to do is set a variable name for each field as you add it to your structure. Let's do this now. In your structure, add an element Text Area (HTML) which has the Field Label Instructions. If we wanted to give it the variable name Steps, we can do it very easily: at the bottom of every form element is a Variable Name field. Replace the generated name with the name you want to use. Now your template writer has a variable by which he or she can refer to this field.

Below each field is a button labeled Edit Options. This contains several other ways to configure your fields:

Field Type: changes the field type, in case you dragged the wrong field type to this location in the form. Field Label: changes the displayed label for the field. Index Type: Choose how you want Liferay to index your field for search. You can have it index by keyword, which filters out common words such as and, but, the, and so on, or you can have it index the full text of the field. By default, indexing is turned off. Predefined Value: If there's a common default value for this field, type it here. Instructions for the User: You can type instructions in the Instructions for the User field and display them as a tooltip by checking the box. Repeatable: If you want this field to be a repeatable element, check this box. Your users will then be able to add as many copies of this field as they like. For example, if you're creating a structure for articles, you might want a repeatable Author field in case you have multiple authors for a particular article. Required: Check the box to mark the field required. If a field is required, users cannot submit content using this structure without filling out this field.

For the Nose-ster structure, type something in the Instructions for the User field that helps users know what to put into the Body element (example: this is an HTML Text area for the body of your content). Also enable the Display as Tooltip box. Now, when users hover over the Help icon near your title, your instructions are displayed.

As with everything else in Liferay, you can set permissions on structures. Let's see how you'd do that.

Assigning Permissions

Setting permissions on structures is done using the same procedure as permissions everywhere else in Liferay. Most users should not have the ability to edit structures. Structures are coupled with templates, which require some web development knowledge to create. For this reason, only trusted developers should be able to create structures and templates. Users, of course, should be able to view structures. The View permission enables them to make use of the structures to create content.

Figure 3.11: View Permission for a Structure

You can grant or deny permissions based on Roles, and this is the recommended way to handle permissions for structures.

Now that you understand what structures are used for, you need to understand the other half of Liferay's web content management system: templates.

Using templates

Developers create templates to display the elements of the structure in the markup that they want. Content can then be styled properly using CSS, because markup is generated consistently by the template when structured content is displayed. In essence, templates are scripts that tell Liferay how to display content in the structure. Any changes to the structure require corresponding changes to the template, because new or deleted fields produce errors on the page. If users enter content into a structure, it must have a matching template. Without a template, the portal has no idea how to display content which has been created using a custom structure.

Let's look more closely at the types of templates Liferay supports.

Template Types (VM, XSL, FTL, and CSS)

Liferay supports templates written in four different templating languages, to support the skill sets of the largest number of developers. This increases the chances that you can jump right in and use whichever one you've already used before. If you haven't yet been exposed to any of them, your best bet is Velocity or Freemarker, as they are less "chatty" than XSL and extremely simple to understand.

VM (Velocity Macro): Velocity is a scripting language that lets you mix logic with HTML. This is similar to other scripting languages, such as PHP, that you may have seen before, though Velocity is much simpler. It's been in the product the longest, so it is probably the most widely used language for templates in Liferay WCM. If you haven't used any of the template languages before, we recommend using Velocity: you'll get up to speed the fastest.

XSL (Extensible Style Sheet Language): XSL is used in Liferay templates to transform the underlying XML of a structure into markup suitable for the browser. While it may not be as clean and compact as Velocity or FTL, it's widely used for transforming XML into other formats, and it's very likely your developers have already been exposed to it.

FTL (FreeMarker Template Language): Freemarker is a templating language which could be considered a successor to Velocity, though it is not yet as popular. It has some advantages over Velocity for which it sacrifices some simplicity, yet it is still easy to use.

CSS (Cascading Style Sheets): You can use CSS if your structure is very straightforward and modifications are simple (colors, fonts, layouts, etc). If your structure is more complex, however, you'll need to use one of the other options.

Adding a Template

Liferay WCM makes it easy to create structures, templates, and content from the same interface. Let's go through the entire flow of how you'd create a structure, link it to a template, and then create content using them both. We'll use Velocity for our template, and we'll lay out the structure fields systematically to go along with the format we've defined for our content.

Figure 3.12: Adding Template Interface

1. Go back to the Web Content section of the control panel and click Add under Web Content.
2. Click the Edit icon for Structures.
3. Remove the Content field and add the following fields: