Module: alfresco/core/CoreWidgetProcessing

alfresco/core/CoreWidgetProcessing

This mixin in provides all the functions required for widgets that wish to process sub-widgets.
Author:
  • Dave Draper
Support:
  • This module is safe to be mixed into 3rd-party widgets and services (at least until the next major release).
Copyright:
  • Copyright (C) 2005-2020 Alfresco Software Limited
License:
Source:

Extends

Mixes In

Members

_countDownLocationPrefix :string

This string is used to identify locations of counts of widgets that are being processed.
Type:
  • string
Since:
  • 1.0.36
Default Value:
  • "_processingCountDown"
Source:

_processedWidgetCountdown :number

As of 1.0.36 this is no longer used and it should not be referenced
Type:
  • number
Deprecated:
  • Since 1.0.36
    Default Value:
    • null
    Source:

    _processedWidgets :Array

    Used to keep track of all the widgets created as a result of a call to the processWidgets function. This should not be referenced directly, instead the getProcessedWidgets should be called.
    Type:
    • Array
    Default Value:
    • null
    Source:

    _processedWidgetsLocationPrefix :string

    This string is used to identify locations where processed widgets can be referenced. This location will either be populated with an array of widgets or with a promise that will be resolved once all the widgets have been created. This should not be set or configured.
    Type:
    • string
    Since:
    • 1.0.36
    Default Value:
    • "_processedWidgets"
    Source:

    _processingWidgetsLocationPrefix :string

    This string is used to identify locations of arrays where widgets that are being created will be stored. THis should not be set or configured.
    Type:
    • string
    Since:
    • 1.0.36
    Default Value:
    • "_processingWidgets"
    Source:

    cssRequirements :object[]

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

    currentItem :object

    The current item to act upon
    Type:
    • object
    Default Value:
    • null
    Source:

    widgetProcessingComplete :boolean

    This is set from false to true after the allWidgetsProcessed extension point function is called. It can be used to check whether or not widget processing is complete. This is to allow for checks that widget processing has been completed BEFORE attaching a listener to the allWidgetsProcessed function.
    Type:
    • boolean
    Default Value:
    • false
    Source:

    Methods

    _registerProcessedWidget(widget, index, processWidgetsId)

    This function registers the creation of a widget. It decrements the _processedWidgetCountdown attribute and calls the {@link module:alfresco/core/Core#allWidgetsProcessed} function when it reaches zero.
    Parameters:
    Name Type Description
    widget object The widget that has just been processed.
    index number The target index of the widget
    processWidgetsId string An optional ID that might have been provided to map the results of multiple calls to processWidgets
    Source:

    _visibilitySetting(status, widget)

    This function is called when form style visibility configuration is used.
    Parameters:
    Name Type Description
    status boolean Whether or not the widget should be displayed or not.
    widget object The widget to toggle the visibility of
    Since:
    • 1.0.69
    Source:

    allWidgetsProcessed(widgets, processWidgetsId)

    This is an extension point for handling the completion of calls to processWidgets
    Parameters:
    Name Type Description
    widgets Array An array of all the widgets that have been processed
    processWidgetsId string An optional ID that might have been provided to map the results of multiple calls to processWidgets
    Support:
    • This function is provided as an extension point and is safe to be overridden by extending or mixing modules (at least until the next major release).
    Source:

    createWidget(widget, domNode, callback, callbackScope, index) → {object|promise}

    This method will instantiate a new widget having requested that its JavaScript resource and dependent resources be downloaded. In principle all of the required resources should be available if the widget is being processed in the context of the Surf framework and dependency analysis of the page has been completed. However, if this is being performed as an asynchronous event it may be necessary for Dojo to request additional modules. This is why the callback function is required to ensure that successfully instantiated modules can be kept track of.
    Parameters:
    Name Type Description
    widget object The configuration for the widget
    domNode element The DOM node to attach the widget to
    callback function A function to call once the widget has been instantiated
    callbackScope object The scope with which to call the callback
    index number The index of the widget to create (this will effect it's location in the _processedWidgets array)
    Source:
    Returns:
    Either the created widget or the promise of a widget
    Type
    object | promise

    createWidgetDomNode(widget, rootNode, rootClassName)

    Creates a new DOM node for a widget to use. The DOM node contains a child
    element that the widget will be attached to and an outer
    element that additional CSS classes can be applied to.
    Parameters:
    Name Type Description
    widget object The widget definition to create the DOM node for
    rootNode element The DOM node to create the new DOM node as a child of
    rootClassName string A string containing one or more space separated CSS classes to set on the DOM node
    Source:

    filterPropertyExists(renderFilterConfig) → {boolean}

    Checks to see whether or not the supplied filter property is a genuine attribute of the currentItem.
    Parameters:
    Name Type Description
    renderFilterConfig Object The filter configuration to process.
    Source:
    Returns:
    true if the property exists and false if it doesn't.
    Type
    boolean

    filterWidget(widgetConfig) → {boolean}

    Overrides filterWidget to check for a "renderFilter" attribute included in the supplied widget configuration. This is then used to determine whether or not the widget should be created or not.
    Parameters:
    Name Type Description
    widgetConfig object The configuration for the widget to be created
    Source:
    Returns:
    The result of the filter evaluation or true if no "renderFilter" is provided
    Type
    boolean

    getCustomRenderFilterProperty(renderFilter) → {string}

    Parameters:
    Name Type Description
    renderFilter Object The filter configuration to process.
    Source:
    Returns:
    The name of the filter
    Type
    string

    getProcessedWidgets(processWidgetsId) → {Array.<object>|promise}

    This function can be used to retrieve the widgets that have been processed by a call to processWidgets. It return a promise of the widgets that will be created an as such calls to this function should be protected through the use of dojo/when. It is not recommended to use this function, instead it is better to extend the [allWidgetsProcessed]allWidgetsProcessed function as this will only be called when widget processing has completed and is passed an argument of the widgets that were created.
    Parameters:
    Name Type Description
    processWidgetsId string The ID mapped to the original processWidgets call
    Since:
    • 1.0.36
    Source:
    Returns:
    The array of processed widgets or a promise of them
    Type
    Array.<object> | promise

    getRenderFilterPropertyValue(renderFilter) → {object}

    Processes the "filterProperty" attribute defined in the filter configuration (which is expected to be a dot notation path to an attribute of the currentItem. This property is then retrieved from currentItem and returned so that it can be compared against the "values" configuration. Retrieval of the
    Parameters:
    Name Type Description
    renderFilter Object The filter configuration to process.
    Source:
    Returns:
    The property of [currentItem]{@link module:alfresco/core/WidgetsProcessingFilterMixin#currentItem} defined by the "property" attribute of the filter configuration.
    Type
    object

    getRenderFilterValues(renderFilter) → {string[]}

    Attempt to convert the supplied filter value into an array. Filter values should be configured as an array of strings but this also allows single strings to be used (which are converted into a single element array) but if all else fails then an empty array will be returned.
    Parameters:
    Name Type Description
    renderFilter Object The filter configuration to process.
    Source:
    Returns:
    An array (assumed to be of strings) that is either empty, the same array supplied as an argument or a single string element supplied as an argument.
    Type
    string[]

    getWidgetProcessingLocation(processWidgetsId, prefix) → {string}

    This function is used to get the dot-notation property of the key attributes used when processing widgets. When a processWidgetsId is provided, the location will be a location within a map. The supplied prefix indicates the type of property required - this will either be the remaining count of widgets to process, the array of widgets processed so far or the promise of all the widgets when processing is complete.
    Parameters:
    Name Type Description
    processWidgetsId string The ID mapped to the original processWidgets call
    prefix string Expected to be either _processedWidgetsLocationPrefix or _processingWidgetsLocationPrefix
    Since:
    • 1.0.36
    Source:
    Returns:
    A dot-notation property to set or retrieve the processed widgets
    Type
    string

    onVisibilityProcessedFailure(widget)

    Called when visibility config on a widget has failed rule-evaluation.
    Parameters:
    Name Type Description
    widget object The widget under test
    Since:
    • 1.0.44
    Source:

    onVisibilityProcessedSuccess(widget)

    Called when visibility config on a widget has passed rule-evaluation.
    Parameters:
    Name Type Description
    widget object The widget under test
    Since:
    • 1.0.44
    Source:

    processAllFilters(filterConfig) → {boolean}

    Processes filter configuration. This looks for either "renderFilters" (e.g. a filter containing sub-filters) or "renderFilter" (i.e. a single filter containing one or more rules to evaluate). It then delegates processing to the appropriate function
    Parameters:
    Name Type Description
    filterConfig object The configuration to inspect
    Source:
    Returns:
    True if all filters have evaluated successfully and false otherwise.
    Type
    boolean

    processFilter(renderFilterConfig, target) → {boolean}

    This is called from the filterWidget function for each acceptable filter value and compares it against the supplied target value.
    Parameters:
    Name Type Description
    renderFilterConfig object The configuration for the filter
    target string | boolean | number The target object to match (ideally this should be a string, boolean or a number
    Source:
    Returns:
    true If the supplied value matches the target value and false otherwise.
    Type
    boolean

    processFilterArray(renderFilterConfig, targetArray, currValue) → {boolean}

    This function is used to compare the value of all the elements in the supplied targetArray against the value of the supplied currValue. If a match is found then this will return true.
    Parameters:
    Name Type Description
    renderFilterConfig object The complete configuration for the render filter
    targetArray array The array of values to compare against the supplied currValue
    currValue string | boolean The value to compare against all the elements in the targetArray
    Source:
    Returns:
    Indicates whether or not the supplied currValue has been found in the targetArray
    Type
    boolean

    processFilterConfig(renderFilterConfig, index) → {boolean}

    Parameters:
    Name Type Description
    renderFilterConfig object The filter configuration to process
    index number The index of the filter configuration
    Source:
    Returns:
    True if the filter criteria have been met and false otherwise.
    Type
    boolean

    processMultipleFilters(renderFilterConfig, renderFilterMethod) → {boolean}

    This function is used to to determine whether or not a filter containing multiple sub-filters evaluates to true. The sub-filters themselves can contain further nested filters.
    Parameters:
    Name Type Description
    renderFilterConfig object[] The configuration for the filter array
    renderFilterMethod string Either ANY or ALL
    Source:
    Returns:
    True if the filter passes and false otherwise
    Type
    boolean

    processSingleFilter(renderFilterConfig, renderFilterMethod) → {boolean}

    This function is used to to determine whether or not a single filter evaluates to true. Note that a single filter can consist of multiple rules where all rules or just one rule must evaluate to true in order for the filter to pass.
    Parameters:
    Name Type Description
    renderFilterConfig object[] The configuration for the filter array
    renderFilterMethod string Either ANY or ALL
    Source:
    Returns:
    True if the filter passes and false otherwise
    Type
    boolean

    processVisibility(widget, is, isNot, attribute, negate, payload)

    This function is called whenever a widget configured with a dynamic visibility rule is triggered by a publication. The configured rules are processed and the widget is displayed or hidden accordingly
    Parameters:
    Name Type Description
    widget object The widget to control the visibility of
    is array The values that the payload value can be for the widget to be visible
    isNot array The values that the payload value must not be for the widget to be visible
    attribute string The dot-notation attribute to retrieve from the payload
    negate boolean Whether or not the to negate the evaluated rule (e.g evaluated visible become invisible)
    payload object The publication payload triggering the visibility processing
    Deprecated:
    Source:

    processWidget(rootNode, processWidgetsId, widgetConfig, index)

    Creates a widget from the supplied configuration. The creation of each widgets DOM node is delegated to the createWidgetDomNode function and the actual instantiation of the widget is handled by the createWidget function. Before creation of the widget begins the filterWidget function is called to confirm that the widget should be created. This allows extending classes the opportunity filter out widget creation in specific circumstances.
    Parameters:
    Name Type Description
    rootNode element The DOM node where the widget should be created.
    processWidgetsId string An optional ID that might have been provided to map the results of multiple calls to processWidgets
    widgetConfig object The configuration for the widget to be created
    index number The index of the widget configuration in the array that it was taken from
    Source:

    processWidgetConfig(widget) → {object}

    This function is used to build the configuration used to instantiate a widget.
    Parameters:
    Name Type Description
    widget object The widget configuration build configuration for
    Source:
    Returns:
    The arguments that can be used when instantiating the widget configuration processed
    Type
    object

    processWidgets(widgets, rootNode, processWidgetsId)

    This function can be used to instantiate an array of widgets. Each widget configuration in supplied widgets array is passed to the processWidget function to handle it's creation.
    Parameters:
    Name Type Description
    widgets array An array of the widget definitions to instantiate
    rootNode element The DOM node which should be used to add instantiated widgets to
    processWidgetsId string An optional ID that might have been provided to map the results of the call to
    Support:
    • This function is safe to call by extending or mixing modules (at least until the next major release).
    Source:

    setupVisibilityConfigProcessing(widget, configAttribute, negate)

    Sets up the dynamic visibility handling for the supplied widget.
    Parameters:
    Name Type Description
    widget object The widget to process the config of
    configAttribute string The attribute to use in the widget config for rules
    negate boolean Whether or not to negate the evaluated rule
    Source:

    substituteFilterTokens(value) → {string}

    This function is called from both processFilter and processFilterArray to substitute any tokens found in the target values with matching dot-notation properties found in the currentItem and currentMetadata objects if they are available.
    Parameters:
    Name Type Description
    value * The value to look for tokens in
    Since:
    • 1.0.43
    Source:
    Returns:
    The value with any tokens substituted
    Type
    string

    visibilityRuleComparator(targetValue, useCurrentItem, currValue) → {boolean}

    This function compares the supplied values for equality. It is called from the processVisibility function to compare the current value with the configured rules for dynamically hiding and displaying a widget triggered by publications
    Parameters:
    Name Type Description
    targetValue string The target value supplied
    useCurrentItem boolean Indicates whether or not the values to check are attributes of the "currentItem"
    currValue string The value from the current rule being processed
    Deprecated:
    Source:
    Returns:
    true if the values match and false otherwise
    Type
    boolean