It happened to me several times, but I imagine it happened to you during the development of a portlet, the need to select a file or folder from Liferay Document Library; something simple at first glance because the core portlets already do this in several points.

But replicate the same behaviour within your own portlet is not so easy and requires several hours of Liferay source code analysis to figure out where to put your hands; those of you who have ever put his hands in the source code of Liferay and especially in AlloyUI source code, knows how frustrating it can be.

Then I started thinking how to solve the problem without having to do copy&paste every time, and the solution I found was to create an AlloyUI module which expose some JavaScript objects to interface with the Document Library; something that free the developer from the details and that could be reused over time.

So I created the liferay-dl-util module and packed everything with a hook released on the Liferay Marketplace, so that anyone can download and use it immediately.

In this article we will see how to use the JavaScript objects provided by the module to allow the selection of a file or folder from the Liferay Document Library.

The extension is available on Liferay Marketplace: Document Library JS Util

Let's first prepare the JSP page in which we are going to use the Javascript objects; for simplicity I'll assume that the reader knows the meaning of the HTML tags and taglib used in this example.

<!--
    HTML container element, where will be rendered the
    button which will open the dialog to select the file
-->
<div id="<portlet:namespace/>fileSelector"></div>
<!--
    This is the (usually) hidden field in which the Javascript object
    Liferay.DLUtil.FileSelector will automatically fill in the document UUID
    after being selected; if this field is missing, nothing will be filled in
-->
<aui:input name="uuid" disabled="true" />
<!--
    This is only a sample field, to view all the informations provided by
    the Javascript object
-->
<aui:input name="fileArea" type="textarea" />

Since the AlloyUI module also provides an object to select a folder, let's add in the sample JSP page the elements to manage this second chance.

<!--
    HTML container element, where will be rendered the
    button which will open the dialog to select the folder
-->
<div id="<portlet:namespace/>folderSelector"></div>
<!--
    This is the (usually) hidden field in which the Javascript object
    Liferay.DLUtil.FolderSelector will automatically fill in the folderId
    after being selected; if this field is missing, nothing will be filled in
-->
<aui:input name="folderId" disabled="true" />
<!--
    This is only a sample field, to view all the informations provided by
    the Javascript object
-->
<aui:input name="folderArea" type="textarea" />

Now we are going to write at the bottom of the JSP page, the AlloyUI code necessary to initialize and use the component to select a file from the Liferay Document Library.

<aui:script use="liferay-dl-util">
    new Liferay.DLUtil.FileSelector({
        /* HTML container name set above */
        container: '#<portlet:namespace/>fileSelector',
        /* configuration object of the A.Dialog widget */
        dialog: {
            centered: true,
            modal: true,
            title: '<liferay-ui:message key="please-select-file" />'
        },
        /* CSS selector to identify the field to fill in the document UUID */
        hiddenInput: '#<portlet:namespace/>uuid',
        /* events provided by the widget */
        on: {
            click: function(button, event) {
                /*
                 * Function invoked at the button click, before the dialog opens; insert here your code if needed
                 */
            },
            select: function(contextPath, uuid, title, version) {
                /*
                 * Function invoked "after" file selection; insert here your code in case you need informations
                 * other than simple the document UUID
                 */

                // this sample code only display, inside the textarea above, all the informations provided by
                // the widget
                var area = A.one('#<portlet:namespace/>fileArea');
                var msg = 'ContextPath: ' + contextPath + '\n' +
                          'UUID: ' + uuid + '\n' +
                          'Title: ' + title + '\n' +
                          'Version: ' + version;
                area.val(msg);
            }
        }
    }).render();
</aui:script>

Finally let's see the code to be inserted at the bottom of the JSP page to initialize and use the component to select a folder from the Liferay Document Library.

<aui:script use="liferay-dl-util">
    new Liferay.DLUtil.FolderSelector({
        /* HTML container name set above */
        container: '#<portlet:namespace/>folderSelector',
        /* CSS selector to identify the field to fill in the folderId */
        hiddenInput: '#<portlet:namespace/>folderId',
        /* events provided by the widget */
        on: {
            click: function(button, event) {
                /*
                 * Function invoked at the button click, before the dialog opens; insert here your code if needed
                 */
            },
            select: function(folderId, folderName, isSupportMetaData, isSupportSocial) {
                /*
                 * Function invoked "after" file selection; insert here your code in case you need informations
                 * other than simple the document UUID
                 */

                // this sample code only display, inside the textarea above, all the informations provided by
                // the widget
                var area = A.one('#<portlet:namespace/>folderArea');
                var msg = 'FolderId: ' + folderId + '\n' +
                          'FolderName: ' + folderName + '\n' +
                          'IsSupportMetaData: ' + isSupportMetaData + '\n' +
                          'IsSupportSocial: ' + isSupportSocial;
                area.val(msg);
            }
        }
    }).render();
</aui:script>