Class: module:argos/GroupedList

module:argos/GroupedList()

Grouped List provides a hook for grouping rows before rendering them to the page. The grouping adds a container for the set of rows and is collapsible. Note that it constructs the page sequentially meaning the rows should be in the correct order before attempting to group.

Constructor

new module:argos/GroupedList()

Extends:
Source:

Extends

Members

_groupBySections

Properties:
Name Type Description
The Object

current group object that is compared to the next entries group object Must have a tag property that identifies the group. The title property will be placed into the groupTemplate for the header text.

Source:

_loadedSelections

Cache of loaded selections

Inherited From:
Source:

_selectionConnects

Properties:
Name Type Description
The Object

selection event connections

Inherited From:
Source:

_selectionModel

Properties:
Name Type Description
The Object

selection model for the view

Inherited From:
Source:

actions

The list action layout definition for the list action bar.

Inherited From:
Source:

actionsNode

Properties:
Name Type Description
Attach HTMLElement

point for the list actions container

Inherited From:
Source:

allowSelection

Properties:
Name Type Description
True Boolean

to allow selections via the SelectionModel in the view.

Inherited From:
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.

Inherited From:
Source:

cancelText

Properties:
Name Type Description
The String

text displayed on the cancel button.

Inherited From:
Deprecated:
  • Yes
Source:

configureText

Properties:
Name Type Description
The String

text displayed for quick action configure.

Inherited From:
Source:

contentNode

Properties:
Name Type Description
Attach HTMLElement

point for the main view content

Inherited From:
Source:

contextView

Properties:
Name Type Description
The String

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

Inherited From:
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.

Inherited From:
Source:

currentSearchExpression

Properties:
Name Type Description
The String

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

Inherited From:
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.

Inherited From:
Source:

defaultSearchTerm

Properties:
Name Type Description
The String

default search term to use

Inherited From:
Source:

defaultSearchTermSet

Properties:
Name Type Description
Flag Boolean

to indicate the default search term has been set.

Inherited From:
Source:

detailView

Properties:
Name Type Description
The String/View

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

Inherited From:
Source:

editView

Properties:
Name Type Description
The String

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

Inherited From:
Source:

emptySelectionNode

Properties:
Name Type Description
Attach HTMLElement

point for the empty, or no selection, container

Inherited From:
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
Inherited From:
Source:

emptySelectionText

Properties:
Name Type Description
The String

text displayed in the emptySelection button.

Inherited From:
Source:

enableActions

Properties:
Name Type Description
Flag Boolean

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

Inherited From:
Source:

enableSearch

Properties:
Name Type Description
Controls Boolean

the addition of a search widget.

Inherited From:
Source:

errorHandlers

Properties:
Name Type Description
errorHandlers Array

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

Inherited From:
Source:

errorRenderText

Properties:
Name Type Description
The String

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

Inherited From:
Source:

groupTemplate

Properties:
Name Type Description
Simplate Simplate

that defines the Group template that includes the header element with collapse button and the row container

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.

Inherited From:
Source:

hasSettings

Properties:
Name Type Description
Indicates Boolean

if there is a list settings modal.

Inherited From:
Source:

hideSearch

Properties:
Name Type Description
Controls Boolean

the visibility of the search widget.

Inherited From:
Source:

id

Inherited From:
Source:

insertText

Properties:
Name Type Description
The String

text displayed on the insert button.

Inherited From:
Deprecated:
  • Yes
Source:

insertView

Properties:
Name Type Description
The String

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

Inherited From:
Source:

isCardView

Properties:
Name Type Description
Indicates Boolean

whether a template is a card view or a list

Inherited From:
Source:

itemIndicatorTemplate

Properties:
Name Type Description
The Simplate

template used to render item indicator

Inherited From:
Source:

itemRowContentTemplate

Properties:
Name Type Description
The Simplate

template used to render row content template

Inherited From:
Source:

itemTemplate

Inherited From:
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
Inherited From:
Source:

listActionTemplate

Properties:
Name Type Description
The Simplate

template used to render the single list action row.

Inherited From:
Source:

listLoading

Properties:
Name Type Description
Indicates Boolean

if the list is loading

Inherited From:
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.
Inherited From:
Source:

loadingText

Properties:
Name Type Description
The String

text displayed when data is being requested.

Inherited From:
Source:

modelName

Registered model name to use.

Inherited From:
Source:

moreNode

Properties:
Name Type Description
Attach HTMLElement

point for the request more entries container

Inherited From:
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
Overrides:
Source:

moreText :String

The text displayed in the more button.

Type:
  • String
Inherited From:
Source:

multiColumnClass

Properties:
Name Type Description
SoHo string

class to be applied on multi column.

Inherited From:
Source:

multiColumnCount

Properties:
Name Type Description
Number number

of columns in view

Inherited From:
Source:

multiColumnView

Properties:
Name Type Description
Flags Boolean

if the view is multi column or single column.

Inherited From:
Source:

newTooltipText

Properties:
Name Type Description
The String

text displayed in tooltip for the new button.

Inherited From:
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.
Inherited From:
Source:

noDataText

Properties:
Name Type Description
The String

text displayed when no records are available.

Inherited From:
Source:

pageSize

Properties:
Name Type Description
The Number

number of entries to request per SData payload.

Inherited From:
Source:

pullRefreshBannerTemplate

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

pullRefreshTemplate

Properties:
Type Description
Simplate
Inherited From:
Mixes In:
Source:

pullReleaseTemplate

Properties:
Type Description
Simplate
Inherited From:
Mixes In:
Source:

queryArgs

Inherited From:
Source:

queryInclude

Inherited From:
Source:

queryOrderBy

Overrides:
Source:

querySelect

Inherited From:
Source:

queryWhere

Inherited From:
Source:

quickActionConfigureView

Properties:
Name Type Description
The String

id of the configure view for quick action preferences

Inherited From:
Source:

refreshTooltipText

Properties:
Name Type Description
The String

text displayed in tooltip for the refresh button.

Inherited From:
Source:

remainingContentNode

Properties:
Name Type Description
Attach HTMLElement

point for the remaining entries content

Inherited From:
Source:

remainingNode

Properties:
Name Type Description
Attach HTMLElement

point for the remaining entries container

Inherited From:
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.

Inherited From:
Source:

request

Properties:
Name Type Description
request

Object SData request passed into the store. Optional.

Inherited From:
Source:

resourceKind

Inherited From:
Source:

resourcePredicate

Inherited From:
Source:

resourceProperty

Inherited From:
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.

Inherited From:
Source:

rowTemplateError

Properties:
Type Description
Simplate
Inherited From:
Source:

searchNode

Properties:
Name Type Description
Attach HTMLElement

point for the search widget

Inherited From:
Source:

searchWidget

Properties:
Name Type Description
The Object

search widget instance for the view

Inherited From:
Source:

searchWidgetClass

Properties:
Name Type Description
The SearchWidget

class constructor to use for the search widget

Inherited From:
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

Inherited From:
Source:

selectIconClass

Properties:
Name Type Description
CSS String

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

Inherited From:
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.

Inherited From:
Source:

tools

Properties:
Name Type Description
The Object

toolbar layout definition for all toolbar entries.

Inherited From:
Source:

utility

Properties:
Name Type Description
Maps Object

to Utility Class

Inherited From:
Source:

viewSettingsText

Properties:
Name Type Description
Creates Object

a setter map to html nodes, namely:

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

viewType

View type (detail, edit, list, etc)

Inherited From:
Source:

visibleActions

listbase calculated property based on actions available

Inherited From:
Source:

widgetTemplate

Properties:
Name Type Description
Simplate Simplate

that defines the HTML Markup. This override adds the needed styling.

Overrides:
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
Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

Inherited From:
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>
Inherited From:
Source:

createErrorHandlers() → {Array}

Inherited From:
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.

Inherited From:
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.

Inherited From:
Source:
Returns:

this.tools

Type
Object

destroy()

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

Inherited From:
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.

Inherited From:
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.

Inherited From:
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

formatRelatedQuery(entry, fmt, property) → {String}

Constructs a where expression using the provided format string and extracting the needed property from entry

Parameters:
Name Type Description
entry Object

Data point to extract from.

fmt String

Format string to be replaced where ${0} will be the extracted property.

property String

Property name to extract from the entry. May be a path: 'Address.City'.

Inherited From:
Source:
Returns:
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.

Inherited From:
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.

Inherited From:
Source:
Returns:

context.

Type
Object

getErrorMessage()

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

Inherited From:
Source:

getGroupForEntry(entry) → {Object}

Function that returns a "group object". The group object must have a tag property that is based off the passed entry as it will be used to compare to other entries. The title should also reflect the current entry as it will be used for the header text in the group splitter.

An example for a Yellow Page type list:

entryA = {first: 'Henry', last: 'Smith', phone: '123'} entryB = {first: 'Mary', last: 'Sue', phone: '345'}

groupGroupForEntry: function(entry) {
    var lastInitial = entry.last.substr(0,1).toUppperCase();
    return {
        tag: lastInitial,
        title: lastInitial
    };
}
Parameters:
Name Type Description
entry Object

The current entry being processed.

Source:
Returns:

Object that contains a tag and title property where tag will be used in comparisons

Type
Object

getListCount()

Returns a promise with the list's count.

Inherited From:
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

Inherited From:
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

Inherited From:
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.

Inherited From:
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.

Inherited From:
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

Inherited From:
Source:

invokeSingleSelectAction()

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

Inherited From:
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.

Inherited From:
Source:
Returns:
Type
Boolean

isSelectionDisabled() → {Boolean}

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

Inherited From:
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.

Inherited From:
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

Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

Inherited From:
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:

processFeed(feed)

Overwrites the parent processFeed to introduce grouping by group tags, see getGroupForEntry.

Parameters:
Name Type Description
feed Object

The SData feed result

Deprecated:
  • Use processData instead
Source:

refresh()

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

Inherited From:
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.

Inherited From:
Source:
Returns:

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

Type
Boolean

requestData()

Initiates the data request.

Inherited From:
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.

Inherited From:
Source:

setSearchTerm()

Sets the query value on the serach widget

Inherited From:
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.

Inherited From:
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.

Inherited From:
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

Inherited From:
Source:

startup()

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

Overrides:
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.

Inherited From:
Source: