• Document Library
• Document Library Display

You will now study the use of these applications, starting with Document Library. The Document Library application allows you to organize and manage your documents. You use it to create a tree-structured hierarchy where the documents are published and stored. Thus, you can organize the document storage logically so that users can easily locate the files.

To add the Document Library application on our ISI portal page, follow the steps listed here:
 

1. Log in as Administrator on the ISI portal.
2. Create a new page called Document Library under our predefined communities, or at any other location you’d like.
3. Select the Add Application menu.
4. Select and add the Document Library application from the CMS category.
 

Now you’re ready to create a folder structure for document storage. You’ll create a hierarchy of folders for storing documents created by our analysts and categorize the documents into two types:

• Fundamental Analysis Documents
• Technical Analysis Documents

These classification names derive from the type of analysis that the documents contain.
 

For each category of documents, you’ll further classify the documents based on who the author is. For simplicity, call these authors Analyst1, Analyst2, and so on. So you’ll create a folder for each analyst and store the analysts’ documents in their respective folders. Begin by creating the folder hierarchy.

To create a folder in the Document Library application, follow these steps:
 

1. Navigate to the Document Library page that you created in the previous section.
2. Click the Add Folder button in the Document Library application.
3. Take action on the following fields in the displayed dialog (see Figure 9-2):
a. Name: Enter Fundamental.
b. Description: Enter This folder contains analysis reports created by prominent fundamental analysts.
c. Permissions: Leave these settings at their default values.
4. Click the Save button to save your changes. You will automatically return to the main application screen after your changes have been saved.
5. You will now add another folder called Technical to organize the technical analysis documents produced by the portal’s leading technical analysts. Follow steps 2, 3, and 4 to create the Technical folder.

When you return to the main application screen, you will notice that the newly added Fundamental and Technical folders are listed on the main page

First, you’ll add subfolders under the Fundamental folder. Follow these steps to do so:
 

1. Click the Fundamental link in the folders list displayed on the main application screen.
2. Click the Add Subfolder button on the displayed screen.

3. Take action on the following fields in the displayed dialog:

a. Name: Enter Analyst1.
b. Description: Enter The documents in this subfolder are provided by Analyst1.
c. Permissions: Leave these settings at their default values.

4. Click the Save button to save your changes.

5. Add two more subfolders under the Fundamental folder by following steps 2 through 4 again, but call these subfolders Analyst2 and Analyst3 and update the description text accordingly.
6. Save your edits.

Note that the three subfolders you created appear under the Fundamental folder. Also, notice the folder-navigation links that appear above the Search edit box. Looking at these links, you can easily see the current folder’s position in the hierarchy. You can jump to any folder by clicking its name in the series of navigation links.

Now follow the preceding steps to create subfolders called Analyst1, Analyst2, and Analyst3 under the Technical main folder. Next, you’ll learn to store documents in the folder hierarchy that you have created so far.

To add documents to our document library on the portal, follow the steps listed here:
 

1. Navigate to the Fundamental/Analyst1 subfolder.
2. Click the Add Document button.

3. Click the Browse link to select the documents.
4. Select the desired analysis reports for uploading (you can select multiple documents if desired).

5. Click the Upload Files link to upload the files to the server.

You can use either the new uploader or the classic uploader to upload files to the server. In the previous section, you used the new uploader by clicking the Browse (you can select multiple files) link. In this section, you’ll use the classic uploader by clicking the Use the classic uploader link on the upload page (see Figure 9-6).

Perform the following actions to complete the classic uploader entry screen:
 

1. Type the name of the file to be uploaded in the File edit box. If you are not sure of the file’s full path, use the Browse button to locate the file and add its name to the edit box.
2. Enter the desired title for the file in the Title edit box.
3. Enter the desired description for the file in the Description edit box.
4. Enter the tags in the corresponding edit box. You can create new tags here by typing the index word and clicking the Add Tags button. Alternatively, you can tag the current file by selecting from the predefined tags that pop up when you click the Select Tags button.
5. Set the user permissions by clicking the Configure link.
6. Finally, after you complete all your inputs, click the Save button to upload the file to the server.

If you find a document useful, you might want to create a shortcut to it so you can locate it more easily the next time. You obviously must have at least a read permission on the document to create a shortcut to it. Once you create the shortcut, you can grant permissions on it to other users so that they can also locate the document easily.

To create a shortcut to a document, follow the steps listed here:

1. On the screen that lists the documents, locate and click the Add Shortcut button.
2. On the displayed screen, click the Select button to the right of the Community label.

3. Select the desired community from the list. After you do this, the pop-up window closes automatically.
4. Click the Select button to the right of the Document label.
5. Navigate to the desired document and select it. Again, the pop-up window closes automatically.
6. Assign the desired permissions for the shortcut (you can use the defaults, in this case).
7. Click the Save button. The newly created shortcut will appear in the list of documents.

Now that you’ve added a few documents and created a few shortcuts to these documents, we will look at what actions you can perform on them. You can perform these actions on each document displayed in the document list:

• View
• Edit
• Permissions
• Delete

You see the actions menu when you click the Actions button in the document list.

Selecting the View action displays important information about the document or its shortcut; the nature of the information varies depending on which you choose.

The document library screen displays the document’s name, version, size, and number of downloads. The latter statistic helps you judge the document’s popularity. The screen also provides a Download link for downloading the document to your desktop. When you download the document, you can convert it to any of the formats displayed in the Convert To list.

The screen displays the document’s name, version, size, and number of downloads. The latter statistic helps you judge the document’s popularity. The screen also provides a Download link for downloading the document to your desktop. When you download the document, you can convert it to any of the formats displayed in the Convert To list.

You can also rate the current document by using the same five-star system you’ve seen in Liferay’s other applications. By clicking the desired number of stars at the bottom of the screen, you can give the document a rating between 1 and 5 . Your rating immediately affects the adjacent average rating, which is shown with the number of votes cast so far.

In addition to rating the document, you can add your comments to it. Click the Comments tab at the bottom of the screen to see the Post Reply link .Click this link to open an edit box for the comment text. Enter your comment in this edit box and click the Reply button. Your comment will post immediately and appear in the Threaded Replies section of the document-view screen. When different users post their replies on a document, the application arranges all such replies hierarchically under Threaded Replies.

Finally, the Version History tab at the bottom of the document-view screen allows you to view the various versions of the current document available on the server.

The Edit action allows you to edit certain information about the document

On the edit screen, you can set the folder where the document is stored, set the document’s title and description, tag the document with your own index words, rate the document, and add comments to the document. In the case of shortcuts, the Edit action allows you to change the currently assigned community to whom access is granted.

Most important, if you modify the document’s contents, you can upload the document again through this screen. When you do so, the version number displayed under the document’s name increments to indicate that the document has been updated.

This option allows you to set permissions on the current document or shortcut for various user and community roles. The permissions that you can grant or deny under Regular or Community roles are:
 

• View: Allows the user to view the document or shortcut
• Delete: Allows the user to delete the document or shortcut
• Permissions: Allows the user to set permissions for other users
• Update: Allows the user to update the properties of the document or shortcut
• Add Discussion: Allows the user to post replies to the document

For a Guest user, you can assign only the View, Delete, and Permissions permissions—not Update or Add Discussion.

This action, as the name suggests, allows you to delete the selected document or shortcut after you confirm to do so.

Just as you can perform various actions on a document or its shortcut, you can perform certain actions on the folders in which you have arranged your documents. To perform an action on a folder, go to the folder-display view and click the Actions button to the right of the folder’s name. You will see three action menus: Edit, Permissions, and Delete

When you perform the Edit action on a folder, you can set a new parent folder or remove an existing one. You can also set the folder’s name and description

As in the earlier cases, you can use the Permissions action to grant or deny permissions to users having Regular or Community roles. Under Regular or Community roles, you can grant or deny the following permissions:

• View: Allows the user to view the folder
• Delete: Allows the user to delete the folder
• Permissions: Allows the user to set permissions for other users
• Update: Allows the user to update the folder’s properties
• Add Shortcut: Allows the user to create a shortcut in the current folder
• Add Subfolder: Allows the user to create a subfolder under the current folder
• Add Document: Allows the user to add a document in the current folder
 

For a Guest user, you can assign only View, Delete, and Permissions.

The Delete action, as the name suggests, allows you to delete the selected folder after you confirm you want to do so.

Over time, your document-library database will accumulate a large amount of files, so you’ll want the ability to search for a certain file. The Document Library application provides a builtin facility for searching the database.

On the application’s main screen, you will find a Search edit box. To search for a document, enter the desired search text in this edit box and click the Search File Entries button next to it. The application will search the entire database and display the list of file names that match the specified criterion. The application performs the search on the document’s file name, description, and contents.

The search results display the folder name where the document is stored. Clicking any document name opens the document for viewing or allows you to download the document to your machine if an appropriate viewer is not registered for that document type.

So far, you’ve seen how to create a folder hierarchy and add documents to it, as well as search the document-library database for files matching a specific search term. But the Document Library application’s search feature doesn’t locate files based on the users who uploaded the files. What if you want to locate only files that you yourself have uploaded? Locating your own documents in the database could prove to be a nontrivial effort. To address this, the Document Library application provides a feature that lets you easily list your documents and recently added documents.

On the application’s main screen, you will find the tab called My Documents. If you click this tab, you’ll see a list of all documents that you’ve added to the document library

From this screen, you can open any document for viewing or downloading. You can also perform various actions on any document, as discussed in the preceding “Performing Actions on Documents” section.

Just as you can display your own documents, you can view recently added documents by selecting the Recent Documents tab on the main application screen.

Now we will look at the configuration options that you can set at the application level. When you click the Configuration button on the application’s main screen, you will see the typical four tabbed options:
 

• Setup
• Permissions
• Export/Import
• Sharing
 

We will now discuss each of these options in detail.

Under the Setup tab, you will find several configuration options. There are four secondtier tabs:
 

• Display Style
• Folders Listing
• Documents Listing
• Ratings

Under the Display Style option, you can select one of two views: the Classic view or the Tree view.

The Folders Listing tab provides several configuration options for folder display):
 

• Show Breadcrumbs: Selecting this option displays the list of folder-navigation links.
• Show Search: This option enables users to search folders in the database.
• Show Subfolders: This option enables the display of subfolders. When this check box is marked, the application will display subfolders in a tree hierarchy .To view a subfolder, you click the small arrow to the left of the folder name.
• Folders per Page: This option allows you to select the number of folders to display in the folder list. The default value is 20.
• Show Columns: This option allows you to select the columns to display in the list. The Folder option displays a column containing the name of the folder. The # of Folders option displays a column containing the number of subfolders within the specified folder. The # of Documents option displays a column containing the number of documents within the specified folder. The Action option displays the Actions button in each row of the folder list.

The Documents Listing tab lets you set various options to determine how documents will be listed onscreen

• Show Search: This option allows you to enable or disable the display of the search option on the document-list screen.
• Documents per Page: This sets the number of documents to be displayed per page. The default value is 20.
• Show Columns: This option allows you to select from five columns for display. The Document column displays the document name, the Size column displays the document’s size, the Downloads column displays the number of downloads so far, the Locked column indicates if the document is currently locked for editing, and the Action column displays the Actions button in the row.

The Ratings tab allows or prevents the user from rating the document

The Permissions option allows you to set application-level permissions for your users. As usual, you can set permissions for Regular and Community roles. The following permissions can be granted or denied:
 

• View: Denying this permission makes the application itself inaccessible to the user.
• Configuration: Granting this permission allows the user to adjust the configuration settings on the application.
• Add Folder: Granting this permission allows the user to add a new folder to the database.

For the Guest role, you can grant or deny only the View and Configuration permissions.

As your document database grows, you need to archive it to a safe place periodically. The Export option on the application’s configuration screen allows you to do so. When you export, the application archives the data related to the current community served by the current application instance. If the portal administrator were to use this export option for backing up the data, she would need to do so for each community.

Alternatively, a system administrator can be made responsible for the entire data backup. Obviously, the administrator would need to know the underlying storage used by the current Liferay installation for maintaining the document repository. The data that you export to backup storage can be restored via the Import facility.

As the screen in Figure 9-22 shows, you can select various fields for backup. By default, all folders and its documents are backed up. Along with this, you can save shortcuts, ranks, comments, ratings, tags, and so on. Simply mark the check box in front of each field that you wish to back up. Clicking the Export button exports the selected fields to the file specified in the filename edit box at the top of the screen.

When you select the Import tab, you will see the screen shown in Figure 9-23.

 

On this screen, you first need to select the file from which you wish to import data. Do this by clicking the Browse button and navigating to the desired file name. After selecting the data file, select the various fields for import:
 

• Setup: This option imports the previously configured setup options.

• Archived Setups: This option results in the import of archived setups, if the backup database contains any.

• User Preferences: This option imports the user preferences.

• Delete portlet data before importing: This option deletes all the existing data before importing the new data from the archived file. Note that other applications on the portal might reference some of the documents in your database, so deleting all the data might result in orphan links in those applications.

• Data: You have to decide on two types of strategies while importing data; I’ll discuss these shortly.

• Permissions: By default, all permissions related to organizations, user groups, roles, and communities would be imported. You can optionally choose to import the permissions assigned to users.

Now let’s return to the two types of data-import strategies I just mentioned. You must decide on the data strategy and the user ID strategy. With the data strategy, you have two options: you can either copy the data as new data, or mirror the data instead.

If you choose the Copy as New option, the data is imported as a new item. So the first time the data is imported, a new entry will be created for every archived entry. The next time the data is imported from the same file, an additional entry would be created for the same document. So you’d have multiple copies of the same document when you import the file multiple times.

Now suppose you mirror the data instead. The first time you import the data, a new entry is added for each imported document and a link to the original document is created. The next time you import data from a file, the newly added entry is updated and no additional entries for the same document are created.

You also need to choose a user ID strategy for importing data. Because the user who originally created a document may or may not exist in the new instance of the portal, you need to choose one of these options:
 

• If a user ID does not exist in the new instance, then use your ID in place of the missing ID.
• Regardless of whether the user ID exists in the new system, always use your ID while importing data.
 

After selecting the desired fields and strategies, click the Import button to import the data to your database.

The Sharing option produces the code that you can embed in other web sites to make this application available elsewhere. It also allows you to share the application on Facebook.

All of this chapter’s preceding content involved creating a document library using Liferay’s Document Library application. Liferay also provides an application that allows you to display the contents of this library. This application is known as Document Library Display.

To install the Document Library Display application, follow the steps listed here:

1. Log on to the portal with Administrator rights.
2. Navigate to the Document Library page you created in the “Adding the Application” section toward the beginning of the chapter.
3. Select the Add Application menu option.
4. Select the Document Library Display application under the CMS category.
5. Add the application to the page by clicking the Add button.

Using the Document Library Display application is easy. The application opens with a screen displaying the first level of folders in the document library (see Figure 9-25).

The folder list displays the folder name, the number of subfolders within it, and the number of documents within the selected folder and associated subfolders. You can navigate to the subfolders by clicking the expansion arrows associated with the top-level folders. When you reach the lowest-level node, you’ll see the list of documents inside the selected node. You can click any document name to view or download the document.

The Document Library application works well for managing documents such as PDFs, text files, and so on. But images generally require special attention and special programs to render them. You cannot simply store the images alongside your text-based files. For this reason, Liferay has provided another application called Image Gallery that allows you to manage a database of images.

The Image Gallery application shares many features with the Document Library application because their functionality is more or less the same. They differ only in the type of data storage and in the way their contents are rendered to the user. Thus, we will focus mainly on the features that set Image Gallery apart from Document Library.

To install the Image Gallery application on our ISI portal, follow the steps listed here:
 

1. Log in as Administrator on the ISI portal.
2. Create a new page called Image Library under our predefined communities, or at any other location that you’d like.
3. Select the Add Application menu.
4. Select and add the Image Gallery application from the CMS category

If you look at the main screen of the Image Gallery application, you’ll see many similarities to the Document Library application. Just the way you organize your documents in a folder hierarchy, you will need to organize your images under logical folders on your site. The application shows three main tabs:
 

• Folders
• My Images
• Recent Images

The Folders tab, as in the Document Library application, allows you to create folders and subfolders. It allows you to add images to a folder and upload them to the server. The default file extensions for recognized images are .bmp, .gif, .jpeg, .jpg, .png, .tif, and .tiff. Most of the industry’s popular image viewers recognize these formats.

A typical image-view screen is shown in Figure 9-27.

 

On this screen, you can also search images against the text in the images’ description fields. Additionally, you might have noticed another button called View Slide Show. Clicking this button opens a new window and starts a slide show of all the images in the current folder (see Figure 9-28).

The slide-show viewer allows you to pause the show any time by clicking the Pause button. You can then navigate to the next or previous image by clicking the respective buttons. You can resume the slide show by clicking the Play button. Finally, you can set the speed of the slide show by selecting the duration value for each image (in seconds) from the dropdown list box.

The Image Gallery application’s configuration does vary from the configuration of the Document Library application. When you click the Configuration icon in the main application window, you will see the following three tabbed options:

• Permissions
• Export/Import
• Sharing
 

Notice the absence of the Setup option. The Image Gallery application does not provide any setup options. I won’t address the Sharing option here because it closely resembles its counterpart in the Document Library application. But we’ll review Permissions and Export/ Import.

As in the case of the Document Library application, the Permissions tab allows you to set user-level permissions for both Regular and Community roles. You can assign the following permissions:

• View: Allows the user to view the application
• Configuration: Allows the user to perform various configuration tasks
• Add Folder: Allows the user to add folders

The Add Folder permission cannot be granted to a Guest user.

The Export/Import tab allows you to export and import your image database. When you click this tab and select the Export second-tier tab.

Note that this screen has fewer fields for selection compared to the Document Library application. While selecting the images to be archived, you can specify a date range or select all the images. When you set a date range, only the images added to the database in the specified range would be added to the archive.

The second-tier Import tab, which resembles its counterpart in the Document Library application, allows you to select the fields to be imported.