Class: module:argos/_ListBase

module:argos/_ListBase(options)

A List View is a view used to display a collection of entries in an easy to skim list. The List View also has a selection model built in for selecting rows from the list and may be used in a number of different manners.

Constructor

new module:argos/_ListBase(options)

Extends:
Parameters:
Name Type Description
options Object
Mixes In:
Source:

Extends

Members

_loadedSelections

Cache of loaded selections

Source:

_selectionConnects

Properties:
Name Type Description
The Object

selection event connections

Source:

_selectionModel

Properties:
Name Type Description
The Object

selection model for the view

Source:

actions

The list action layout definition for the list action bar.

Source:

actionsNode

Properties:
Name Type Description
Attach HTMLElement

point for the list actions container

Source:

allowSelection

Properties:
Name Type Description
True Boolean

to allow selections via the SelectionModel in the view.

Source:

app

A reference to the global App object

Inherited From:
Source:

autoClearSelection

Properties:
Name Type Description
True Boolean

to clear the selection model when the view is shown.

Source:

cancelText

Properties:
Name Type Description
The String

text displayed on the cancel button.

Deprecated:
  • Yes
Source:

configureText

Properties:
Name Type Description
The String

text displayed for quick action configure.

Source:

contentNode

Properties:
Name Type Description
Attach HTMLElement

point for the main view content

Source:

contextView

Properties:
Name Type Description
The String

view id to show when the #navigateToContextView action is invoked.

Source:

continuousScrolling

Properties:
Name Type Description
If Boolean

true, will remove the loading button and auto fetch more data when the user scrolls to the bottom of the page.

Source:

currentSearchExpression

Properties:
Name Type Description
The String

current search term being used for the current requestData().

Source:

customizationSet

Properties:
Name Type Description
The String

customization identifier for this class. When a customization is registered it is passed a path/identifier which is then matched to this property.

Source:

defaultSearchTerm

Properties:
Name Type Description
The String

default search term to use

Source:

defaultSearchTermSet

Properties:
Name Type Description
Flag Boolean

to indicate the default search term has been set.

Source:

detailView

Properties:
Name Type Description
The String/View

id of the detail view, or view instance, to show when a row is clicked.

Source:

editView

Properties:
Name Type Description
The String

view id to show if there is no insertView specified, when the #navigateToInsertView action is invoked.

Source:

emptySelectionNode

Properties:
Name Type Description
Attach HTMLElement

point for the empty, or no selection, container

Source:

emptySelectionTemplate

Properties:
Name Type Description
Template Simplate

used on lookups to have empty Selection option. This template is not directly rendered but included in #viewTemplate.

The default template uses the following properties:

 name                description
 ----------------------------------------------------------------
 emptySelectionText  The text to display on the empty Selection button.

The default template exposes the following actions:

  • emptySelection
Source:

emptySelectionText

Properties:
Name Type Description
The String

text displayed in the emptySelection button.

Source:

enableActions

Properties:
Name Type Description
Flag Boolean

that determines if the list actions panel should be in use.

Source:

enableSearch

Properties:
Name Type Description
Controls Boolean

the addition of a search widget.

Source:

errorHandlers

Properties:
Name Type Description
errorHandlers Array

Array of objects that should contain a name string property, test function, and handle function.

Overrides:
Source:

errorRenderText

Properties:
Name Type Description
The String

error message to display if rendering a row template is not successful.

Source:

hashTagQueries

Properties:
Name Type Description
A Object

dictionary of hash tag search queries. The key is the hash tag, without the symbol, and the value is either a query string, or a function that returns a query string.

Source:

hasSettings

Properties:
Name Type Description
Indicates Boolean

if there is a list settings modal.

Source:

hideSearch

Properties:
Name Type Description
Controls Boolean

the visibility of the search widget.

Source:

id

Overrides:
Source:

insertText

Properties:
Name Type Description
The String

text displayed on the insert button.

Deprecated:
  • Yes
Source:

insertView

Properties:
Name Type Description
The String

view id to show when the #navigateToInsertView action is invoked.

Source:

isCardView

Properties:
Name Type Description
Indicates Boolean

whether a template is a card view or a list

Source:

itemIndicatorTemplate

Properties:
Name Type Description
The Simplate

template used to render item indicator

Source:

itemRowContentTemplate

Properties:
Name Type Description
The Simplate

template used to render row content template

Source:

itemTemplate

Source:

listActionItemTemplate

Properties:
Name Type Description
The Simplate

template used to render a list action item. The default template uses the following properties:

 name                description
 ----------------------------------------------------------------
 actionIndex         The correlating index number of the action collection
 title               Text used for ARIA-labeling
 icon                Relative path to the icon to use
 cls                 CSS class to use instead of an icon
 id                  Unique name of action, also used for alt image text
 label               Text added below the icon
Source:

listActionTemplate

Properties:
Name Type Description
The Simplate

template used to render the single list action row.

Source:

listLoading

Properties:
Name Type Description
Indicates Boolean

if the list is loading

Source:

loadingTemplate

Properties:
Name Type Description
The Simplate

template used to render the loading message when the view is requesting more data.

The default template uses the following properties:

 name                description
 ----------------------------------------------------------------
 loadingText         The text to display while loading.
Source:

loadingText

Properties:
Name Type Description
The String

text displayed when data is being requested.

Source:

modelName

Registered model name to use.

Inherited From:
Source:

moreNode

Properties:
Name Type Description
Attach HTMLElement

point for the request more entries container

Source:

moreTemplate

Properties:
Name Type Description
The Simplate

template used to render the pager at the bottom of the view. This template is not directly rendered, but is included in #viewTemplate.

The default template uses the following properties:

 name                description
 ----------------------------------------------------------------
 moreText            The text to display on the more button.

The default template exposes the following actions:

  • more
Source:

moreText :String

The text displayed in the more button.

Type:
  • String
Source:

multiColumnClass

Properties:
Name Type Description
SoHo string

class to be applied on multi column.

Source:

multiColumnCount

Properties:
Name Type Description
Number number

of columns in view

Source:

multiColumnView

Properties:
Name Type Description
Flags Boolean

if the view is multi column or single column.

Source:

newTooltipText

Properties:
Name Type Description
The String

text displayed in tooltip for the new button.

Source:

noDataTemplate

Properties:
Name Type Description
The Simplate

template used to render a message if there is no data available. The default template uses the following properties:

 name                description
 ----------------------------------------------------------------
 noDataText          The text to display if there is no data.
Source:

noDataText

Properties:
Name Type Description
The String

text displayed when no records are available.

Source:

pageSize

Properties:
Name Type Description
The Number

number of entries to request per SData payload.

Source:

pullRefreshBannerTemplate

Properties:
Type Description
external:Simplate
Mixes In:
Source:

pullRefreshTemplate

Properties:
Type Description
Simplate
Mixes In:
Source:

pullReleaseTemplate

Properties:
Type Description
Simplate
Mixes In:
Source:

quickActionConfigureView

Properties:
Name Type Description
The String

id of the configure view for quick action preferences

Source:

refreshTooltipText

Properties:
Name Type Description
The String

text displayed in tooltip for the refresh button.

Source:

remainingContentNode

Properties:
Name Type Description
Attach HTMLElement

point for the remaining entries content

Source:

remainingNode

Properties:
Name Type Description
Attach HTMLElement

point for the remaining entries container

Source:

remainingText

Properties:
Name Type Description
The String

format string for the text displayed for the remaining record count. This is used in a String#format call.

Source:

resourceKind

Source:

route

Properties:
Name Type Description
Route String

passed into the router. RegEx expressions are also accepted.

Inherited From:
Source:

rowTemplate

Properties:
Name Type Description
The Simplate

template used to render a row in the view. This template includes #itemTemplate.

Source:

rowTemplateError

Properties:
Type Description
Simplate
Source:

searchNode

Properties:
Name Type Description
Attach HTMLElement

point for the search widget

Source:

searchWidget

Properties:
Name Type Description
The Object

search widget instance for the view

Source:

searchWidgetClass

Properties:
Name Type Description
The SearchWidget

class constructor to use for the search widget

Source:

security

May be defined along with Application hasAccessTo to incorporate View restrictions.

Inherited From:
Source:

selectIcon

Properties:
Name Type Description
The String

relative path to the checkmark or select icon for row selector

Source:

selectIconClass

Properties:
Name Type Description
CSS String

class to use for checkmark or select icon for row selector. Overrides selectIcon.

Source:

serviceName

May be used to specify the service name to use for data requests. Setting false will force the use of the default service.

Properties:
Type Description
String/Boolean
Inherited From:
Source:

titleText

Properties:
Name Type Description
The String

text displayed as the default title.

Overrides:
Source:

tools

Properties:
Name Type Description
The Object

toolbar layout definition for all toolbar entries.

Overrides:
Source:

utility

Properties:
Name Type Description
Maps Object

to Utility Class

Source:

viewSettingsText

Properties:
Name Type Description
Creates Object

a setter map to html nodes, namely:

  • listContent => contentNode's innerHTML
  • remainingContent => remainingContentNode's innerHTML
Source:

viewType

View type (detail, edit, list, etc)

Inherited From:
Source:

visibleActions

listbase calculated property based on actions available

Source:

widgetTemplate

Properties:
Name Type Description
The Simplate

template used to render the view's main DOM element when the view is initialized. This template includes emptySelectionTemplate, moreTemplate and listActionTemplate.

The default template uses the following properties:

 name                description
 ----------------------------------------------------------------
 id                   main container div id
 title                main container div title attr
 cls                  additional class string added to the main container div
 resourceKind         set to data-resource-kind
Source:

Methods

_applyStateToActions(selection)

Called from checkActionState method and sets the state of the actions from what was selected from the selected row, it sets the disabled state for each action item using the currently selected row as context by passing the action instance the selected row to the action items enabled property.

Parameters:
Name Type Description
selection Object
Source:

activateEntry(params)

Handler for each row.

If a selection model is defined and navigation is disabled then toggle the entry/row in the model and if singleSelectionAction is true invoke the singleSelectAction.

Else navigate to the detail view for the extracted data-key.

Parameters:
Name Type Description
params Object

Collection of data- attributes from the node.

Source:

beforeTransitionAway()

Called before the view is transitioned (slide animation complete) away from.

Inherited From:
Source:

beforeTransitionTo()

Extends the parent implementation by also toggling the visibility of the views components and clearing the view and selection model as needed.

Overrides:
Source:

buildRoute() → {String}

Show method calls this to build a route that it can navigate to. If you add a custom route, this should change to build a route that can match that.

Inherited From:
Source:
Returns:
Type
String

checkActionState()

Called when showing the action bar for a newly selected row, it sets the disabled state for each action item using the currently selected row as context by passing the action instance the selected row to the action items enabled property.

Source:

clear(all)

Clears the view by:

  • clearing the selection model, but without it invoking the event handlers;
  • clears the views data such as this.entries and this.entries;
  • clears the search width if passed true; and
  • applies the default template.
Parameters:
Name Type Description
all Boolean

If true, also clear the search widget.

Source:

configureSearch()

Sets the default search expression (acting as a pre-filter) to this.options.query and configures the search widget by passing in the current view context.

Source:

createActionLayout() → {Object}

Sets and returns the list-action actions layout definition, this method should be overriden in the view so that you may define the action entries for that view.

Source:
Returns:

this.acttions

Type
Object

createActions(actions)

Creates the action bar and adds it to the DOM. Note that it replaces this.actions with the passed param as the passed param should be the result of the customization mixin and this.actions needs to be the final actions state.

Parameters:
Name Type Description
actions Array.<Object>
Source:

createErrorHandlers() → {Array}

Overrides:
Source:
Returns:

Returns an array of error handlers

Type
Array

createHashTagQueryLayout() → {Array.<Object>}

Generates the hash tag layout by taking the hash tags defined in this.hashTagQueries and converting them into individual objects in an array to be used in the customization engine.

Source:
Returns:
Type
Array.<Object>

createToolLayout() → {Object}

Sets and returns the toolbar item layout definition, this method should be overriden in the view so that you may define the views toolbar entries.

Overrides:
Source:
Returns:

this.tools

Type
Object

destroy()

Extends dijit Widget to destroy the search widget before destroying the view.

Source:

emptySelection()

Handler for the none/no selection button is pressed. Used in selection views when not selecting is an option. Invokes the this.options.singleSelectAction tool.

Source:

escapeSearchQuery(searchQuery) → {String}

Replaces a single " with two "" for proper SData query expressions.

Parameters:
Name Type Description
searchQuery String

Search expression to be escaped.

Source:
Returns:
Type
String

expandExpression(expression) → {String}

Expands the passed expression if it is a function.

Parameters:
Name Type Description
expression String/Function

Returns string directly, if function it is called and the result returned.

Inherited From:
Source:
Returns:

String expression.

Type
String

formatSearchQuery(searchQuery) → {String/Boolean}

Called to transform a textual query into an SData query compatible search expression.

Views should override this function to provide their own formatting tailored to their entity.

Parameters:
Name Type Description
searchQuery String

User inputted text from the search widget.

Source:
Returns:

An SData query compatible search expression.

Type
String/Boolean

getContext() → {Object}

Returns the current views context by expanding upon the parent implementation to include the views resourceKind.

Overrides:
Source:
Returns:

context.

Type
Object

getErrorMessage()

Gets the general error message, or the error message for the status code.

Inherited From:
Source:

getListCount()

Returns a promise with the list's count.

Source:

getModel()

Returns a new instance of a model for the view.

Inherited From:
Source:

getOptionsContext() → {Object}

Returns the options used for the View getContext().

Inherited From:
Source:
Returns:

Options to be used for context.

Type
Object

getRoute()

Gets the route associated with this view. Returns this.id if no route is defined.

Inherited From:
Source:

getSecurity(access)

Returns the defined security.

Parameters:
Name Type Description
access
Inherited From:
Source:

getService() → {Object}

Returns the primary SDataService instance for the view.

Inherited From:
Source:
Returns:

The Sage.SData.Client.SDataService instance.

Type
Object

getTitle()

Sets the title to card

Source:

getTools() → {Object}

Called from Applications view transition handler and returns the fully customized toolbar layout.

Inherited From:
Source:
Returns:

The toolbar layout

Type
Object

getUnloadedSelections() → {Array}

Returns this.options.previousSelections that have not been loaded or paged to

Source:
Returns:
Type
Array

handleError(error)

Starts matching and executing errorHandlers.

Parameters:
Name Type Description
error Error

Error to pass to the errorHandlers

Inherited From:
Source:

hasMoreData() → {Boolean}

Deterimines if there is more data to be shown.

Source:
Returns:

True if the list has more data; False otherwise. Default is true.

Type
Boolean

hideActionPanel(rowNode)

Parameters:
Name Type Description
rowNode HTMLElement

The currently selected row.

Deprecated:
  • Hides the passed list-action row/panel by removing the selected styling
Source:

init()

Called on loading of the application.

Inherited From:
Source:

initConnects()

Establishes this views connections to various events

Inherited From:
Source:

initModel()

Initializes the model instance that is returned with the current view.

Inherited From:
Source:

invokeActionItem(parameters, evt, node)

This is the data-action handler for list-actions, it will locate the action instance viw the data-id attribute and invoke either the fn with scope or the named action on the current view.

The resulting function being called will be passed not only the action item definition but also the first (only) selection from the lists selection model.

Parameters:
Name Type Description
parameters Object

Collection of data- attributes already gathered from the node

evt Event

The click/tap event

node HTMLElement

The node that invoked the action

Source:

invokeSingleSelectAction()

Invokes the corresponding top toolbar tool using this.options.singleSelectAction as the name. If autoClearSelection is true, clear the selection model.

Source:

isDisabled() → {Boolean}

Returns true if view is disabled.

Inherited From:
Source:
Returns:

.

Type
Boolean

isNavigationDisabled() → {Boolean}

Determines if the view is a navigatible view or a selection view by returning this.selectionOnly or the navigation this.options.selectionOnly.

Source:
Returns:
Type
Boolean

isSelectionDisabled() → {Boolean}

Determines if the selections are disabled by checking the allowSelection and enableActions

Source:
Returns:
Type
Boolean

load()

Called once the first time the view is about to be transitioned to.

Inherited From:
Deprecated:
  • Yes
Source:

more()

Handler for the more button. Simply calls requestData which already has the info for setting the start index as needed.

Source:

Navigates to the defined this.detailView passing the params as navigation options.

Parameters:
Name Type Description
key String

Key of the entry to be shown in detail

descriptor String

Description of the entry, will be used as the top toolbar title text

additionalOptions Object

Additional options to be passed into the next view

Source:

Helper method for list-actions. Navigates to the defined this.editView passing the given selections idProperty property in the navigation options (which is then requested and result used as default data).

Parameters:
Name Type Description
action Object

Action instance, not used.

selection Object

Data entry for the selection.

additionalOptions Object

Additional options to be passed into the next view.

Source:

Navigates to the defined this.insertView, or this.editView passing the current views id as the returnTo option and setting insert to true.

Parameters:
Name Type Description
additionalOptions Object

Additional options to be passed into the next view.

Source:

Helper method for list actions. Takes a view id, data point and where format string, sets the nav options where to the formatted expression using the data point and shows the given view id with that option.

Parameters:
Name Type Description
action Object

Action instance, not used.

selection Object

Data entry for the selection.

viewId String

View id to be shown

whereQueryFmt String

Where expression format string to be passed. ${0} will be the idProperty

additionalOptions Object

Additional options to be passed into the next view property of the passed selection data.

Source:

onActivate(self)

The onActivate event.

Parameters:
Name Type Description
self
Inherited From:
Source:

onBeforeTransitionAway(self)

The onBeforeTransitionAway event.

Parameters:
Name Type Description
self
Inherited From:
Source:

onBeforeTransitionTo(self)

The onBeforeTransitionTo event.

Parameters:
Name Type Description
self
Inherited From:
Source:

onShow(self)

The onShow event.

Parameters:
Name Type Description
self
Inherited From:
Source:

onToolLayoutCreated()

Called after toolBar layout is created;

Inherited From:
Source:

onTransitionAway(self)

The onTransitionAway event.

Parameters:
Name Type Description
self
Inherited From:
Source:

onTransitionTo(self)

The onTransitionTo event.

Parameters:
Name Type Description
self
Inherited From:
Source:

open()

Available Options: horizontal: True if the transition is horizontal, False otherwise. reverse: True if the transition is a reverse transition (right/down), False otherwise. track: False if the transition should not be tracked in history, True otherwise. update: False if the transition should not update title and back button, True otherwise. scroll: False if the transition should not scroll to the top, True otherwise.

Inherited From:
Source:

refresh()

Called when the view needs to be reset. Invokes the request data process.

Overrides:
Source:

refreshRequiredFor(options) → {Boolean}

Determines if the view should be refresh by inspecting and comparing the passed navigation options with current values.

Parameters:
Name Type Description
options Object

Passed navigation options.

Overrides:
Source:
Returns:

True if the view should be refreshed, false if not.

Type
Boolean

requestData()

Initiates the data request.

Source:

routeLoad(ctx, next)

Fires first when a route is triggered. Any pre-loading should happen here.

Parameters:
Name Type Description
ctx Object
next function
Inherited From:
Source:

routeShow(ctx, next)

Fires second when a route is triggered. Any pre-loading should happen here.

Parameters:
Name Type Description
ctx Object
next function
Inherited From:
Source:

selectEntry(params, evt, node)

Handler for the select or action node data-action. Finds the nearest node with the data-key attribute and toggles it in the views selection model.

If singleSelectAction is defined, invoke the singleSelectionAction.

Parameters:
Name Type Description
params Object

Collection of data- attributes from the node.

evt Event

The click/tap event.

node HTMLElement

The element that initiated the event.

Source:

setSearchTerm()

Sets the query value on the serach widget

Source:

setSource(source)

Sets the this.options.source to passed param after adding the views resourceKind. This function is used so that when the next view queries the navigation context we can include the passed param as a data point.

Parameters:
Name Type Description
source Object

The object to set as the options.source.

Source:

show(options, transitionOptions)

Shows overrides the view class to set options for the list view and then calls the inherited show method on the view.

Parameters:
Name Type Description
options Object

The navigation options passed from the previous view.

transitionOptions Object

Optional transition object that is forwarded to ReUI.

Overrides:
Source:

showActionPanel(rowNode)

Handler for showing the list-action panel/bar - it needs to do several things:

  1. Check each item for context-enabledment
  2. Move the action panel to the current row and show it
  3. Adjust the scrolling if needed (if selected row is at bottom of screen, the action-bar shows off screen which is bad)
Parameters:
Name Type Description
rowNode HTMLElement

The currently selected row node

Source:

startup()

Called on application startup to configure the search widget if present and create the list actions.

Source:

transitionAway()

Called after the view has been transitioned (slide animation complete) away from.

Inherited From:
Source:

transitionTo()

Extends the parent implementation to also configure the search widget and load previous selections into the selection model.

Overrides:
Source: