Module: alfresco/lists/AlfList

alfresco/lists/AlfList

This is the simplest widget for rendering lists of data. The data is retrieved by publishing a loadDataPublishTopic that will need to be subscribed to by a service included on the page. Depending upon the service handling the request it may be necessary to configure a loadDataPublishPayload to provide additional information on the data that should be loaded.

Lists should be configured with at least one AlfListView (or a widget that extends it) to render the loaded data. The most basic view that can be used would be the HtmlListView that renders a basic bullet list of the data

If the list is not rendered on the page when first loaded (for example it might be displayed in a dialog or an initially hidden tab in an AlfTabContainer) then it will be necessary to configure the waitForPageWidgets to be false to avoid the list waiting for an event that will never be fired before attempting to load data).

If you need to use a list with greater capabilities then consider using the AlfHashList, AlfSortablePaginatedList or AlfFilteredList as these incrementally provide additional capabilities for URL hashing, sorting and paginating and filtering respectively.

Depending upon the payload of the data returned by the service it might be necessary to configure the itemsProperty to identify the attribute containing the array of items to be rendered.

It is also possible to explicitly define the data to be listed by setting the currentData. This should be configured to be an object containing an "items" attribute that is the data to be rendered.

Author:
  • Dave Draper
Copyright:
  • Copyright (C) 2005-2020 Alfresco Software Limited
License:
Source:

Examples

Basic list with hard-coded data

{
  name: "alfresco/lists/AlfList",
  config: {
    currentData: {
      items: [
        { value: "one"},
        { value: "two"}
      ]
    },
    widgets: [
      {
        name: "alfresco/lists/views/HtmlListView",
        config: {
          propertyToRender: "value"
        }
      }
    ]
  }
}

Basic list loading users from the Repository via the CrudService

{
  name: "alfresco/lists/AlfList",
  config: {
    loadDataPublishTopic: "ALF_CRUD_GET_ALL",
    loadDataPublishPayload: {
      url: "api/people"
    },
    itemsProperty: "people",
    widgets: [
      {
        name: "alfresco/lists/views/HtmlListView",
        config: {
          propertyToRender: "userName"
        }
      }
    ]
  }
}

Extends

Mixes In

Members

_currentlySelectedView :string

Use to keeps track of the view that is currently selected.
Type:
  • string
Default Value:
  • null
Source:

_dataFailureWidgetsRendered :boolean

A flag to indicate whether or not the widgetsForDataFailureDisplay have been rendered. This prevents them from being repeatedly set. It should not be explicitly configured in the list - it is for internal use only.
Type:
  • boolean
Since:
  • 1.0.48
Default Value:
  • false
Source:

_filterDelay :number

Type:
  • number
Default Value:
  • 1000
Source:

_focusItemKey :string

The key of the item to attempt to focus on in the loaded results. This can be set via the payload handled by onReloadData.
Type:
  • string
Since:
  • 1.0.77
Default Value:
  • null
Source:

_hideLoadingTimeoutPointer :object

This timeout pointer is used to ensure the loading message doesn't display forever
Type:
  • object
Since:
  • 1.0.48
Default Value:
  • null
Source:

_readyToLoad :boolean

This is updated by the onPageWidgetsReady function to be true when all widgets on the page have been loaded. It is used to block loading of data until the page is completely setup. This is done to avoid multiple data loads as other widgets on the page publish the details of their initial state (which would otherwise trigger a call to loadData)
Type:
  • boolean
Default Value:
  • false
Source:

additionalControlsTarget :string

This is the ID of the widget that should be targeted with adding additional view controls to
Type:
  • string
Default Value:
  • "DOCLIB_TOOLBAR"
Source:

additionalViewControlVisibilityConfig :object

This is the dynacmic visibility configuration that should be applied to all additional controls added for a view.
Type:
  • object
Default Value:
  • null
Source:

cssRequirements :object[]

An array of the CSS files to use with this widget.
Type:
  • object[]
Default Value:
  • [{cssFile:"./css/AlfList.css"}]
Source:

currentData :object

Used to keep track of the current data for rendering by views.
Type:
  • object
Default Value:
  • null
Source:

currentItemPropertyForDataItems :string

A property from the currentItem that should be used as the list of items to be displayed. This is useful when rendering a list within a list.
Type:
  • string
Since:
  • 1.0.85
Default Value:
  • null
Source:

currentRequestId :string

An internally used attribute to hold a UUID for the any in-flight request. This allows the request to be cancelled if a subsequent request is issued before the in-flight request completes. This should not be configured.
Type:
  • string
Since:
  • 1.0.75
Default Value:
  • null
Source:

dataFailureMessage :string

This is the message to display when data cannot be loaded Message keys will be localized where possible.
Type:
  • string
Default Value:
  • "alflist.data.failure.message"
Source:

dataFilters :array

An array of filters that should be included in data loading requests. The list itself will not perform any filtering it is up to the service (or API that the service calls) to filter the results based on the data provided.
Type:
  • array
Default Value:
  • null
Source:

fetchingDataMessage :string

This is the message to display when data is loading. Message keys will be localized where possible.
Type:
  • string
Default Value:
  • "alflist.loading.data.message"
Source:

fetchingMoreDataMessage :string

This is the message to display when fetching more data. Message keys will be localized where possible.
Type:
  • string
Default Value:
  • "alflist.loading.data.message"
Source:

filteringTopics :array

An array of the topics to subscribe to that when published provide data that the indicates how the data requested should be filtered.
Type:
  • array
Default Value:
  • null
Source:

hideLoadingDelay :number

Permit the loading indicators to remain on screen for a few milliseconds after the page loads in order to prevent "flashing" of the loading message.
Type:
  • number
Default Value:
  • 250
Source:

hideLoadingTimeoutDuration :number

Specifies how long to wait (in ms) before forcing removal of the loading message
Type:
  • number
Since:
  • 1.0.48
Default Value:
  • 10000
Source:

i18nRequirements :object[]

An array of the i18n files to use with this widget.
Type:
  • object[]
Default Value:
  • [{i18nFile: "./i18n/AlfList.properties"}]
Source:

itemsProperty :string

The property in the data response that is the attribute of items to render
Type:
  • string
Default Value:
  • "items"
Source:

loadDataFailureTopic :string

If not configured this will automatically be generated to be the loadDataPublishTopic appended with "_FAILURE".
Type:
  • string
Since:
  • 1.0.74
Default Value:
  • null
Source:

loadDataImmediately :boolean

Indicates whether or not a request for data should be loaded as soon as the widget is created. This will have no effect when currentData is configured.
Type:
  • boolean
Default Value:
  • true
Source:

loadDataPublishPayload :object

This is the payload to publish to make requests to retrieve data to populate the list with.
Type:
  • object
Default Value:
  • null
Source:

loadDataPublishTopic :string

This is the topic to publish to make requests to retrieve data to populate the list with. This can be overridden with alternative topics to obtain different data sets. Defaults to GET_DOCUMENT_LIST
Type:
  • string
Source:

loadDataSuccessTopic :string

If not configured this will automatically be generated to be the loadDataPublishTopic appended with "_SUCCESS".
Type:
  • string
Since:
  • 1.0.74
Default Value:
  • null
Source:

metadataProperty :string

The property in the data response that is a metadata attribute containing additional information about the overall context of the list. This defaults to "metadata". If not attribute with the defined name is provided then no data will be assigned.
Type:
  • string
Default Value:
  • "metadata"
Source:

noDataMessage :string

This is the message to display when no data is available. Message keys will be localized where possible.
Type:
  • string
Default Value:
  • "alflist.no.data.message"
Source:

pendingLoadRequest :boolean

An internally used attribute used to indicate whether or not a request is pending to be performed as soon as the current request completes.
Type:
  • boolean
Default Value:
  • false
Source:

renderingViewMessage :string

This is the message to display whilst a view is being rendered. Message keys will be localized where possible.
Type:
  • string
Default Value:
  • "alflist.rendering.data.message"
Source:

requestInProgress :Boolean

Is there currently a request in progress?
Type:
  • Boolean
Default Value:
  • false
Source:

startIndexProperty :string

The property in the response that indicates the starting index of overall data to request.
Type:
  • string
Default Value:
  • "startIndex"
Source:

suppressDndUploading :boolean

Indicates whether or not views should apply drag-and-drop highlighting. Each view used by the list will have this value applied (even if it overrides custom configuration) as it is up to the list to control whether or not it supported drag-and-drop behaviour.
Type:
  • boolean
Since:
  • 1.0.39
Default Value:
  • true
Source:

templateString :String

The HTML template to use for the widget.
Type:
  • String
Source:

totalResultsProperty :string

The property in the response that indicates the total number of results available.
Type:
  • string
Default Value:
  • "totalRecords"
Source:

useInfiniteScroll :boolean

Indicates whether Infinite Scroll should be used when requesting documents
Type:
  • boolean
Default Value:
  • false
Source:

viewControlsMap :object

A map of the additional controls that each view requires. This is map is populated as each view is selected (so that the controls are only loaded once) but are then loaded from the map. This allows the same controls to be added and removed as views are switched.
Type:
  • object
Default Value:
  • null
Source:

viewMap :object

A map of views that the list can switch between.
Type:
  • object
Default Value:
  • null
Source:

viewModifiers :string[]

This can be configured to an array of modifying functions (typically provided by the ObjectProcessingMixin but can be provided by extending or mixed in modules) to process the widget models used to render views. A common example might be to use the processInstanceTokens to pass on instance values of the list onto the views that are rendered.
Type:
  • string[]
Since:
  • 1.0.65
Default Value:
  • null
Source:

viewPreferenceProperty :string

The preference property to use for saving the current view. Initially defaulted to the document library view preference but can be overridden if desired.
Type:
  • string
Default Value:
  • "org.alfresco.share.documentList.viewRendererName"
Source:

viewWidgetsMappingId :string

This is the string that is used to map the call to processWidgets to create the views defined for the list to the resulting callback in allWidgetsProcessed
Type:
  • string
Since:
  • 1.0.35
Default Value:
  • "VIEWS"
Source:

waitForPageWidgets :boolean

This indicates that the instance should wait for all widgets on the page to finish rendering before making any attempt to load data. If this is set to true then loading can begin as soon as this instance has finished being created. This needs to be overridden in the case where the instance is created dynamically after the page has loaded.
Type:
  • boolean
Default Value:
  • true
Source:

widgets :object[]

The widgets processed by AlfDocumentList should all be instances of "alfresco/lists/views/AlfListView". Any widget that is instantiated that does not inherit from that class will not be included as a view.
Type:
  • object[]
Default Value:
  • null
Source:

widgetsForDataFailureDisplay :object[]

An optional JSON model defining the widgets to display when an error occurs attempting to load data to display.
Type:
  • object[]
Since:
  • 1.0.48
Default Value:
  • null
Source:

Methods

_extractFilters(requestConfig) → {Object[]}

Extract the filter objects from the supplied successful requestConfig
Parameters:
Name Type Description
requestConfig Object The request config from a successful request
Source:
Returns:
The filters in the request (empty if none found)
Type
Object[]

allWidgetsProcessed(The, processWidgetsId)

Iterates over the widgets processed and calls the registerView function with each one.
Parameters:
Name Type Description
The object[] created widgets
processWidgetsId string The ID that the call to the processWidgets to create the views.
Source:

clearViews()

Iterates over all the views and calls their clearOldView function.
Source:

completeListSetup(The)

This is called from allWidgetsProcessed to determine whether or not to immediately load data or to wait for all of the widgets on the page to be created first.
Parameters:
Name Type Description
The object[] created widgets
Since:
  • 1.0.36.4
Source:

constructor()

The constructor
Source:

copyViewData()

This is called from handleNewViewInstances when a new view is created to replace the existing view. It allows all relevant data to be copied from the old view to the new view.
Since:
  • 1.0.51
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code must be called in the overriding function and if the inherited function returns a value then that value must be returned by the overriding function.
Source:

createFilterSubscriptions(The)

Create the subscriptions for the filteringTopics. This is called from allWidgetsProcessed.
Parameters:
Name Type Description
The object[] created widgets
Since:
  • 1.0.36.4
Source:

handleNewViewInstances(widgets)

Parameters:
Name Type Description
widgets object[] The array of widgets created (this should just contain a single view instance)
Since:
  • 1.0.48
Source:

hideChildren(targetNode)

Hides all the children of the supplied DOM node by applying the "share-hidden" CSS class to them.
Parameters:
Name Type Description
targetNode Element The DOM node to hide the children of.
Source:

hideLoadingMessage()

Remove any loading displays.
Since:
  • 1.0.48
Source:

isValidViewSelectionConfig(viewSelectionConfig) → {boolean}

By default this just ensures that a label has been provided. However this function could be overridden to provide more complete validation if there are specific requirements for view selection configuration.
Parameters:
Name Type Description
viewSelectionConfig object The configuration to validate
Source:
Returns:
Either true or false depending upon the validity of the supplied configuration.
Type
boolean

loadData(parameters)

Makes a request to load data from the repository. If the request is successful then then the onDataLoadSuccess function will be called. If the request fails then the onDataLoadFailure function will be called.
Parameters:
Name Type Argument Description
parameters object <optional>
 An optional parameters object providing information about the data to load
Properties
Name Type Argument Description
focusItemKey string <optional>
 An item to focus on if it is in the data that is reloaded
Source:
Fires:

onDataLoadFailure(response, originalRequestConfig)

Handles failed calls to get data from the repository.
Parameters:
Name Type Description
response object The response object
originalRequestConfig object The configuration that was passed to the serviceXhr function
Source:

onDataLoadSuccess(response, originalRequestConfig)

Handles successful calls to get data from the repository.
Parameters:
Name Type Description
response object The response object
originalRequestConfig object The configuration that was passed to the serviceXhr function
Source:

onFilterRequest(payload)

Updates the list of filters that should currently be included when requesting data.
Parameters:
Name Type Description
payload object The published payload containing the filter data.
Source:

onFiltersUpdated()

Handle filters being updated
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code does not need to be called however the overriding function must perform the designated action and return the appropriate data where appropriate.
Source:

onPageWidgetsReady(payload)

The list is intended to work co-operatively with other widgets on a page to assist with setting the data that should be retrieved. As related widgets are created and publish their initial state they may trigger requests to load data. As such, data loading should not be started until all the widgets on the page are ready.
Parameters:
Name Type Description
payload object
Source:

onReloadData(payload)

Handles requests to reload the current list data by clearing all the previous data and then calling loadData.
Parameters:
Name Type Argument Description
payload object <optional>
 The payload supplied when making the reload request.
Properties
Name Type Argument Description
focusItemKey string <optional>
 An item to focus on if it is in the data that is reloaded
Source:

onRequestFinished()

Triggered when a request has finished to allow another submission.
Source:

onRequestInProgress()

Triggered when a request is in progress to prevent multiple submissions.
Source:

onScrollNearBottom(payload)

This is an extension point function that performs no action but can be overridden by extending modules.
Parameters:
Name Type Description
payload
Source:

onViewSelected(payload)

Handles requests to switch views. This is called whenever the viewSelectionTopic topic is published on and expects a payload containing an attribute "value" which should map to a registered view. The views are mapped against the index they were configured with so the value is expected to be an integer.
Parameters:
Name Type Description
payload object The payload published on the view selection topic.
Source:

postCreate()

Source:

postMixInProperties()

Subscribe the document list topics.
Source:

processLoadedData(response)

Publishes the details of the documents that have been loaded (primarily for multi-selection purposes) and stores any requested starting index and total records data.
Parameters:
Name Type Description
response object The original response.
Source:

processView(view, index)

Processes a registered view. This function essentially adds the view to the viewMap.
Parameters:
Name Type Description
view object The view to process
index number The view index
Source:

publishAdditionalControls(viewName, view)

Gets the additional controls for a view and publishes them.
Parameters:
Name Type Description
viewName string The name of the view
view object The view to get the controls for.
Source:

registerView(view, index)

This is called from allWidgetsProcessed for each widget defined. Only widgets that inherit from AlfListView will be successfully registered.
Parameters:
Name Type Description
view object The view to register
index number
Source:

registerViews(The)

Iterate of the supplied list of widgets (which should all be views) and calling the registerView function for each of them. Once the views are all registered ensure that the requested view to be initially displayed is rendered. This is called from allWidgetsProcessed.
Parameters:
Name Type Description
The object[] created widgets
Since:
  • 1.0.36.4
Source:

renderView()

This function renders the view with the current data.
Source:

setDisplayMessages()

This function should be overridden as necessary to change the messages displayed for various states of the list, e.g.
  • When no view is configured
  • When there is no data to render
  • When data is being retrieved
  • When the view is being rendered
  • When the additional data is being retrieved (e.g. on infinite scroll)
Source:

setupSubscriptions()

This function sets up the subscriptions that the Document List relies upon to manage its internal state and request documents.
Source:

showDataLoadFailure()

If there is no data to render a view with then this function will be called to update the DocumentList view node with a message explaining the situation.
Source:

showLoadingMessage()

This is called before a request to load more data is made so that the user is aware that data is being asynchronously loaded.
Source:

showNoDataMessage()

If there is no data to render a view with then this function will be called to update the DocumentList view node with a message explaining the situation.
Source:

showRenderingMessage()

This is called once data has been loaded but before the view rendering begins. This can be useful when there is a lot of data and the view is complex to render so may not be instantaneous.
Source:

showView(view, renderedItems) → {Promise|Array.<object>}

Parameters:
Name Type Description
view object The view to show
renderedItems object[] The items rendered (this should be returned)
Source:
Fires:
Returns:
The promise of the items rendered in the view
Type
Promise | Array.<object>

updateLoadDataPayload(payload)

This is an extension point for extending modules to use. By default it does nothing to the supplied payload.
Parameters:
Name Type Description
payload object The payload object to update
Source:

<inner> onNewViewRendered(oldView, newView, renderedItems) → {Promise|Array.<object>}

Parameters:
Name Type Description
oldView object The previous view that is being replaced
newView object The view that has now been rendered
renderedItems object[] The items rendered (this should be returned)
Since:
  • 1.0.101
Source:
Returns:
The promise of the items rendered in the view
Type
Promise | Array.<object>