Adding Views to Filtered Search

[ddraper]

Introduction

One of the Alfresco Solutions Engineers recently contacted me to ask how easy it would be to add a table view into the new filtered search page in Alfresco 5.0. Fortunately this page is built using the Aikau framework, so this is actually an incredibly easy task to accomplish. This blog will take you through the process. If you have trouble following the steps or just want to try it out then download the example extension module from here.

Extension Module Creation

The best practice to customizing Alfresco Share is to first create an extension module, and for Aikau pages this is a very straightforward process. First of all ensure that Share is running in “client-debug” mode.

Now login to Share and perform a search so that the filtered search page is displayed.

Open the “Debug” drop-down menu and select “Toggle Developer View”

You should see a page that looks like this:

Now click on the link at the very top of the page that says “Click to generate extension JAR”. This will generate a JAR file containing all files required to customize the filtered search page.

Unpack the JAR file and open the “/alfresco/site-webscripts/org/alfresco/share/pages/faceted-search/customization/faceted-search.get.js” file in your editor of choice.

Now go back to the filtered search page (still in developer view) and click on the info icon for the main list. It should display a tooltip indicating that the widget selected has an id of “FCTSRCH_SEARCH_RESULTS_LIST”.

Copy the “Find Widget Code Snippet”, it should be:

widgetUtils.findObject(model.jsonModel.widgets, 'id', 'FCTSRCH_SEARCH_RESULTS_LIST');‍

Paste this into the “faceted-search.get.js” file that is open in your editor. This snippet of code is all you need to target a widget on an Aikau page (obviously each snippet of code is different for each widget on the page), and in this case you have targeted the main search results list.

Understanding the extension

Lists in Aikau are used to manage data and delegate the rendering of that data to one or more views . We want to add an additional view into the search page.

There is lots of information in the Aikau tutorial on creating views, so I'm not going to repeat that information here, but if you're not familiar with defining a list then you should certainly work your way through the tutorial.

To add a new view you just need to “push” a new widget declaration into the “widgets” array of the search lists “config” object. You can create any view you like, but as a relatively simple example you could create the following (this would be the complete contents of the faceted-search.get.js file):

var widget = widgetUtils.findObject(model.jsonModel.widgets, 'id', 'FCTSRCH_SEARCH_RESULTS_LIST');
if (widget && widget.config && widget.config.widgets)
{
   widget.config.widgets.push({
      name: 'alfresco/documentlibrary/views/AlfSearchListView',
      config: {
         viewSelectionConfig: {
            label: 'Table View',
            iconClass: 'alf-tableview-icon'
         },
         widgetsForHeader: [
            {
               name: 'alfresco/documentlibrary/views/layouts/HeaderCell',
               config: {
                  label: 'Name'
               }
            },
            {
               name: 'alfresco/documentlibrary/views/layouts/HeaderCell',
               config: {
                  label: 'Description'
               }
            }
         ],
         widgets: [
            {
               name: 'alfresco/search/AlfSearchResult',
               config: {
                  widgets: [
                     {
                        name: 'alfresco/documentlibrary/views/layouts/Row',
                        config: {
                           widgets: [
                              {
                                 name: 'alfresco/documentlibrary/views/layouts/Cell',
                                 config: {
                                    additionalCssClasses: 'mediumpad',
                                    widgets: [
                                       {
                                          name: 'alfresco/renderers/SearchResultPropertyLink',
                                          config: {
                                             propertyToRender: 'displayName'
                                          }
                                       }
                                    ]
                                 }
                              },
                              {
                                 name: 'alfresco/documentlibrary/views/layouts/Cell',
                                 config: {
                                    additionalCssClasses: 'mediumpad',
                                    widgets: [
                                       {
                                          name: 'alfresco/renderers/Property',
                                          config: {
                                             propertyToRender: 'description'
                                          }
                                       }
                                    ]
                                 }
                              }
                           ]
                        }
                     }
                  ]
               }
            }
         ]
      }
   });
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

We're pushing in a new 'alfresco/documentlibrary/views/AlfDocumentListView' that uses the table view icon ('alf-tableview-icon'), has a label of “Table View” (which we could have localized if we wanted) and a value of “table”.

The view has two header cells (for name and description) and each item in the list is rendered as an 'alfresco/documentlibrary/views/layouts/Row' widget containing two 'alfresco/documentlibrary/views/layouts/Cell' widgets.

The first cell contains 'alfresco/renderers/SearchResultPropertyLink' that renders the “displayName” of the item and the second is a simple 'alfresco/renderers/Property' that renders the description.

Testing out the view

Re-package the extension files as a JAR file, copy that JAR file into the “share/WEB-INF/lib” folder and then restart the server. When you perform a search you should see your table view as an option.



Selecting the table view will show the search results as:



You can add more columns to your table view, but it's important to understand that the API used on the search page only retrieves a very small set of Node data. The data that is available for each node found is:

• displayName

• description

• mimetype

• modifiedBy (user display name)

• modifiedByUser (username)

• modifiedOn

• name

• title

• nodeRef

• path (within a site)

• site (if the node is in a site)

• size (in bytes)

• tags

• type (e.g. “document”)

If you want to display more than than this limited set of data then there are a couple of options available.

One approach that you could take is to use the “alfresco/documentlibrary/views/layouts/XhrLayout” widget that allows an initial version of the view to be rendered for an item (using the limited data set) and when that item is clicked the full node data is requested and the “full” view is then rendered using that data. However, this widget is only a prototype and should only be used as an example.

Another option would be to extend the “alfresco/documentlibrary/AlfSearchList” widget to request the full data for each node before the view is rendered. This would naturally slow down the rendering of search results but would allow you to display any of the data available for that node.

Deprecations

The example used in this blog will work on 5.0, but you should be aware that some of the widgets referenced have now been deprecated in later versions of Alfresco. The deprecated widgets won't be removed for a long time, but if you’re customizing 5.0.1 onwards then you should look to use the latest versions. All deprecations are listed in the release notes for Aikau.