Chapter 5. Building your own portal
- Creating organization, roles, and users in Liferay Portal
- Creating portal pages and adding portlets
- Setting permissions for portal pages and portlets
- Configuring Liferay Portal
- Developing portal themes and layouts with the Liferay Plugins SDK
Chapters 3 and 4 introduced the Portlet 2.0 API with an example Book Catalog portlet. Now that you know the nuts and bolts of portal development, it’s time to build your own web portal. In this chapter, you’ll develop a web portal, named Book Portal, with Liferay Portal.
You’ll see firsthand the importance of knowing your portal server and how built-in features of the portal server can reduce your development effort for custom portlets. How quickly you can develop and deploy a functional web portal should be one of the criteria you use in selecting a portal server. In some cases, depending on your portal server’s features, you may consider adjusting the design of your custom portlets so they’re easier to develop quickly (you’ll see this in the context of the Book Catalog portlet, later in this chapter).
Note
This chapter is specific to Liferay Portal. If you’re not using Liferay Portal, you might want to skip or skim through this chapter. If you’re new to portlet development, you should read this chapter to get a feel for web portal development. If you’re using GateIn Portal, refer to appendix A for details on how to create a web portal with GateIn.
In this chapter, you’ll develop Book Portal using Liferay Portal as your portal server. The development approach followed in this chapter is common in developing web portals. As we go through the process of developing Book Portal, we’ll touch upon some of the features offered by Liferay Portal. You’ll also see how the Book Catalog portlet (developed in chapters 3 and 4) uses Liferay Portal’s document storage feature to store e-books.
Let’s first look at the requirements of the Book Portal web portal.
5.1. Requirements for Book Portal
Book Portal allows its registered users to search for and download e-books. The following are the main requirements for Book Portal:
- Book Portal allows the portal administrator to publish announcements on the portal’s home page, and these should be visible to both anonymous and registered users. The published announcements should be made available either immediately or at the date and time the administrator specifies for their publication.
- Book Portal displays the most popular products available at www.amazon.com that are tagged with “Java.”
- Book Portal shows books in the catalog that are currently available to registered users of the portal. The book catalog can only be updated by the portal administrator. For each book in the catalog, the following information should be displayed to the registered user: title, author, ISBN, and a download link for the book. Registered users should be able to take a printout of the catalog if they choose. They should also be able to set their preference regarding the number of books they want to view on the page. The book catalog provides a search facility so users can easily locate books.
- Book Portal provides discussion forums for each book in the catalog to allow registered users to discuss the books.
- The portal administrator can additionally perform the following actions on the book catalog: update book information, add new book information, and remove book information.
- Book Portal has a message board for each of the books in the book catalog. The administrator is responsible for creating the message board for a book. Registered users can post comments on the message board and subscribe to posts or message boards for books. Anonymous users of the portal can view the message boards, but they can’t post messages.
- It should be easy for the Book Portal administrator to change the look and feel of the portal or the layout of the pages.
- The company developing Book Portal has an internal application, In-Demand Book Apps, which the company staff uses to store information about the books that are most frequently sought after on the internet. The company plans to make this application available via Book Portal to a few select users, to allow them to submit information about the books that they would like to be made available by Book Portal.
Book Portal’s requirements are typical of web portals. In a web portal, there are often different types of users (such as registered users, anonymous users, administrators, and so on), and each user type has a different set of access permissions. A web portal may also act as the single point of entry to other web applications, like the In-Demand Book Apps web application, which is accessed via Book Portal. In a web portal, themes let you easily change the look and feel of the portal, and page layouts let you easily organize portlets on portal pages.
It’s important to know the different types of users of your web portal, because each user type has access to a different set of operations and information. Book Portal has three different types of users: portal administrator, registered users, and anonymous users.
- Portal administrator— The Book Portal administrator is responsible for creating the portal pages, adding portlets to the portal pages, and configuring portlets so that only authorized individuals can access portlets and perform restricted actions. The portal administrator also handles the tasks related to maintaining the book catalog, like adding, removing, and editing books in the catalog. You can think of the portal administrator as the superuser of the portal who can perform all the actions available in the portal server.
- Registered users— Registered users of Book Portal can view the book catalog and download books. They also can post messages on message boards.
- Anonymous users— Anonymous users of the system can only view published announcements and RSS feeds from Amazon. They don’t have access to the book catalog or to post messages on message boards.
Note
Both Jetspeed and Liferay Portal provide administration features to define access rights for a portlet based on the user role. You could use either of these portal servers to address the security requirements of Book Portal.
Now let’s look at how you can create Book Portal and its users in Liferay Portal.
5.2. Getting started developing Book Portal
To get started with developing Book Portal in Liferay Portal, you need to perform the following activities:
- Create an organization—Liferay Portal’s way of identifying a web portal
- Create users and roles, and map users to roles
Liferay Portal lets you identify users belonging to an organization. You can think of Book Portal as an organization whose user base consists of registered users and a portal administrator. The registered users in the Book Portal organization have the BookUser custom role, and the Book Portal administrator has the PortalAdministrator custom role.
Initially, you need to set up the following for Book Portal:
1.
Create the Book Portal organization in Liferay Portal— The starting point for developing Book Portal is to create an organization in Liferay Portal with which users of the portal are associated.
2.
Create roles that are applicable to the Book Portal organization— This includes PortalAdministrator and BookUser. Liferay Portal treats anonymous users as users having the Guest role, which is a predefined role in Liferay Portal, so you don’t need to create it.
3.
Create users— You need to create users who are predefined in the portal. For instance, a registered user is created in Book Portal when a user registers with the web portal, but the Book Portal administrator (who has the PortalAdministrator role) needs to be created.
4.
Map users to roles— When a user registers with Book Portal, they should automatically be assigned the BookUser role. Anonymous users are by default mapped to the Guest role by Liferay Portal.
5.
Assign users to the organization— Registered users should be automatically assigned to the Book Portal organization.
Figure 5.1 shows the process for setting up the web portal.
Figure 5.1. The process described in this chapter for setting up a portal in Liferay Portal
Note
The concept of an organization is specific to Liferay Portal, but in most portal servers you’ll find features for creating roles and users and for assigning roles to users.
Let’s begin by creating the organization with which Book Portal is associated.
5.2.1. Creating an organization for Book Portal
To create an organization for Book Portal, you need to log in as the Liferay Portal administrator. Once you do that, you’ll have full control over the portal, and you’ll be able to create organizations, roles, users, portal pages, and a lot more. In this chapter, you’re interested in creating an organization for Book Portal and a user whose role is PortalAdministrator. Once you have a user with the PortalAdministrator role, the job of creating portal pages, adding portlets to portal pages, and defining additional roles for the Book Portal organization will lie with the PortalAdministrator.
To log in as the Liferay Portal administrator, go to the home page of Liferay Portal 6.x and select the Login as Bruno option, as described in chapter 1. Once you are logged in as administrator (Bruno), you can create an organization for Book Portal. Follow these steps:
1. Select Manage > Control Panel from the dockbar.
2. In the control panel screen, select the Organizations option, which lets you manage organizations in the portal.
3. In the Organizations window, as shown in figure 5.2, you’ll see that the 7Cogs, Inc. organization already exists—it comes by default with Liferay Portal to give you the feel of how a portal created using Liferay Portal works. Click Add to add a new organization to the portal.
Figure 5.2. Click the Add button to add a new organization to the portal.
4. A form will be displayed where you can enter the name of organization you want to create and its type, as shown in figure 5.3. Enter MySamplePortal, Inc as the Name of organization, and select Regular Organization as its Type. Click Save to save the organization information.
Figure 5.3. Create an organization by entering a name and type for it. Clicking the Save button will save the organization information in the database used by Liferay Portal internally. The Modified message is displayed at the top right whenever a modification is made to the organization’s information.
5. Once the organization information is saved successfully, you’ll see more information that can be entered for your newly created organization, as shown in figure 5.4. You can upload a logo for the organization, and you can specify miscellaneous details such as phone numbers, email addresses, and so on. Enter any information you wish for the organization, and click Save.
Figure 5.4. Additional organization information is displayed to the administrator after the organization information is saved the first time. The administrator can upload a logo for the organization and specify its parent organization (if any). The Group ID uniquely identifies an organization in Liferay Portal.
The newly created MySamplePortal, Inc organization will now be displayed in the list of organizations defined in Liferay Portal. The Group ID shown in figure 5.4 uniquely identifies the organization in Liferay Portal.
Note
The Group ID is useful in implementing custom portlets that interact with Liferay Portal’s services or database.
You have successfully created the Book Portal organization in Liferay Portal. You’re now ready to create the PortalAdministrator and BookUser roles.
5.2.2. Creating roles for Book Portal users
Roles in Liferay Portal are independent of organizations; you can create a role and associate any user, of any organization, with that role. For instance, you can create a BookUser role and associate it with a user of organization X and also with a user of organization Y.
To create a role, select Manage > Control Panel from the dockbar, and in the control panel screen select the Roles option, which allows you to add, remove, or edit role information. On the Roles page, click Add to add the BookUser custom role.
Figure 5.5 shows the information that you need to enter to create a role in Liferay Portal. Enter BookUser as the role Name, add a description for the role, and click Save. Once the role is saved, it will show up among the other roles defined in Liferay Portal.
Figure 5.5. Role information that needs to be added to Liferay Portal
Now that you have created the BookUser role, you’re ready to create the PortalAdministrator role. But consider for a moment whether you really need a PortalAdministrator role. The predefined Administrator role in Liferay Portal is for a user who has full control over Liferay Portal. This is similar to the PortalAdministrator role for Book Portal, so you don’t need to create a new role. Liferay Portal’s built-in Administrator role meets your requirements for Book Portal.
Note
It’s recommended that you check the predefined roles in your portal server before creating a new role, to avoid creating duplicate roles with the same permissions.
You’re now ready to associate the BookUser role with the MySamplePortal, Inc organization, because the BookUser role is specific to MySamplePortal, Inc.
5.2.3. Mapping roles to the Book Portal organization
Look at the list of roles defined in Liferay Portal, and click the Action button for the BookUser role. Click the Assign Members option to associate the BookUser role with the MySamplePortal, Inc organization. Figure 5.6 illustrates how you can do this.
Figure 5.6. Assigning a Liferay Portal role to an organization. The Update Associations button lets you associate a particular role with an organization.
In figure 5.6, select Assign Members > Organizations > Available to view the organizations defined in Liferay Portal. Click the check box beside the MySamplePortal, Inc organization, and click the Update Associations button to associate the BookUser role with MySamplePortal, Inc.
The Importance of Associating a Custom Role with an Organization
In Book Portal, you have associated the custom BookUser role with the MySamplePortal, Inc organization, which means that any user having the BookUser role is implicitly associated with the MySamplePortal, Inc organization. The reason for making this association is so that it’s explicit that the BookUser role is meaningful only in the context of MySamplePortal, Inc. In Liferay Portal, you may have multiple organizations, and explicitly associating a custom role with an organization can help clarify that the role is meaningful only in the context of a particular organization.
You’re now ready to create a user who will act as the portal administrator for the MySamplePortal, Inc organization.
5.2.4. Creating Book Portal users and assigning them to the organization
If your portal has predefined users, you need to create them for the portal. Registered users are created when users register with Book Portal, so you don’t need to create them. The Book Portal administrator is the only predefined user of Book Portal, so that’s the only user you need to create.
What you need to do is create a user in the MySamplePortal, Inc organization, and then assign that user the built-in Liferay Portal role of Administrator.
You can create a user by selecting Manage > Control Panel from the dockbar, and selecting the Users option. Click Add to create new users in Liferay Portal. Figure 5.7 shows the form for adding a user to Liferay Portal.
Figure 5.7. Enter information about the user to be created in Liferay Portal.
For this example, keep the email address of the Book Portal administrator as [email protected]. You’ll use this email address to log in as the Book Portal administrator. Enter the user information, and click Save to save the user information.
Once the basic information about the portal administrator user is saved, additional information can be entered for the user, as shown in figure 5.8.
Figure 5.8. Additional user information can be entered after the basic information is saved. The User ID uniquely identifies a user in Liferay Portal, the Password option is used to set the user’s password, the Organizations option is used to assign the user to an organization, and the Roles option is used to assign roles to the user.
In figure 5.8, the additional information displayed after the basic user information is saved lets you assign the user to an organization and set a password. You can also upload the user’s photograph at this time. The User ID shown in figure 5.8 is a unique identifier for the user, generated by Liferay Portal, and it’s useful in developing custom portlets that interact with the Liferay Portal services or database.
In figure 5.8, click the Password option to set the password for the Book Portal administrator. You also need to associate the Book Portal administrator with the MySamplePortal, Inc organization so that MySamplePortal, Inc is reflected as the organization managed by the Book Portal administrator. To do so, click the Organizations option in figure 5.8. Now, click the Select hyperlink to view and associate the Book Portal administrator with the MySamplePortal, Inc organization, as shown in figure 5.9.
Figure 5.9. Clicking the Select hyperlink opens the list of organizations in Liferay Portal. To associate the Book Portal administrator with MySamplePortal, Inc, click MySamplePortal, Inc organization from the list.
Once you have selected MySamplePortal, Inc, save the Book Portal administrator details by clicking Save (shown in figure 5.7).
The next step is to associate the Book Portal administrator user with the predefined Administrator role.
5.2.5. Mapping users to roles
Registered users of Book Portal need to be mapped to the BookUser role. You’ll see later in this chapter how registered users are automatically mapped to the BookUser role when they register. In this section, you’ll see how the Book Portal administrator is mapped to Liferay Portal’s built-in Administrator role.
Click the Roles option in figure 5.8 to view or edit the roles the Book Portal administrator is associated with. Figure 5.10 shows the form that’s used to select appropriate roles for the Book Portal administrator.
Figure 5.10. The Select option under Regular Roles lets you select regular roles like Administrator, Power User, BookUser, and so on. Select Administrator as the role for the Book Portal administrator.
In figure 5.10, click the Select option under the Regular Roles heading. Choose the Administrator role for the Book Portal administrator, because you want the portal administrator to have full control over Liferay Portal.
So far, you have completed the following steps:
1. Created the MySamplePortal, Inc organization.
2. Created the BookUser role for users who will register with Book Portal. Note that you didn’t create any users with BookUser role. The users who register themselves with Book Portal will be associated with the BookUser role.
3. Associated the BookUser role with the MySamplePortal, Inc organization.
4. Created a user, with email address [email protected], who acts as the Book Portal administrator.
5. Assigned the Administrator role to the user you created to act as the Book Portal administrator.
The next step is to log in as the Book Portal administrator and create public portal pages for the MySamplePortal, Inc organization, and to add portlets to those portal pages.
5.3. Creating portal pages and adding portlets
A web portal consists of portal pages containing portlets that display content. Regardless of which portal server you’re using, you’ll be required to create portal pages and to add portlets to them. Depending upon the requirements of your web portal, you’ll also need to define permissions for the portal pages and portlets. For instance, registered users in Book Portal shouldn’t have access to add, update, and remove books from the book catalog, and anonymous users shouldn’t be able to view portal pages that are accessible only to registered users.
In this section, you’ll create portal pages for Book Portal, add required portlets to the portal pages, and learn how to restrict unauthorized access to portal pages and portlets as specified by the Book Portal requirements. In this section, you’ll also see how the Book Portal requirements determine whether a built-in or a custom portlet should be used.
Let’s first go through the steps required to create the Book Portal Home page, which will also show you how to create portal pages in Liferay Portal in general.
5.3.1. Creating a Home portal page
To create portal pages for the MySamplePortal, Inc organization, log in as the Book Portal administrator (the userid is the email of the Book Portal administrator: [email protected]). Select the Manage > Control Panel option from the dock-bar, and select the Organizations option in the control panel. You’ll see the list of organizations that have been created in Liferay Portal, as shown in figure 5.11.
Figure 5.11. MySamplePortal, Inc is shown as an organization that has been created in Liferay Portal.
In figure 5.11, if you click the Actions button, it will show you the actions you can perform on the organization (which will vary depending on your role). Figure 5.12 shows the actions that you can perform as an Administrator.
Figure 5.12. Options available to the Book Portal administrator on the MySamplePortal, Inc organization
Select the Manage Pages option to create public portal pages for MySamplePortal, Inc. Figure 5.13 shows the options that you’ll see.
Figure 5.13. The Public Pages top-level tab shows three subtabs for managing the public portal pages of the MySamplePortal, Inc organization. You can add a new page here, edit an existing page’s title, or change the order in which they’re displayed in the portal.
Figure 5.13 shows all the options related to managing an organization’s portal pages. At the top are three tabs: Public Pages, Private Pages, and Settings. The Public Pages tab has three subtabs: Pages, Look and Feel, and Export/Import. In this section, we’ll focus on the Pages subtab, which is where you create Book Portal pages. The Look and Feel subtab is discussed in section 5.5.2.
The Pages subtab allows you to create and edit your public portal pages. Under the New Page tab, enter Home as the Name of the portal page, and keep the Type of page as Portlet. Click Add Page to save the Home page. When the page information is successfully saved, the newly added page is shown in the page hierarchy on the left side of the form, as shown in figure 5.14.
Figure 5.14. The newly added Home page is shown in the page hierarchy displayed on the left side of the form. The View Pages button lets you view the pages of the MySamplePortal, Inc organization. The Display Order option lets you change the order in which the pages are displayed in the web portal.
Now that the MySamplePortal, Inc Home page has been created, let’s add portlets to it. To view the MySamplePortal, Inc pages, select Go To > MySamplePortal, Inc from the dockbar.
Once you’re on the Home page of the MySamplePortal, Inc organization, you can add appropriate portlets to create the home page of your Book Portal, as shown in figure 5.15.
Figure 5.15. Book Portal’s Home page, consisting of built-in Announcements, RSS, Sign In, and Calendar portlets
Figure 5.15 shows how the Home page of Book Portal looks to the Book Portal administrator. The Home page includes the following built-in portlets:
- Sign In— Located under the Tools application category that shows up when you select the Add > More option from the dockbar. It allows users to log in to Book Portal.
- Calendar— Located under the Collaboration application category that shows up when you select the Add > More option from the dockbar. It shows important upcoming events.
- Announcements— Located under the News application category that shows up when you select the Add > More option from the dockbar. It shows announcements.
- RSS— Located under the News application category that shows up when you select the Add > More option from the dockbar. It displays the most popular products tagged with Java that are available at www.amazon.com.
By default, the page layout of the Home page is set to 2 Columns (30/70)—the page is partitioned into two columns with the first column taking 30 percent of the page width and the second column taking the remaining 70 percent. You may want to change the page layout so that all the portlets are displayed appropriately on the page. To change the layout, select the Manage > Page Layout option from the dockbar and choose the 2 Columns (70/30) page layout, as shown in figure 5.16.
Figure 5.16. The 2 Columns (70/30) page layout partitions the page into two columns where the first column takes 70 percent of the page width and the second column takes 30 percent of the page width.
After selecting 2 Columns (70/30) as the page layout of the Home page, save changes by clicking Save. You’ll now see that the portlets in the Home page of Book Portal are resized to the new page layout.
Let’s take a look at the Announcements and RSS portlets in detail.
5.3.2. Adding an Announcements portlet
The announcement feature in Book Portal is not simple, because each announcement can either be published immediately or at a scheduled date and time. Neither Jetspeed nor GlassFish (with OpenPortal Portlet Container 2.1.2) provide any built-in portlets for publishing announcements, but Liferay Portal does have a built-in Announcements portlet that exactly matches the requirements of Book Portal’s publish announcement feature. You can find the Announcements portlet under the News category when you select the Add > More option from the dockbar.
Figure 5.17 shows the Announcements portlet, which allows you to publish announcements immediately or at a scheduled date and time. The Manage Entries tab allows you to add, edit, and delete announcements.
Figure 5.17. The Manage Entries tab allows you to add, edit, and delete announcements. The Distribution Scope drop-down list allows you to select the role for which you want to view, add, modify, or delete announcements.
Note
If you don’t see the Manage Entries tab, make sure that you’re logged in as the portal administrator.
The Distribution Scope drop-down list in the Announcements portlet allows you to choose the roles for which the announcement is meant. There are many predefined roles in Liferay Portal, such as Administrator, User, Guest, Power User, and so on, that you can select. It also shows any custom roles you have created in Liferay Portal. For instance, the Distribution Scope drop-down list also shows the BookUser role, which you created earlier in this chapter.
To add a new announcement, click Add Entry shown in figure 5.17. An Entry announcement form will be displayed, in which you can enter the announcement information, as shown in figure 5.18.
Figure 5.18. The Announcement portlet allows you to specify the date and time when the announcement will be published and expired. The Distribution Scope lets you choose the user roles for which the announcement is being published.
Figure 5.18 shows that while adding an announcement you can select a Distribution Scope, which means you can select the user roles to which the published announcement is visible. If you choose General as the Distribution Scope of an announcement, it’s visible to all users of the system, including anonymous users. The Book Portal requirement in section 5.1 specifies that the announcements must be visible to anonymous users, so you should choose General as the Distribution Scope for the announcement.
The Display Date and Expiration Date options allow you to specify the date and time when the announcement is published (when it’s made visible to users) and removed from Book Portal’s Home page.
As you can see, the features offered by the built-in Announcement portlet match the requirements for Book Portal. Figure 5.19 shows how the announcement portlet will appear to a registered user.
Figure 5.19. The announcement portlet shows published announcements.
Figure 5.19 shows the announcement that was published using the built-in Announcements portlet. If an announcement’s Display Date is after the current date, or its Expiration Date is before the current date, the announcement isn’t shown by the portlet.
Note
The limitation of the built-in Announcement portlet is that it doesn’t allow you to localize the announcement’s text based on the user’s locale. As there is no localization requirement specified for Book Portal, we don’t need to worry about this.
5.3.3. Adding an RSS feed portlet
You can obtain information about the most popular Java books from Amazon using RSS feeds. You saw in chapter 1 that Liferay Portal’s built-in RSS feed portlet can be used to receive RSS feeds from websites.
To receive an RSS feed from Amazon, you first add an instance of the built-in RSS portlet from the News category to your Home portal page. The Configuration option (displayed when you click the configure portlet icon from the portlet window’s title bar) for the RSS portlet allows you to specify the locations on the internet from which to obtain the RSS feeds, as shown in figure 5.20.
Figure 5.20. The Configuration option for the RSS portlet lets you specify the URL from which to receive the RSS feeds.
In figure 5.20, you specify the title for the RSS feed and its location. In the Title field, enter Popular Java Books, and in the URL field enter the following URL: http://www.amazon.com/rss/tag/java/popular?length=100.
Tip
For more information about how to retrieve RSS feeds for tagged products from Amazon, see Amazon’s RSS help: http://www.amazon.com/gp/tagging/rss-help.html.
Figure 5.21 shows the RSS portlet showing the most popular products from Amazon tagged with “Java.”
Figure 5.21. The RSS portlet showing the most popular products from Amazon tagged with “Java”
As you can see, the features offered by Liferay Portal’s built-in RSS portlet meet the Book Portal requirements.
Next we’ll look at how you can define permissions for portal pages, portlets, and roles.
5.3.4. Setting permissions for portal pages and portlets
An Administrator user can define permissions for the portal pages and portlets that form part of an organization.
Select Go To > MySamplePortal, Inc from the dockbar. To specify permissions for a portal page, select the Manage > Page option from the dockbar. Select the Home page from the hierarchy, to specify permissions for it. The Page tab has a Permissions button (shown in figure 5.22), and clicking it allows you to set the permissions for the page.
Figure 5.22. You can define permissions for a portal page by selecting the Manage > Page option from the dockbar. The Permissions button lets you modify permissions for the selected portal page.
Once you click the Permissions button, you’ll be presented with options to view and edit the permissions for the Home portal page, as shown in figure 5.23. This figure shows the various roles in Liferay Portal and their access permissions for the Home portal page. These are some of the permissions you can configure:
Figure 5.23. Home page permissions for different roles. The BookUser role isn’t even allowed to view the portal page, and the Guest user can view the portal page but can’t update it.
- Add Discussion— Allows a user to post a comment. This permission is useful when you want users to post comments regarding the web content published on the portal page.
- Update— Allows a user to remove portlets from a portal page and to move them around on the portal page.
- View— Allows a user to view the portal page.
Figure 5.23 shows that BookUser doesn’t have view, update, or add discussion permissions for the Home portal page.
To allow BookUser to view the Home portal page, select the View permission for BookUser and save the changes. Custom roles (and other roles in Liferay Portal) inherit their permissions from the Guest role, so this change isn’t required, but it’s good to make it explicit that BookUser can view the Home portal page. Now users with Guest (also referred to as anonymous) or BookUser roles can view the Home portal page.
Note
You shouldn’t give users Update permission for public portal pages (except for the portal administrator), because it will allow them to change the page structure, remove portlets from the portal page, and change settings for the portlets.
Like portal pages, portlets can also have permissions for different users. To view the permissions for a portlet, log in as the Book Portal administrator and select the Configuration option (displayed when you click the configure portlet icon from the portlet window’s title bar) for any of the portlets you have added to the Home portal page.
The Configuration option shows the configuration options available for the portlet, as shown in figure 5.24 for the Announcements portlet.
Figure 5.24. The Permissions tab shows the permissions for the portlet. On this screen, you can modify the permissions for a portlet.
In figure 5.24, the Permissions tab shows the portlet permissions that are defined for different roles. This is what the permissions do:
- View— Allows a user to see the portlet.
- Configuration— Allows a user to configure the portlet with the portlet’s Configuration option.
- Add to Page— Allows a user to add the portlet to a portal page. You saw this permission in chapter 1.
- Add Entry— Allows a user to add new announcements to the Announcements portlet.
As mentioned earlier, roles in Liferay Portal inherit their permissions from the Guest role; any user can view the portlet if the Guest role has the permission to view the portlet.
In figure 5.24, only the View, Configuration, Add Entry, and Add to Page options can have permissions defined. If the portlet supports additional portal-managed portlet modes (as discussed in chapter 4), you’ll see additional options, as in the case of the Book Catalog portlet. The Book Catalog portlet supports print, help, and edit portlet modes, which will also show up in the Permissions tab.
Note
You’ll usually give only View permissions to users, as well as Preferences permissions if the portlet allows users to personalize the portlet content (which means it supports EDIT portlet mode). If you give Configuration permissions, users can change the look and feel of the portlet and define permissions for it, which is usually not allowed.
Now let’s look at the custom Book Catalog portlet from chapter 4 and see how it can use the built-in Document Library portlet to meet its requirements.
Code Reference
You should now import the code from the ch5_BookCatalog project into your Eclipse workspace, and build and deploy the portlet in your Liferay Portal server.
5.3.5. Using the built-in Document Library and Book Catalog portlets together
One of the primary requirements for Book Portal is that it should allow the portal administrator to manage books in the catalog and allow registered users to view, search for, and download e-books. The most important point to consider is where to store the e-book. You can store the book in a database or in the portal server’s filesystem. Liferay Portal provides a Document Library portlet, which we discussed in chapter 4, and you can consider using it to store your e-books. Let’s see how the Document Library portlet can be used in collaboration with the Book Catalog portlet.
To start, log in as the Book Portal administrator and create a Catalog portal page and set page layout to 2 Columns (50/50), as explained in section 5.3.1. Add the Book Catalog and Document Library portlets to the Catalog portal page, as shown in figure 5.25.
Figure 5.25. The Catalog portal page shows the Book Catalog and Document Library portlets to a portal administrator. The Document Library portlet isn’t visible to registered users of the portal.
To organize documents stored by the Document Library portlet, create a folder named Java Books using the portlet’s Add Folder option, as shown in figure 5.26.
Figure 5.26. The Add Folder option enables you to add a folder to the Document Library portlet. The Add Document option is for uploading a document to be stored by the portlet.
Figure 5.26 shows that you can use the Add Folder option to add a folder, and Add Document to store a document using the Document Library portlet.
The Document Library portlet provides the download URL for each document that’s stored in the document library. Just select the document in the Document Library portlet, and the portlet will display the URL, as shown in figure 5.27.
Figure 5.27. The Document Library portlet is used to store documents. You can view the download URL for a document by selecting the document in the portlet.
In figure 5.27, we want to view the download URL for the AspectJ in Action e-book. Selecting the AspectJ in Action.doc hyperlink displays its download URL, as shown in figure 5.28.
Figure 5.28. The Document Library portlet provides the download URL for a document, which can be used by other portlets to download a document directly without needing to go to the Document Library portlet.
The download URL of a document in the Document Library portlet refers to a servlet in Liferay Portal that’s responsible for downloading the document or file identified by the URL. The same URL can be used by the Book Catalog portlet to allow the downloading of e-books. By using the Document Library portlet to store the e-books, the Book Catalog portlet isn’t responsible for uploading e-books or storing them in a filesystem or database.
Figure 5.29 shows the Book Catalog portlet, which uses the download URL provided by the Document Library portlet to allow the downloading of e-books. In this figure, the Download link for each of the books refers to the download URL provided by the Document Library portlet for the corresponding e-book. The Book Catalog portlet’s Upload Book form (which is shown when the Book Portal administrator clicks the Upload hyperlink for a book) only requires the download URL for the e-book and not the e-book itself, as shown in figure 5.30.
Figure 5.29. The Download link in the Book Catalog portlet refers to the download URL obtained for the e-book from the Document Library portlet.
Figure 5.30. The Book Catalog portlet’s Upload Book form. You don’t upload the e-book; instead, you enter the download URL of the e-book, which is then used by the Book Catalog portlet’s Download link.
In figure 5.30, you don’t upload the e-book. Instead, you provide the download URL of the corresponding e-book that was stored in the Document Library portlet. The download URL is later used by the Book Catalog portlet’s Download link to allow users to download e-books.
The Impact of Using Built-in Portlets
The use of the Book Catalog portlet in combination with the Document Library portlet demonstrates the impact that a portal server’s built-in portlets can have on the design of custom portlets. Using the Document Library portlet to store e-books reduces the time and effort required to implement the Book Catalog portlet, making it possible to quickly develop your Book Portal. As a general rule, if you’re creating portlets targeted for a particular portal server, consider reusing the functionality offered by built-in portlets before finalizing the design of custom portlets.
Now that you’ve created the Catalog portal page and added the Document Library and Book Catalog portlets, it’s time to set permissions for the Catalog portal page and its portlets.
5.3.6. Setting permissions for displaying the book catalog
Book Portal requires that the registered users of the portal can view the catalog and download e-books. The portal administrator is responsible for managing the catalog. A registered user only needs to interact with the Book Catalog portlet, but a portal administrator needs to use both the Book Catalog (for managing book information) and the Document Library (to upload e-books) portlets.
When defining permissions for the Catalog portal page and its portlets, you need to take care of the following requirements:
- The Catalog portal page isn’t accessible to Guest (or anonymous) users.
- The Catalog portal page shows both the Book Catalog and Document Library portlets to the portal administrator so that it’s easy for the administrator to move between the two portlets when the upload URL for a book needs to be specified in the Book Catalog portlet.
- The Catalog portal page shows only the Book Catalog portlet to registered users. As registered users of Book Portal are represented by the BookUser role, a user with the BookUser role can view the Book Catalog portlet. Registered users aren’t allowed to add, remove, or update book information, so if they click Add Book or the Remove and Upload hyperlinks in the Book Catalog portlet, they should see an “access denied” message.
Let’s see how you can address these requirements.
Restricting Guest Users
The Guest (or anonymous) users of the portal must not have access to the Catalog portal page. The registered users—those users with the BookUser role—should be able to access the Catalog portal page.
In section 5.3.4 you saw how to set permissions for a portal page. For the Catalog portal page you need to provide View permission for the BookUser role and remove it for Guest users. This is shown in figure 5.31.
Figure 5.31. Giving View permission to the BookUser role and removing it from the Guest role
In figure 5.31, View permission is assigned to the BookUser role, so registered users of the application can access the Catalog portal page. The Guest role doesn’t have View permission, so those users can’t access the Catalog portal page.
Restricting Registered Users
The registered Book Portal users shouldn’t have access to the Document Library portlet, so you need to remove the View permission for the Guest role, as shown in figure 5.32. Because all roles in Liferay Portal inherit from the Guest role’s permissions, removing View permission for Guest removes the View permission that was implicitly available to BookUser.
Figure 5.32. View permission for Guest is removed to restrict BookUser from accessing the Document Library portlet.
The registered users of Book Portal aren’t allowed to add or remove books from the catalog. Also, registered users aren’t allowed to specify the download URL of an e-book using the Upload hyperlink. This requirement is addressed in the Book Catalog portlet using programmatic security; it uses the PortletRequest’s isUserInRole method to check the user role before allowing access to functionality for adding, removing, or specifying the download URL for books. Chapter 4 goes into detail on how to use the isUserInRole method in portlets. If the user’s role is BookUser, the add, remove, and upload book functionality isn’t allowed; if the user’s role is Administrator, that functionality is enabled.
5.3.7. Setting permissions for displaying discussion forums
The last portal page that you need to create is for the discussion forums, where registered Book Portal users can discuss the book with other registered users.
To create the forums, log in as the Book Portal administrator and create a portal page named Forums (as described in section 5.3.1) and add the built-in Message Boards portlet (found under the Collaboration category), as shown in figure 5.33. Also, set page layout to 1 Column, as explained in section 5.3.1.
Figure 5.33. The Forums portal page contains the Message Boards portlet, which shows the message boards for various books.
Figure 5.33 shows the Forums portal page of Book Portal, which contains the built-in Message Boards portlet. With this portlet, a portal administrator can create forums for various books, and registered users can discuss the books in the forum. You create forums in the Message Boards portlet by clicking the Add Category button, shown in figure 5.33, and creating a Category.
In the case of the Message Boards portlet, permissions need to be defined at the Category (forum) level and at the portlet level. Portlet-level permission for the Message Boards portlet is specified using the Configuration option (displayed when you click the configure portlet icon from the portlet window’s title bar) to allow or restrict users from viewing the portlet. Category-level permissions (displayed when you click Permissions button) are specified to control the functions offered by the message board, such as adding messages, subscribing to threads, deleting messages, and so on.
You should define portlet-level permissions to allow the Guest and BookUser roles to view the portlet. Define Category-level permissions to allow the BookUser role to view messages, add messages, reply to messages, and subscribe to threads.
This completes the development of Book Portal, but there are still a few settings that need to be defined for Liferay Portal server before Book Portal is ready for use. In the next section we’ll discuss these settings.
5.4. Configuring Liferay Portal server settings
Liferay Portal server settings are meant for providing global settings for all portals created on the same portal server instance. By using Liferay Portal server settings, you can define the authentication settings for users, default roles with which a newly registered user is associated, the email server that’s used to send emails to users, events for which emails are sent out, the default display settings to be used by web portals, and so on.
Book Portal was created in Liferay Portal, and it’s possible that multiple portals are supported by the same instance of Liferay Portal server. The portal server settings apply to all the portals on the server instance.
To view the portal server settings, log in as the Book Portal administrator and select the Settings option from the control panel. It lets the Liferay Portal administrator view and edit settings that apply to the portal server instance.
Warning
The Manage > Settings option in the dockbar is different from the Settings option in the control panel. The Manage > Settings option is for specifying virtual host information, setting up a staging environment, and so on.
We’ll begin our discussion of portal server settings with the authentication setting.
5.4.1. Setting the authentication mechanism
The Liferay Portal server authentication setting defines the authentication mechanism used by the portal server, as shown in figure 5.34. This figure shows the authentication settings that you can use to authenticate users with the Liferay Portal server. You can specify whether users authenticate using an email address or userid, whether people can sign up with the portal or retrieve their password, and so on. You can also choose an appropriate authentication provider like LDAP, CAS, OpenSSO, and so on.
Figure 5.34. Authentication settings allow you to set the authentication mechanism used to authenticate users with the portal server. You can choose LDAP, OpenSSO, or any other appropriate authentication provider supported by Liferay Portal.
Figure 5.35 shows how Liferay Portal makes use of OpenSSO to implement single sign-on functionality so that the In-Demand Book Apps and Book Portal can be accessed without requiring users to re-authenticate with the In-Demand Book Apps application.
Figure 5.35. OpenSSO authenticates the user against the User Repository, and if the authentication is successful, it allows access to the Book Portal and In-Demand Book Apps. The User Repository contains user credentials, and it’s in sync with the user information stored in the Liferay Portal database.
OpenSSO authenticates a user against its User Repository, and on successful login it allows the user to access the Book Portal and In-Demand Book Apps application. A User Repository contains user credentials in addition to other information about the users.
You can create a user in the User Repository either by manually creating users using the OpenSSO user interface or by using an LDAP service to authenticate users. When using OpenSSO with Liferay Portal, if you create a user in the User Repository, the user’s information is persisted in Liferay Portal after authentication, if it doesn’t already exist.
Note
The Liferay Portal wiki (http://www.liferay.com/community/wiki) provides information on how to integrate Liferay Portal with OpenSSO and other SSO products. Integrating OpenSSO with Liferay Portal is accomplished in a few simple steps, which include dropping an OpenSSO WAR file in Liferay Portal and performing configuration in Liferay Portal.
Now let’s look at how you can associate the default user role of BookUser with registered users of Book Portal.
5.4.2. Specifying the default user associations
Liferay Portal, by default, assigns User and PowerUser roles to all users who register with the portal. In Book Portal, the registered users should get the default role of BookUser.
To assign the default role of BookUser to registered users, select the Users option from the list of configuration options displayed on the Settings page, as shown in figure 5.36. Go to the Default User Associations configuration option, and specify BookUser as the default role of the user.
Figure 5.36. The BookUser role is specified as the default role for users. You can associate multiple default roles with a registered user by specifying each role on a separate line.
This completes our discussion of how to develop a portal using Liferay Portal server’s built-in portlets and the custom Book Catalog portlet.
One of the Book Portal requirements is to allow administrators to easily change the look and feel of the web portal, and also the layout of portal pages. This requirement is typical in web portal development projects. Most portal servers provide some mechanism to simplify the creation of new layouts and portal themes. In the next section, we’ll look at how Liferay Portal lets you do this with the help of the Liferay Plugins SDK.
5.5. Developing with the Liferay Plugins SDK
The Liferay Plugins SDK (software development kit) is a Liferay Portal–specific SDK that provides a development environment for themes, layouts, and portlets. In this section we’ll discuss how to develop themes and layouts using the Liferay Plugins SDK.
You can download the Liferay Plugins SDK from the Additional Files page of the Liferay Portal website (http://www.liferay.com/downloads/liferay-portal/additional-files) and extract the zip file to a location in your local filesystem. Because we’re using Liferay Portal 6.0.5 Community Edition, download Liferay Plugins SDK CE GA3 (which corresponds to Liferay Portal 6.0.5) under the Files for Developers section of the web page.
Note
Every release of Liferay Portal server has a corresponding Plugins SDK, specific to that release. It’s recommended that you use the Plugins SDK specific to the Liferay Portal release for which you’re creating your custom portlets, layouts, and themes. For instance, if you’re using Liferay Portal Server 6.0.5, you should use Plugins SDK 6.0.5.
The directories in the Plugins SDK that are important for developing layouts and themes include the following:
- themes— The themes folder contains custom themes. It provides scripts to create your own custom theme folder structure, to create a WAR file for the theme, and to hot deploy it on the portal server.
- layouttpl— The layout template folder contains the custom page layout templates. It provides scripts to create your own custom layout folder structure, to create a WAR file for the layout, and to hot deploy it on the portal server.
Before you begin creating custom themes and layouts, you must configure the Plugins SDK to work with your Liferay Portal installation.
5.5.1. Configuring the Plugins SDK
It’s important to configure the Plugins SDK because it works in the context of the Liferay Portal server you’re using.
You configure the Plugins SDK by creating a properties file that has a name following this convention:
build.<user-id>.properties
In this name, <user-id> is the userid with which you’re logged into your computer. For instance, if you log in to your laptop with the userid of peters, your properties file should have the name build.peters.properties.
You create this properties file in the home directory of your Plugins SDK installation, as shown in figure 5.37. This figure shows the Plugins SDK directory structure for Liferay Portal 6.x. The portlets directory is used when you want to create plugin portlets for Liferay Portal. The build.asarin .properties file is a custom properties file that overrides the properties defined in the build.properties file. Because Plugins SDK works in combination with the Liferay Portal server, the properties that you’ll usually override in the custom properties file are those that identify directories of the Liferay Portal installation.
Figure 5.37. The Plugins SDK directory structure. The build.asarin.properties file represents a custom properties file that overrides the configuration in the build.properties file.
Once you’ve created your custom properties file, you can define the following properties in it:
app.server.dir=C:\liferay-portal-6.0.5\tomcat-6.0.26 app.server.lib.portal.dir=C:\liferay-portal-6.0.5\tomcat-6.0.26\webapps\ROOT\WEB-INF\lib auto.deploy.dir=C:\liferay-portal-6.0.5\deploy app.server.portal.dir=C:\liferay-portal-6.0.5\
The preceding properties file is specific to Windows. If you’re using a Linux or Mac OS X system, your properties file should look something like this:
app.server.dir=/liferay-portal-6.0.5/tomcat-6.0.26 app.server.lib.portal.dir=/liferay-portal-6.0.5/tomcat-
Table 5.1 describes the properties defined in the preceding code.
Table 5.1. Properties defined in the custom properties file
|
Property |
Description |
|---|---|
| app.server.dir | The installation directory of the Liferay Portal server. If you’re using a Liferay-Tomcat bundle, this property refers to the Tomcat installation directory. |
| app.server.lib.portal.dir | The location of the libraries used by Liferay Portal server. If you’re using a Liferay-Tomcat bundle, this property refers to the ${app.server.dir}/ROOT/WEB-INF/lib directory. |
| auto.deploy.dir | The hot deploy directory for Liferay Portal. This is the deploy directory of Liferay Portal, as mentioned in chapter 1. |
| app.server.portal.dir | The web application directory of the Liferay Portal installation. If you’re using a Liferay-Tomcat bundle, this property refers to the ${app.server.dir}/ROOT directory. |
To create themes and layouts using the Plugins SDK, you also need to install an Ant build tool and add its bin directory to the PATH variable, as shown here:
set ANT_HOME=C:apache-ant-1.7.1 set PATH=%PATH%;%ANT_HOME%in
If you’re using a Linux or Mac OS X system, export the $PATH as shown here:
export ANT_HOME=/apache-ant-1.7.1 export PATH=$PATH:$ANT_HOME/bin
Now that you’ve configured the Plugins SDK, you’re ready to create a theme for Book Portal.
5.5.2. Developing portal themes
Portal themes let you customize the look and feel of a portal, and every portal server provides a mechanism to allow portal developers to create custom themes. For instance, Liferay Portal provides the Plugins SDK, and Jetspeed provides a similar directory structure that you can use to create custom themes. The portlet specification doesn’t define a standard way to develop portal themes, so any themes you develop will be portal server–specific.
In this section, we’ll look at
- How to change the background color of the portal page in Liferay Portal
- How to change the default breadcrumbs image in Liferay Portal
- How to add JavaScript files as part of the portal theme so that there’s a single copy of the JavaScript file included in a portal page
We’ll also look at how to deploy a theme and set it for a portal. In this section, your customized portal page will end up looking like what you see in figure 5.38.
Figure 5.38. A Book Portal page that uses a custom theme. The background color is grey, the company logo is no longer the default Liferay Portal logo, and the breadcrumbs image looks like an arrow and not like an angle bracket (>) character.
To modify the company logo, all you need to do is upload a new logo using the control panel. Earlier in this chapter, figure 5.4 showed where you could upload a logo for the organization when it was created in Liferay Portal.
Code Reference
The Book Portal theme described in this section is available in the ch5_book-portal-theme.zip file in the book’s source code. Extracting the contents of the zip file creates a book-portal-theme folder. Copy the book-portal-theme folder into the themes folder of your Liferay Plugins SDK folder, and execute the ant deploy command from the book-portal-theme folder to deploy the theme in your Liferay Portal server.
The default Liferay Portal themes are located in the classic folder of the Liferay Portal installation:
${app.server.dir}webappsROOThtml hemesclassic
Figure 5.39 shows the directory structure of this classic directory. This figure shows that the classic folder contains five subdirectories: _diffs, css, images, js, and templates. The _diffs directory mirrors the structure of the classic folder and overrides theme files. The _diffs directory contains only the folders and files that need to be overridden. For instance, if you want to override the CSS elements defined in the custom.css file in the css folder, you should first create a css folder in the _diffs directory, and then create a custom.css file inside it.
Figure 5.39. Subdirectories of the classic folder, which contains the default Liferay Portal themes
Now that you have an understanding of Liferay Portal themes, let’s look at how the custom theme in the ch5_book-portal-theme.zip file was created for Book Portal. If you copied the book-portal-theme folder to the themes directory of Liferay Plugins SDK, then remove the book-portal-theme folder.
To create themes for Liferay Portal server, go to the themes directory in the Plugins SDK, and issue the following command:
create book-portal "Book Portal Theme"
If you’re using a Linux or Mac OS X system, to execute the create.sh shell script located in themes folder, you first need to execute the chmod command, as shown here:
chmod +x create.sh
Now, execute create.sh shell script from themes folder, as shown here:
./create.sh book-portal "Book Portal Theme"
The create command creates a book-portal-theme project for the new theme with the title Book Portal Theme. Figure 5.40 shows the book-portal-theme project’s directory structure.
Figure 5.40. Liferay Portal’s theme directory structure. The _diffs directory contains the custom CSS, images, and JavaScript files for the custom theme.
The docroot directory of the book-portal-theme project contains _diffs and WEB-INF directories. The _diffs subdirectory of docroot is where you’ll put your CSS and image files.
Initially all the directories are empty, except the WEB-INF directory, which contains the liferay-plugin-package.properties file, which contains theme information that can be changed, such as name, author, and so on.
You can add custom theme files in the _diffs directory to create a theme for Book Portal. The _diffs directory of the book-portal-theme project must be a mirror image of the classic directory of the Liferay Portal installation, which contains the default Liferay Portal themes.
Let’s now look at how you can go about changing the default background color of portal pages and change the breadcrumbs image.
Changing the Background Color of a Portal Page
Let’s say the custom theme of the Book Portal changes the background color of the pages to grey. The custom.css file in the css subdirectory of the classic folder contains the CSS element that defines the background color of a portal page, as shown here:
body {
background: #EEF0F2;
font-size: 11px;
}
You need to change the value of background attribute to #CCCCCC, as shown here:
body {
background: #CCCCCC;
font-size: 11px;
}
To change the background color, you first need to create a css subfolder in the _diffs directory of the book-portal-theme project. That’s because you need to mirror the folder structure of the classic folder that contains the default Liferay Portal themes.
Create a css folder inside the _diffs directory of the book-portal-theme project, and copy the custom.css file from ${app.server.dir}webappsROOThtml hemesclassiccss to book-portal-theme\_diffscss. You copy the file because you only want to change the body element of custom.css and keep the other CSS elements. After you’ve copied the file, change the body CSS element as previously described.
Changing the Default Breadcrumbs Image
The default breadcrumbs image used in Liferay Portal is specified in the custom_common.css file (inside the css directory of the classics folder). To change the image, copy the custom_common.css file to the _diffs directory of your custom theme folder, and change the url element of the following CSS class to point to your custom breadcrumbs image:
.site-breadcrumbs li span {
background: url(../images/common/breadcrumbs.png) no-repeat 100% 50%;
display: block;
padding: 0.5em 15px 0.5em 0;
}
In the case of the custom Book Portal theme, the new breadcrumbs image represents a right arrow and is located in the _diffs/images directory of your theme project, with the name my_breadcrumbs.png. You need to change the url element of the preceding CSS class to reflect the new breadcrumbs image, as shown here:
.site-breadcrumbs li span {
background: url(../images/common/
my_breadcrumbs.png) no-repeat 100% 50%;
display: block;
padding: 0.5em 15px 0.5em 0;
}
Now you can create an images directory inside the _diffs directory of your theme project, and copy the my_breadcrumbs.png file.
The last, optional, step in creating the theme is to provide a thumbnail image for the theme. The image is displayed, along with the name of the theme, on the theme-selection Liferay Portal page.
Note
The name of the theme’s thumbnail image must be thumbnail.png and it must be located in the images directory, and not one of its subdirectories.
Adding Javascript Files as Part of the Portal Theme
To add JavaScript files as part of the portal theme in Liferay, you need to do the following:
1. Create a js subfolder in the _diffs directory of the book-portal-theme project. Again, this is because you need to mirror the folder structure of the classic folder that contains the default Liferay Portal themes.
2. Add your custom JavaScript files to the js folder. Let’s say you want to use jQuery in your portlets and you want only a single copy of jquery-1.5.2.min.js in your portal page. To do so, download jquery-1.5.2.min.js (http://code.jquery.com/jquery-1.5.2.min.js) and copy it to the js subfolder of _diffs.
3. Create a templates subfolder in the _diffs directory of the book-portal-theme project, and copy the portal_normal.vm file from ${app.server.dir}webapps ROOThtml hemesclassic emplates to book-portal-theme\_diffs emplates. You copy the file because portal_normal.vm defines the overall structure of the portal page and specifies the JavaScript files that are included in the portal page. After you’ve copied the file, add a <script> element to the <head> section, as shown here:
<head>
<title>$the_title - $company_name</title>
<script type="text/javascript"
src="$javascript_folder/jquery-1.5.2.min.js"></script>
$theme.include($top_head_include)
</head>
In the preceding code, the <script> element adds the jquery-1.5.2.min.js JavaScript file to the portal page. The $javascript_folder variable refers to the directory containing the JavaScript files.
If the JavaScript files that you want to add to your portal page are hosted externally, you don’t need to create the js subfolder in the _diffs directory. You only need to change the portal_normal.vm file to refer to the externally hosted JavaScript files. For instance, you could use the following <script> element in portal_normal.vm to refer to the jquery-1.5.2.min.js file from Google CDN:
<script type="text/javascript"
src="http://ajax.googleapis.com/ajax/libs/
jquery/1.5.2/jquery.min.js">
</script>
Deploying and Setting a Portal Theme
Now you’re ready to deploy your custom theme using the following command:
ant deploy
When you issue the ant deploy command from within the themes folder of the Plugins SDK, it builds all the custom themes projects you’ve created and copies the generated WAR files to the hot deploy directory of your Liferay Portal installation. If you execute the ant deploy command from a particular folder inside the themes folder, only the theme represented by that folder is deployed.
The deployed theme can be viewed: log in as the Book Portal administrator, select the Manage > Page option from the dock-bar, and select the Look and Feel tab. If the theme was successfully deployed, you’ll see the newly added theme, as shown in figure 5.41.
Figure 5.41. The custom Book Portal theme is displayed along with other themes.
To use the Book Portal theme, select the Manage > Page option from the dockbar. You’ll see the Look and Feel tab for the entire MySamplePortal, Inc portal and for individual pages, as shown in figure 5.42.
Figure 5.42. The Look and Feel tab allows you to change the theme for the portal or for an individual portal page.
Select the Look and Feel tab to view available themes in the portal, and select Book Portal Theme to modify the look and feel of the portal. (Figure 5.42 shows that the Look and Feel tab is also displayed for individual portal pages, which means you can set the theme of an individual portal page.)
Next, we’ll look at how you can change the layout of your portlets on a portal page by creating a custom layout template.
5.5.3. Developing page layout templates
Portals use layout templates to define the layout of a portal page. Portal servers come with their own predefined layout templates, but they also allow you to create custom layouts. Like themes, layouts are portal-specific and can’t be reused across different portal servers.
In this section, you’ll see how to create a custom layout for the Book Portal using the Liferay Plugins SDK. The custom layout splits the horizontal space on a page into 80/20 size, where the left side gets 80 percent of the horizontal space and the right side gets 20 percent.
Code Reference
The two-column layout described in this section is available in the ch5_2-column-layouttpl.zip file of the source code that accompanies this book. Extracting the contents of the zip file creates a 2-column-layouttpl folder. Copy this 2-column-layouttpl folder into the layouttpl folder of your Liferay Plugins SDK folder. Then, execute the ant deploy command from the 2-column-layouttpl folder to deploy the layout in your Liferay Portal server.
Let’s now look at how to create the layout defined in the ch5_2-column-layouttpl.zip file. If you copied the 2-column-layouttpl folder to the layouttpl directory of Liferay Plugins SDK, remove the 2-column-layouttpl folder.
To create a layout template, go to the layouttpl folder of the Plugins SDK, and execute the following command:
create 2-column "2 columns (80/20)"
The create command creates a layout template project named 2-column-layouttpl and titled “2 columns (80/20)”. Figure 5.43 shows the contents of the docroot directory of the 2-column-layouttpl project.
Figure 5.43. Contents of the 2-column-layouttpl project’s docroot directory
The following files are shown in figure 5.43:
- 2_column.png—The image that’s shown when Liferay Portal displays the list of available layouts. You can replace this default image if you want to.
- 2_column.tpl—The layout template file, which contains the layout of the template.
- 2_column.wap.tpl—The layout template file for WAP.
Note
Portal servers provide support for mobile devices, which is why there’s a WAP version of the layout template.
The next step is to write the 80/20 layout logic in the 2_column.tpl file. The content of the 2_column.tpl file that creates a 80/20 layout template is as follows:
<div class="columns-3" id="content-wrapper">
<table class="portlet-layout">
<tr>
<td class="aui-w80 portlet-column portlet-column-first" id="column-1">
$processor.processColumn("column-1",
"portlet-column-content portlet-column-content-first")
</td>
<td class="aui-w20 portlet-column portlet-column-last" id="column-2">
$processor.processColumn("column-2","portlet-column-content
portlet-column-content-last")
</td>
</tr>
</table>
</div>
The layout template contains HTML and processing instructions. Notice the use of the aui-w20 and aui-w80 classes to represent the space taken up by each <td> tag. The id and class elements must be used as shown in the preceding template code. The portlet-column-first CSS class is represents the first column in the layout, and the portlet-column-last CSS class represents the last column.
Similarly, you could create a three-column 20/60/20 template as shown here:
<div class="columns-3" id="content-wrapper">
<table class="portlet-layout">
<tr>
<td class="aui-w20 portlet-column portlet-column-first" id="column-1">
$processor.processColumn("column-1",
"portlet-column-content portlet-column-content-first")
</td>
<td class="aui-w60 portlet-column portlet-column-first" id="column-2">
$processor.processColumn("column-2", "portlet-column-content")
</td>
<td class="aui-w20 portlet-column portlet-column-last" id="column-3">
$processor.processColumn("column-3","portlet-column-content
portlet-column-content-last")
</td>
</tr>
</table>
</div>
You can see that creating a new layout template in Liferay Portal is very intuitive.
You’re now ready to deploy your layout template on Liferay Portal. To do so, execute the following command from the layouttpl directory:
ant deploy
This will generate a WAR file for the layout template project and copy it to the hot deploy folder of Liferay Portal.
If the layout is successfully deployed, you can verify that the template is available by going to dockbar and selecting Manage > Page Layout. This will display the list of all available layout templates, as shown in figure 5.44.
Figure 5.44. The newly created “2 columns (80/20)” layout template is available in the list of layout templates.
Selecting a layout template from the list of available templates changes the layout of the current portal page, and the portlets are rearranged on the page.
5.6. Summary
In this chapter, you saw how the choice of a portal server can impact the time and effort required to develop and deploy a web portal. The key to quickly developing a web portal is having a good understanding of the target portal server’s features. You saw (in the Book Catalog portlet) that you can use the features offered by built-in portlets to build your custom portlets, and in some scenarios you can simply use built-in portlets to address business requirements.
In the next chapter, we’ll look at the portlet tag library, which can help you perform some basic tasks in the JSP page itself, like creating portlet URLs.