The Documents and Media library stores files on the server using the same type of structure that you use to store files locally. It accepts files of any kind, can serve as a virtual shared drive, and can mount and browse external repositories. You can organize documents using customizable document types and metadata sets and display them with automatic document preview generation. Its companion app, the Media Gallery, displays selected content from the Documents and Media library. It can render image, audio, and video files.
As you create sites, you’ll probably want to share files on them. The Documents and Media library (Document Library) lets you upload and publish all kinds of files on your sites. Pictures, videos, spreadsheets, slide presentations, and more can be stored in and shared from the Document Library. Document Library instances can be scoped to a portal instance, site, or page, so you can work with files where they’re relevant.
Here, you’ll learn how to add files, display them, and collaborate on them. You’ll learn how to use both the Documents and Media Library and the Media Gallery. And lastly, you’ll learn how to collaborate on files from within several environments, including your browser and local desktop file system.
Figure 1: These documents are awesome.
Figure 2: This slideshow rules.
Figure 3: Viewing a file’s details is fun.
Adding Files to a Document Library
This article covers the following topics to help you get started adding files to your Document Library:
- Granting File Permissions and Roles: Determine who can add, view, and update files. Doing this before adding files ensures that only those you wish can access your Document Library.
- Adding Files: Add specific types of files and their associated metadata to your Document Library.
You should carefully manage who can add, view, and update files. You can store files of all kinds for various purposes. For example, you may have one set of files intended for only specific site members and another intended for everyone, including guests. You can use Roles and Permissions to control access to Document Library files. The Document Library’s folder permissions also help you organize files.
Follow these steps to create a Role for managing files in your site’s Documents and Media:
- Open the Menu () and navigate to Control Panel → Users → Roles.
- Select the Site Roles tab (or Organization Roles, for an Organization Role) and then click the Add button () to begin creating a role.
- Give your Role a name and a description, then click Save.
- Select your Role’s Define Permissions tab. In the Role’s permission definition screen, navigate to Site Administration → Content & Data → Documents and Media. In the General Permissions section, select Access in Site Administration and click Save.Figure 1: It’s often helpful to define a role for specific users to access Documents and Media from Site Administration.
- Assign this Role to the Users that should manage media. For more information on this and other topics related to Roles, see Roles and Permissions.
Follow these steps to add files to your site’s Document Library:
- Open the Menu (), click on your site’s name, and navigate to Content & Data → Documents and Media. The Documents and Media screen appears and displays the Documents and Media library’s Home (its root folder). As you add files and folders to the Document Library, they’re listed here.Figure 2: The Documents and Media’s *Home* folder starts empty.
- Click the Add icon () and select the type of document to add to the Document Library. You can add documents, folders, and shortcuts much like you would on a desktop file system. You can even configure access to an entirely different repository. The Add menu’s options are described below.Figure 3: The Add menu lets you upload and add all kinds of documents to the library.
- When you’re finished selecting the file to upload and filling out any document type fields that are necessary, click Publish.
File Upload: Upload a file to the Documents and Media library.
Folder: Create a new folder in the Documents and Media library’s file system.
Multiple Files Upload: Upload several files at once. You can apply a single description and document type to all the files. You can also categorize and tag the files, and assign them default permissions.
Repository: Add access to an external repository.
Shortcut: Create a shortcut to any document that you can view. You can set permissions on the shortcut to specify who can access the original document via the shortcut.
Any additional items in the Add menu are document types described by a unique metadata set. When you add a document belonging to a document type, a form appears that lets you pick the file to upload and enter the data defined by the document type’s metadata set.
You’ll need folders to organize all but the most limited set of files. Here, you’ll learn how to work with folders in a Document Library:
Follow these steps to add a folder:
- Open the Menu (), click on your site’s name, and navigate to Content & Data → Documents and Media for your site. The Documents and Media screen appears and displays the Documents and Media library’s Home (its root folder).
- Click the Add icon () and select Folder. The New Folder form appears.
- In the New Folder form, name and describe your folder. Then expand the Permissions section.
- In the Permissions section, set the folder’s permissions. The Viewable by menu lets you select who has View permission for the folder:
- Anyone (the Guest role; this is the default option)
- Site Members
- To finish creating the folder, click Save after making your selections in the Permissions section.
Upon creating the folder, it appears in your Document Library. Opening the folder’s Actions menu () presents several options for managing the folder. The following sections describe some of these options.
Figure 2: Your new folder appears in the Document Library.
After creating a folder, you can restrict what document types are allowed in it. You can also choose what workflow (if any) to use for approving files added to or edited in the folder.
Follow these steps to change a folder’s document type restrictions and workflow:
- Click the folder’s Actions menu () and select Edit.
- Expand the Document Type Restrictions and Workflow section. In this section, choose from the following options:
- Use Document Type Restrictions and Workflow of the Parent Folder (the parent folder)
- Define Specific Document Type Restrictions and Workflow for this Folder (the current folder)
- Default Workflow for this Folder (the current folder)
- Click Save when you’re finished.
Figure 3: You can set the document type restrictions and workflow to use for a folder’s files.
When creating a folder, you can set some of its permissions via the new folder form. Fine tuning a folder’s permissions, however, can only be done after creating the folder.
Follow these steps to fine tune a folder’s permissions:
- Click the folder’s Actions menu () and select Permissions. The Permissions window appears.
- In the Permissions window, set the permissions you want to use for this folder. The permissions listed below are available for each role.
- Click Save when you’re finished setting permissions.
Here are the permissions you can set:
Delete: Move the folder to the Recycle Bin.
Permissions: View and modify the folder’s permissions.
Add Subfolder: Create folders within the folder.
Add Shortcut: Create a shortcut (link) to any file in the folder that the role is authorized to view.
Update: Edit the folder’s attributes and/or move the folder under a new parent folder.
Add Document: Add a new file to the folder.
Subscribe: Receive email notifications when files are added to or modified in the folder. Note that you can specify the email sender and template from the Documents and Media’s Options () → Configuration menu.
View: View the folder.
Access: Access the folder’s contents.
Using the Documents and Media Management Bar
The Documents and Media Management Bar is where people who manage documents go to unwind after a long day at work. Just kidding. The Management Bar, as its name implies, contains tools for managing the files and folders in your Document Library. It appears above the files and folders in Documents and Media.
Figure 1: The Management Bar is a great place to hang out if you’re managing documents.
If you’ve added files or folders to your Document Library, then you’re already familiar with the Management Bar’s Add button (). The sections that follow describe the rest of the Management Bar.
Note: If a Document Library contains more items than it can display at once, you can use the navigation tool that appears at the bottom of the window to switch your view to another page or configure the page to display more items per page.
The View Types button is to the left of the Add button. It lets you choose how to display the Document Library’s items. The View Types button’s icon depends on the selected view type:
Cards (): Shows a card-like rendering of the item. If the item isn’t an image, a generic image for the item’s type is displayed. For files, each card also contains the file’s suffix (e.g., JPG, PNG, etc.), timestamp, name, and workflow status (e.g., Approved, Draft, etc.).
List (): Shows the same information as the Cards view type, in a list with small file renderings.
Table (): Shows the same information as the other view types, in a list with no file renderings. Also, the file information is in columns.
The items in all view types have an Actions menu (). These actions are also available in when viewing each item separately.
Figure 2: The Cards View type shows items in large card-like renderings.
To display an info panel with the current folder’s details, click the Information icon (). The info panel slides out from the right side of the screen and contains the folder’s name and number of items. It also has these buttons:
Subscribe (): Get notifications about files added to or modified in the folder.
Actions (): Lists actions you can perform on the current folder.
The Management Bar also contains tools that help you locate and arrange items in the Document Library. The most prominent of these tools is the Search bar, where you can find files by keywords.
To the left of the Search bar, the Sort button () arranges items in ascending or descending order.
You can also arrange items via the Filter and Order selector using these criteria:
All: Shows all of the current folder’s immediate subfolders and files (default).
Mine: Shows all the current user’s files (no matter their folder).
Document Type: Shows the files of the selected document type. Upon choosing this option, you must select the document type you want from a popup.
You can also select from the following criteria for ordering items:
- Modified Date (default)
- Create Date
The checkbox on the left-most side of the Management Bar selects all currently displayed items. Selecting multiple items lets you act on all of them at once. You can also select multiple items individually by using the checkboxes for each. When you select one or more items, the Management Bar changes to reflect the actions you can take on the selected items.
Figure 3: With items selected, the Management Bar changes.
Here are the actions you can take on the selected items:
- Download ()
- Move ()
- Edit Tags
- Move to Recycle Bin ()
The Actions button () contains all the actions displayed in the Management Bar, plus actions for file checkin and checkout. File checkout and checkin is explained in Checking out and Editing Files.
Viewing File Previews
File previews help users browse and find media efficiently. To view a preview of a file, click the file’s name in the Document Library. If the file is an image, the image appears. If an app is installed that can render a preview of the file type, a representative image of the file appears (e.g., the opening frame of a video file or a presentation’s first slide). If there are no such preview apps for the file, a generic image based on the file type appears.
Figure 1: File previews let you view and manage a file.
Whenever possible, Liferay DXP generates previews of documents added to the Document Library. Out of the box, Java-based APIs generate previews. The only tool available that is 100% Java and has a compatible license to be distributed with Liferay DXP is PDFBox. A separate thread generates a preview for PDFs when uploaded. This process may last only a few seconds for a small file. The larger the file, the longer it takes.
While PDFBox provides a default implementation of image generation for document previews and thumbnails, you must install and configure additional tools to harness the full power of document previews. These tools include:
- OpenOffice or LibreOffice: Using one of these in server mode lets you generate thumbnails and previews for supported file types (
.odp, etc.), view documents in your browser, and convert documents.
- ImageMagick (also requires Ghostscript): Enables faster and higher-quality previews and conversions.
- Xuggler: Enables audio and video previews, lets you play audio and video files in your browser, and extracts thumbnails from video files.
After installing these tools, you can configure them via portal properties in the Control Panel’s Server Administration screen, or in a
portal-ext.properties file. To learn how to use these tools, see Configuring Liferay DXP.
With these tools installed and configured, a customized viewer displays Documents and Media content, depending on the content type. For example, you can view a document with a customized viewer that lets you navigate through the document’s pages. You can also view and play multimedia documents (audio or video). If the browser supports HTML5, the viewer uses the browser’s native player. Otherwise it falls back to a Flash player.
You can also manage a file from its preview. The bar above the preview contains these buttons:
Info (): Open/close the file’s info panel. This panel contains more detailed information about the file. For more information on this, see The Info Panel.
Share: Share the file with other users. For more information, see Sharing Files.
Download: Download the file.
Actions (): Opens a menu that lets you perform these actions on the file:
- Edit: Modify the file’s name, description, document type, categorization, and related assets. You can even upload a new file to replace it. Note that modifying the file increments its version.
- Edit with Image Editor: Edit the image in the Image Editor. The Image Editor is explained in Editing Images.
- Checkout/Checkin: Checkout prevents others from editing the document while you are working on it. Other users can still view the current version of the document, if they have permission. You can check in the document when you’re done with it.
- Move: Relocate the file to a different parent folder.
- Permissions: Specify which actions each role can perform on the file.
- Move to Recycle Bin: Move the file from the Documents and Media library to the Recycle Bin.
Also note that the Options menu () at the top-right of the screen contains the same actions as the Actions menu.
The comments area (below the preview area) lets you comment on and subscribe to comments on the file.
As mentioned above, clicking the Info icon () opens the info panel. The top of the info panel displays the file’s name, version, and workflow status. There are two tabs in the info panel: Details, and Versions. Details is selected by default and shows the following:
Owner: The file’s owner.
Download: A button to download the file.
Latest Version URL: A URL to access the newest version of the file.
WebDAV URL: A WebDAV URL for accessing the file via a desktop.
Document Type: The file’s document type.
Extension: The file’s extension (e.g., JPG, PDF, etc.).
Size: The file’s size on disk.
Modified: The user that last modified the file, and when it was last modified.
Created: The user that created the file, and when it was created.
Ratings: The file’s average user rating.
Automatically Extracted Metadata: Any and all metadata automatically extracted from the file. When adding new documents or viewing existing documents, a process is triggered automatically that extracts the file’s metadata. The library used by this process is TIKA and it’s included out of the box. Depending on your file’s type and the metadata written with the file, you can find out all kinds of details. In the case of audio or video files, the media’s duration is displayed.
To instead view the file’s version history, select the Versions tab near the top of the info panel. The info panel then changes to list the different versions of the file and lets you view, download, remove, and revert to specific file versions. File version history actions are explained in Checking Out and Editing Files.
Editing and re-uploading images when you only need to apply simple edits is tedious. Docs & Media contains a simple built-in image editor for exactly this reason. To access the image editor, locate the image you want to edit. Click the Actions icon () and select Edit With Image Editor.
You can also access the image editor when selecting an image to insert in content (i.e., via an item selector). Anywhere an image is, you can edit it. For example, you can access the image editor via item selector preview windows in blog entries and web content articles. To do this, click the pencil icon () in the bottom-right corner of the preview window.
Figure 1: You can access the image editor through the Documents and Media repository.
Figure 2: You can also access the image editor through the item selector preview window.
If you edit and save the image via the Documents and Media repository, the file version is incremented a minor version (e.g., from version 1.0 to version 1.1). You can view the image’s version history (and previous versions) by clicking the image, clicking its Info button (), and then selecting the Versions tab. In contrast, if you edit and save an image via an item selector, a copy of the image is created and saved to the Document Library.
Liferay designed the image editor with quick editing in mind. It offers a minimal, user-friendly UI. The main toolbar consists of three buttons, each of which contains a subset of options:
Figure 3: The image editor’s UI is clear and to the point, offering only what you need.
- Rotate: Rotate the image to the left or right, in 90 degree increments.
- Resize: Resize the image. If the lock is closed, the aspect ratio is locked and changing width or height automatically adjusts the other dimension to maintain the aspect ratio. When the lock is opened, the width and height can be changed individually, letting the aspect ratio change (this isn’t recommended because the image can become distorted).
- Crop: Crop the image.
- Saturation: Adjust the color saturation. The default value is 50. Values range from 0 (completely desaturated) to 100 (completely saturated).
- Contrast: Adjust the contrast. The default value is 50. Values range from 0 (no contrast) to 100 (full contrast).
- Brightness: Adjust the brightness. The default value is 50. Values range from 0 (completely black) to 100 (completely white).
Filter (): Apply a filter to the image.
Figure 4: Select from a set of preset image filters.
Upon editing the image in the editor, you can click the Cancel button to cancel the changes, or the Apply button to apply them. Upon applying the changes, the history bar appears. It lets you undo, redo, or reset the changes. Use the Reset button with caution; it resets the image to its original state, reverting all changes made in the editor.
Figure 5: The history bar lets you undo, redo, and reset changes.
Once your Document Library contains files, you may want to publish them in your site. Here are some ways to publish files:
- Show them in a Documents and Media app.
- Display them in a Media Gallery.
- Use the Asset Publisher.
- Insert them in an asset like a web content article or blog entry.
Here, you’ll learn to use the Media Gallery.
The Media Gallery publishes your media files in a simple gallery-like style. It shows a large thumbnail of each media file, lets the user download files, and has slideshow capabilities. A common way to use the Media Gallery is to create a separate page for displaying media and add a Media Gallery widget to it. This way, your media takes center stage.
Follow these steps to create a page that contains a Media Gallery widget:
- Create a page and navigate to it in your site.
- At the top-right of the screen, click the Add icon () then navigate to Widgets → Content Management and select Add next to Media Gallery (alternatively, drag the Media Gallery onto your page). The Media Gallery widget appears on the page.
- Configure the Media Gallery widget to show your files. By default, it shows files from the Home folder of your site’s Documents Library. To choose a different folder, click the widget’s Options icon () and select Configuration.The Configuration window appears and shows the Setup tab. This tab contains these sections:Display Settings: Lets you show each file’s actions, filter the media types to display, and choose a display template for your media.Folders Listing: Lets you select a Document Library folder to serve as the root folder from which to display files. The root folder you select becomes the highest-level folder the Media Gallery can access. For example, if you create a subfolder of a parent folder, and then set that subfolder as the Media Gallery’s root folder, the Media Gallery can no longer access the parent folder.Note: To access the Carousel display template in Media Gallery, your role must have View access for that template. Since the Carousel template is in the Global scope, a Global-scope administrator must grant the role permission to view the template.Figure 1: You can configure the Media Gallery to use any Documents and Media folder as its root folder.
- Configure the rest of the settings as desired in the Media Gallery app’s other configuration tabs:Communication: Lists public render parameters the widget publishes to other widgets on the page. Other widgets can take action on these parameters. For each shared parameter, you can specify whether to allow communication via the parameter and select which incoming parameter can can populate it.Sharing: Embed the widget instance as a widget on on any website, Facebook, Netvibes, or as an OpenSocial Gadget.Scope: Specify the Document Library instance the widget uses: the current site’s instance (default), the global instance, or the page’s instance. If the page doesn’t already have an instance of the widget, you can select Your Page (Create New) to create a page-scoped instance for the widget to display.
- Click Save when you’re finished configuring the Media Gallery widget.
The Media Gallery now shows your files, with images appearing as thumbnails. When you click a thumbnail, a slideshow appears showing the selected image. Below that image, thumbnails of the folder’s other images are displayed. The slideshow continues until you click pause or view the last image. Closing the slideshow window returns you to the page.
Figure 2: The Media Gallery renders large thumbnail images of media files.
Figure 3: The Media Gallery’s slideshow provides a nice way to view images.
Checking Out and Editing Files
When you check out a document in the Document Library, only you can make changes to it until you check it back in. This prevents conflicting edits on the same document by multiple users. When you check out a file, you can download it, replace it, move it to another Document Library folder, check it in, or cancel the checkout. Checking in a file also increments its version, which lets you keep track of changes.
- Checkout the file by clicking its Actions icon () → Checkout. Upon checkout, the file’s status changes to Draft and a lock icon appears on the file.Figure 1: The file on the right in this image is checked out.
- Download the file by clicking its Actions icon () → Download.
- Edit the file locally.
- Return to the Documents and Media Library and click the file’s Actions icon () → Edit. The file’s edit screen appears.
- From the file’s Edit screen, select the edited local file for upload.
- Click Save and Check In. In the pop-up that appears, select whether your change is a major or minor version, add any version notes that you need, and click Save.
Note: If you edit a file without checking it out, the file’s edit screen displays a toggle for Customize the Version Number Increment and Describe My Changes. Setting this to YES lets you specify the version increment’s type and description.
Follow these steps to access a file’s version history:
- Click the file in the Documents and Media Library.
- Click the file’s Info button () at the top-right of the screen. This opens the file’s info panel.
- Select the Versions tab in the info panel.
Each file version has an Actions menu () that you can use to perform the following actions on that file version:
Download: Download the selected version of the file to your machine.
View: View the file entry screen for the selected version of the file.
Revert: Restores the selected file version as a new major file version. Note that this option isn’t available for the newest file version.
Delete Version: Remove the file version from the Document Library. All other file versions remain intact.
Figure 2: The version history actions let you inspect, delete, and reinstate file versions.
Liferay DXP’s role-based permissions system defines which actions users can take on assets, including files. Administrators can let users collaborate on files by assigning the appropriate file permissions to a Role, and then assigning users to that Role. Similarly, non-administrative users can grant permissions to Roles for files they own.
This Role-based permissions system sometimes falls short. For example, if a Role appropriate for file collaboration doesn’t exist, an administrator must create it and manage its users and permissions. Non-administrative users can’t create or manage Roles. Also, if a user wants to share a file with one other user, it’s not practical for an administrator to create and manage a Role for only two users.
Liferay DXP’s sharing feature solves these problems by letting users share files directly with each other, without involving an administrator. This saves time and effort for everyone. After all, sharing is caring.
Note: Administrators can disable sharing. For instructions on this, see Configuring Sharing.
When you share, you grant some of your own permissions for that file to the receiving user. However, there are some important caveats:
- You can only grant View, Comment, or Update permissions. For example, you can’t grant Delete or Override Checkout permissions even if you have those permissions on the file.
- You can only grant permissions you have on the file. For example, you can’t grant Update permission if you only have View and Comment permissions on the file.
- You must grant at least View permission.
- Traditional Role-based permissions always take precedence over sharing permissions. So although sharing can extend permissions, it can’t remove those granted via Roles in the portal.
- By default, the Guest Role has Add Discussion permission. This overlaps with the Comment permission in sharing. Therefore, all users can comment on a file regardless of whether the Comment permission was granted via sharing. Administrators can change this by removing the Add Discussion permission from the Guest Role.
Also note that the receiving user must be part of the same instance, but doesn’t have to be a member of the same Site.
To share a file, you must own that file or be an administrator. You must share files via the Documents and Media app in Site Administration or the Documents and Media widget on a page.
Follow these steps to share a file:
- Using the Documents and Media widget on a page or in Site Administration, navigate to the file you want to share.To navigate to the Documents and Media app in Site Administration, open the Menu (), click your Site’s name, and go to Content & Data → Documents and Media.To share a file via the Documents and Media widget on a page, actions must be enabled for the widget. Follow these steps to enable actions:
- Select Configuration from the widget’s Options menu ().
- In the Setup tab’s Display Settings, select Show Actions.
- Click Save and close the Configuration window.
- Click the file’s Actions button () and select Share. This opens the Share dialog.Alternatively, click the file in Documents and Media and then click the Share button at the top-right. This opens the same Share dialog.Figure 1: To share a file, you must fill out the Share dialog as these steps describe.
- Enter the name or email address of the user you want to share the file with. To share the file with multiple users, enter each user’s email address in a comma delimited list.
- To let receiving users also share the file, select Allow the document to be shared with other users. Note, however, that administrators can share the file regardless of your selection here.
- Select the file permissions to grant to receiving users. Because you can only grant your own permissions for the file, some of these options may be unavailable:
- Update: View, comment, and update.
- Comments: View and comment.
- View: View only.
- Click Share.
You can access files shared with you in three places:
- The Documents and Media Library: Files shared with you are visible in their existing Documents and Media locations. For example, if someone shares a file with you that resides in the Documents and Media Library’s Home folder, then you can access the file in that folder.
- The Notifications app: When a file is shared with you, you get a notification in the Notifications app. Clicking the notification takes you to the file in Documents and Media. For information on notifications, see Managing Notifications and Requests.Figure 2: The Notifications app contains the notifications that are sent when a user shares a file with you.
- The Shared Content app: This app lists all the content shared with you, and the content you shared. You can access this app from your user menu. Each file has an Actions button () for performing permitted actions on the file (e.g., view, comment, update).Figure 3: The Shared Content app lists the files shared with you, and the files you shared.
After sharing a file, you can unshare it or modify its permissions on a per-user basis. This can only be done by Administrators, the file’s owner, or any user with Update permission and permission to share the file. You can take these actions from the file’s Info panel in Documents and Media. Follow these steps:
- Click the file in Documents and Media, then click the Info button () at the top-right. The file’s Info panel slides out from the right.
- Click the Manage Collaborators link. This shows a list of the users you shared the file with and their file permissions.Figure 4: Click *Manage Collaborators* to open up the list of users you shared the file with.
- Make any changes you want to the list of collaborators. To unshare the file with a user, click the
xicon next to that user. You can also change the file permissions via the selector menu for each user.
- Click Save and close the dialog.
Figure 5: The Collaborators dialog lets you unshare a file or change the file permissions for each user.
Administrators can choose whether file sharing is enabled at the global, instance, and Site levels.
Sharing is enabled globally by default. To configure sharing globally, follow these steps:
- Go to Control Panel → Configuration → System Settings → Sharing.
- Under SYSTEM SCOPE, select Sharing.
- Configure sharing via these settings:Expired Sharing Entries Check Interval: The interval in minutes for how often expired sharing entries are checked for deletion.Enabled: Whether sharing is enabled globally.
Figure 1: Configure sharing globally.
When sharing is enabled globally, it’s also enabled by default for all portal instances. You can change this from Virtual Instance Sharing under VIRTUAL INSTANCE SCOPE:
Enabled: Whether sharing is enabled by default for all instances in the portal.
To enable or disable sharing on a per-instance basis, follow these steps:
- Go to Control Panel → Configuration → Instance Settings → Sharing.
- Select Virtual Instance Sharing under VIRTUAL INSTANCE SCOPE.
- Check or uncheck the Enabled checkbox to enable or disable sharing, respectively.
Figure 2: You can enable or disable sharing for each instance.
To enable or disable sharing for a Site, follow these steps:
- Go to Site Administration (your site’s menu) → Configuration → Settings.
- Select the General tab.
- Expand the Sharing section and use the toggle to enable or disable sharing for the Site.
Figure 3: You can enable or disable sharing for each Site.
You can access the Document Library from your desktop file manager via WebDAV. WebDAV is a set of methods based on HTTP that let users create, edit, move, or delete files stored on web servers. WebDAV is supported by most major operating systems and desktop environments, including Linux, macOS, and Windows. Using your file manager via WebDAV doesn’t bypass the functionality of the web interface—Liferay DXP increments the version numbers of files edited and uploaded via WebDAV.
To access the Document Library folder from a file browser, you must use your log-in credentials and the WebDAV URL of the folder you want to access. Follow these steps:
- Navigate to the Documents and Media app that contains the folder you want to access. Click the folder’s Actions icon () and select Access from Desktop.Figure 1: Select *Access from Desktop* to get the folder’s WebDAV URL.
- Copy the WebDAV URL and follow the instructions for your operating system:Windows: Map a network drive drive to the WebDAV URL. Enter your credentials when prompted. The Document Library folder appears in the network drive. From your file browser, you can now add, edit, move, or delete files in this folder.macOS: In the Finder, select Go → Connect to Server. In the Server Address field, enter the WebDAV URL of the folder you want to access, then click Connect and enter your credentials when prompted.Linux: In your file manager, you must slightly modify the Document Library folder’s WebDAV URL. For KDE’s Dolphin, change the URL’s protocol to
http://. For GNOME’s Nautilus, change the URL’s protocol to
http://. Then press Enter and enter your credentials when prompted.
Now you can access the Document Library folder from your desktop file system. If you edit a file in this folder on your file system, the change also shows up in the same Document Library folder in the portal. What’s more, the file’s minor version is incremented due to the edit.
You can define metadata fields that users fill out when they create or edit Document Library files. You do this by creating metadata sets and then associating them with document types, which wrap Document Library files and thus apply your metadata fields to the files. Although you apply metadata sets via document types, metadata sets exist independently and you can apply them to any number of document types.
To see the available metadata sets, open the Menu (), expand your site’s menu, and navigate to Content & Data → Documents and Media. Then click the Metadata Sets tab. Any existing sets appear in a table.
To select a metadata set, select the checkbox to its left. To select all the sets, select the checkbox in the Management Bar. With one or more sets selected, an
X icon appears in the Management Bar. Clicking it deletes the selected metadata set(s). Note that metadata sets don’t support the Recycle Bin. If you delete a metadata set, it’s gone forever.
The Management Bar also contains other options for managing the metadata sets. The selector menu to the right of the checkbox filters the sets the table displays (it’s set to All by default). The Order by selector orders the sets by Modified Date or ID. The up and down arrows sort the sets in ascending or descending order, respectively. You can also use the Search bar to search for a set.
In the table, each metadata set has an Actions button () for performing the following actions on that set:
Edit: Edit the set. Alternatively, click the set’s name in the table.
Permissions: Configure the set’s permissions.
Copy: Copy the metadata set.
Delete: Delete the set.
Figure 1: The Metadata Sets management window lets you view existing sets and create new ones for applying to document types.
Follow these steps to create a metadata set:
- From the Menu (), click your Site’s name and navigate to Content & Data → Documents and Media. Then click the Metadata Sets tab.
- Click the Add button (). The New Metadata Set form appears.
- Give your metadata set a name.
- Open the Details section of the form to give your metadata set a description or select a metadata set to extend (both are optional). To select a metadata set to extend, click the Select button for Parent Metadata Set and then select the metadata set. When a user creates a document of a document type that uses an extended metadata set, the parent metadata set’s fields appear above the extended metadata set’s.
- Add the metadata fields that should be part of this metadata set. To do this, first select the editor’s View tab and select the Fields tab within it. Icons representing the field types are listed on one side and the metadata set’s canvas is on the other side. To add a field type to the metadata set, select its icon, drag, and drop it onto the canvas. The field appears on the canvas as it does for users. By dragging a field onto a field that’s already on the canvas, you can nest the new field in the existing field. When you mouse over a field on the canvas, the field action icons () appear. Clicking the + icon creates a duplicate of the current field and adds it below the current field. Clicking the trash can deletes the field.The following metadata fields are available:
- Boolean: A check box.
- Color: Specifies a color.
- Date: Enter a date. A valid date format is required for the date field, but you don’t have to enter a date manually. When you select the date field a mini-calendar pops up which you can use to select a date.
- Decimal: Enter a decimal number. The value is persisted as a
- Documents and Media: Select a file from a Documents and Media library.
- Geolocation: Specify a location to associate with the document.
- HTML: An area that uses a WYSIWYG editor to enhance the content.
- Integer: Enter an integer. The value is persisted as an
- Link to Page: Link to another page in the same site.
- Number: Enter a decimal number or an integer. The value is persisted either as a
int, depending on the input’s type.
- Radio: Displays several clickable options. The default number of options is three but this is customizable. Only one option can be selected at a time.
- Select: This is just like the radio field except that the options are hidden and must be accessed from a drop-down menu.
- Text: Enter a single line of text.
- Text Box: This is just like the text field except you can enter multiple lines of text or separate paragraphs.
- Web Content: Select web content.
- Edit your fields to reflect their intended metadata. For example, a text field’s default label is Text. If you want to use the text field as a title, for instance, then you should change the field’s label to Title. To do this, first select the field on the canvas. This automatically selects the Settings tab on the left. Alternatively, you can access the Settings tab by clicking the field’s wrench icon. To edit a setting value, double-click it in the Settings table and enter the new value.Labels, default values, variable names, mouse-over tips, widths, and other settings can be configured for most fields. Some fields have a Required setting for specifying whether users must populate the field. If a field’s Repeatable setting is Yes, users can add multiple consecutive instances of the field to the document’s metadata.Also note that you can translate each of a metadata set’s field values to any supported locales. To specify a field value for a translation, select the flag that represents the locale and enter the field value for the locale.
- Click Save when you’re done specifying your new metadata set.Figure 3: Edit your metadata set’s fields to match the metadata that you want each field to hold.
Document types are made of metadata fields and help users define the purpose of Document Library files. For example, a Contract document type may need metadata fields for the effective date, expiration date, contract type, legal reviewer, and more. When users create Document Library files of the Contract document type, they can then populate those metadata fields. Document types also help you integrate files with other features like search and workflow. Search works on file metadata so users can find files faster. You can also apply workflows to specific document types. And you can more cleanly organize document libraries by designating folders to hold particular document types exclusively.
To see the available document types, open the Menu (), expand your site’s menu, and navigate to Content & Data → Documents and Media. Then click the Document Types tab. A searchable table lists any existing document types. The following actions are available for each document type via its Actions button ():
Edit: Edit the document type.
Permissions: Set the document type’s permissions.
Delete: Delete the document type. Note that document types don’t support the Recycle Bin. Once you delete a document type, it’s gone forever.
Figure 1: The Document Types management window lets you view existing document types and create new ones.
Follow these steps to create a document type:
- From the Menu (), expand your site’s menu and navigate to Content & Data → Documents and Media. Then click the Document Types tab.
- Click the Add button (). The New Document Type form appears.
- Give your document type a name and a description.Figure 2: Create your new document type.
- Define the metadata to use with your document type. You do this via these sections in the form:Main Metadata Fields: These are tied directly to the document type. They can be created only via the form and can’t be used with other document types. You create and edit these metadata fields in the form the same way that you do when creating metadata sets.Additional Metadata Fields: Select a metadata set to associate with the document type. Each document type must be associated with one or more metadata set. To differentiate document types that use the same metadata sets, define different main metadata fields.
- Define your document type’s permissions via the form’s Permissions section. By default, anyone can view the document type, including site guests. You can restrict its view, update, delete, and permissions configuration to site members or the document type’s owner.
- Click Save when you’re finished specifying your new document type.
Your document type is now available when adding a document via the Documents and Media’s Add menu. When users create new files of the document type, they’re presented with metadata fields to describe the document.
Online File Creation and Editing with Google Docs™
Although you can add and edit Documents and Media files via upload and download, Liferay DXP doesn’t contain a UI that lets you author or edit documents directly. You can, however, create and edit Documents and Media files online in Google Docs™, Google Sheets™, and Google Slides™.
Note: For simplicity and readability, this documentation refers only to Google Docs™. The material, however, also applies to Google Sheets™ and Google Slides™.
Note that when you use Google Docs™ to create or edit a Documents and Media file, that file isn’t permanently stored in Google Docs™. Google Docs™ is only used for its editing UI. Your edits are then saved to the Documents and Media Library.
Figure 1: You can create new Google documents in Documents and Media.
Figure 2: You can also use Google’s document editor to edit existing Documents and Media files.
Figure 3: When using Google’s document editor, you can save or discard your changes via the editor’s toolbar.