Class: module:argos/Fields/LookupField

module:argos/Fields/LookupField()

The LookupField is similiar to an Edit View in that it is a field that takes the user to another view but the difference is that an EditorField takes the user to an Edit View, whereas LookupField takes the user to a List View.

Meaning that LookupField is meant for establishing relationships by only storing the key for a value and with displayed text.

Constructor

new module:argos/Fields/LookupField()

Extends:
Source:
Example
{
  name: 'Owner',
  property: 'Owner',
  label: this.ownerText,
  type: 'lookup',
  view: 'user_list'
}

Extends

Members

alwaysUseValue

Properties:
Name Type Description
alwaysUseValue Boolean

Signifies that the field should always be included when the form calls getValues.

Inherited From:
Source:

applyTo

Properties:
Name Type Description
applyTo String

If defined it will use the applyTo string when getting and setting properties from the SData object instead of the property property.

Inherited From:
Source:

attributeMap

Properties:
Name Type Description
Creates Object

a setter map to html nodes, namely:

  • inputValue => inputNodes's value
  • inputDisabled => inputNodes's disabled
  • inputReadOnly => inputNodes readonly
Source:

autoFocus

Properties:
Name Type Description
autoFocus Boolean

Flag to indicate if this field should be focused when the form is shown.

Inherited From:
Source:

cancelText

Properties:
Name Type Description
The String

tooltip text for cancelling the selection

Source:

completeText

Properties:
Name Type Description
The String

tooltip text for saving the selection

Source:

containerNode

Properties:
Name Type Description
The HTMLElement

parent container element of the field.

Inherited From:
Source:

currentSelection

Properties:
Name Type Description
The Object

entire selected entry from the target view (not just the key/text properties).

Source:

currentValue

Properties:
Name Type Description
The Object

current value object defined using the extracted key/text properties from the selected entry.

Source:

default

This applies a default value when inserting a new record, the default value is applied after the template entry but before the context and changes are applied.

Note the word default must be in quotes as default is a reserved word in javascript.

Inherited From:
Source:

dependentErrorText

Properties:
Name Type Description
Error String

text shown when validation fails.

  • ${0} is the label text of the field
Source:

dependsOn

Source:

disabled

Properties:
Name Type Description
disabled Boolean

Indicates the disabled state

Inherited From:
Source:

emptyText

Source:

hidden

Properties:
Name Type Description
hidden Boolean

Indicates the visibility state

Inherited From:
Source:

keyProperty

Properties:
Name Type Description
The String

default valueKeyProperty if valueKeyProperty is not defined.

Source:

label

Properties:
Name Type Description
label String

The text that will, by default, show to the left of a field.

Inherited From:
Source:

lookupLabelText

Properties:
Name Type Description
The String

ARIA label text in the lookup button

Source:

lookupText

Properties:
Name Type Description
The String

text placed inside the lookup button

Source:

name

Properties:
Name Type Description
name String

The unique (within the current form) name of the field

Inherited From:
Source:

orderBy

Source:

owner

Properties:
Name Type Description
owner View

View that controls the field.

Inherited From:
Source:

property

Properties:
Name Type Description
property String

The SData property that the field will be bound to.

Inherited From:
Source:

required :Boolean

required should be true if the field requires input. Defaults to false.

Type:
  • Boolean
Source:

requireSelection

Source:

resourceKind

Source:

resourcePredicate

Source:

singleSelect

Properties:
Name Type Description
Sets Boolean

the singleSelect navigation option and if true limits gather the value from the target list view to the first selection.

Source:

singleSelectAction

Properties:
Name Type Description
The String

data-action of the toolbar item (which will be hidden) sent in navigation options. This with singleSelect is listened to in List so clicking a row invokes the action, which is the function name defined (on the field instance in this case).

Source:

textProperty

Properties:
Name Type Description
The String

default valueTextProperty if valueTextProperty is not defined.

Source:

textRenderer

Source:

textTemplate

Source:

type

Properties:
Name Type Description
type String

The registered name of the field that gets mapped in FieldManager when the field is constructed

Inherited From:
Source:

valueKeyProperty

Source:

valueTextProperty

Source:

view

Source:

viewMixin

Source:

where

Source:

widgetTemplate

Properties:
Name Type Description
Simplate Simplate

that defines the fields HTML Markup

  • $ => Field instance
  • $$ => Owner View instance
Overrides:
Source:

Methods

_onBlur(evt)

Handler for onblur, fires onNotificationTrigger if this.notificationTrigger is 'blur'.

Parameters:
Name Type Description
evt Event

Blur event

Source:

_onClick(evt)

Handler for the click event, fires navigateToListView if the field is not disabled.

Parameters:
Name Type Description
evt
Source:

_onComplete()

Forces onChange to fire

Source:

_onKeyUp(evt)

Handler for onkeyup, fires onNotificationTrigger if this.notificationTrigger is 'keyup'.

Parameters:
Name Type Description
evt Event

Click event

Source:

buildRendering()

Processes this.widgetTemplate or this.contentTemplate

Inherited From:
Source:

clearValue(flag)

Clears the value by setting null (which triggers usage of this.emptyText.

Flag is used to indicate if to set null as the initial value (unmodified) or not.

Parameters:
Name Type Description
flag Boolean
Overrides:
Source:

complete()

Called from the target list view when a row is selected.

The intent of the complete function is to gather the value(s) from the list view and transfer them to the field - then handle navigating back to the Edit view.

The target view must be the currently active view and must have a selection model.

The values are gathered and passed to setSelection, ReUI.back() is fired and lastly _onComplete is called in a setTimeout due to bizarre transition issues, namely in IE.

Source:

createNavigationOptions()

Creates the options to be passed in navigation to the target view

Key points of the options set by default:

  • enableActions = false, List views should not be showing their list-actions bar this hides it
  • selectionOnly = true, List views should not allow editing/viewing, just selecting
  • negateHistory = true, disables saving of this options object when storing the history context
  • tools = {}, overrides the toolbar of the target view so that the function that fires is invoked in the context of this field, not the List.

The following options are "expandable" meaning they can be strings or functions that return strings:

resourceKind, resourcePredicate, where and previousSelections

They will be passed the dependsOn field value (if defined).

Source:

disable()

Extends disable to also set the disabled attribute

Overrides:
Source:

enable()

Extends enable to also remove the disabled attribute

Overrides:
Source:

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.

Source:
Returns:

String expression.

Type
String

focus()

Focuses the input for the field

Overrides:
Source:

formatValue(values) → {Object/String}

If using a multi-select enabled lookup then the view will return multiple objects as the value.

This function takes that array and returns the single value that should be used for this.currentValue.

Parameters:
Name Type Description
values Array.<Object>
Source:
Returns:
Type
Object/String

getDependentLabel() → {String}

Retrieves the label string of the field named with this.dependsOn

Source:
Returns:
Type
String

getDependentValue() → {String/Object/Number/Boolean}

Retrieves the value of the field named with this.dependsOn

Source:
Returns:
Type
String/Object/Number/Boolean

getSelection() → {Object}

Returns the current selection that was set from the target list view.

Source:
Returns:
Type
Object

getText() → {String}

Returns the string text of the field (note, not the value of the field)

Source:
Returns:
Type
String

getValue() → {Object/String}

Returns the current value either by extracting the valueKeyProperty and valueTextProperty or several other methods of getting it to that state.

Overrides:
Source:
Returns:
Type
Object/String

hide()

Sets hidden to true and fires onHide.

Inherited From:
Source:

init()

Extends init to connect to the click event, if the field is read only disable and if require selection is false connect to onkeyup and onblur.

Overrides:
Source:

isDirty() → {Boolean}

Determines if the field has been altered from the default/template value.

Overrides:
Source:
Returns:
Type
Boolean

isDisabled() → {Boolean}

Returns the disabled state

Inherited From:
Source:
Returns:
Type
Boolean

isHidden() → {Boolean}

Returns the hidden state

Inherited From:
Source:
Returns:
Type
Boolean

isReadOnly() → {Boolean}

Determines if the field is readonly by checking for a target view

Source:
Returns:
Type
Boolean

Navigates to the this.view id passing the options created from createNavigationOptions.

Source:

onChange(field)

Event that fires when the field is changed

Parameters:
Name Type Description
field _Field

The field itself

Inherited From:
Source:

onDisable(field)

Event that fires when the field is disabled

Parameters:
Name Type Description
field _Field

The field itself

Inherited From:
Source:

onEnable(field)

Event that fires when the field is enabled

Parameters:
Name Type Description
field _Field

The field itself

Inherited From:
Source:

onHide(field)

Event that fires when the field is hidden

Parameters:
Name Type Description
field _Field

The field itself

Inherited From:
Source:

onNotificationTrigger(evt)

Called from onkeyup and onblur handlers if the trigger is set.

Checks the current value against this.previousValue and if different fires onChange.

Parameters:
Name Type Description
evt Event
Source:

onShow(field)

Event that fires when the field is shown

Parameters:
Name Type Description
field _Field

The field itself

Inherited From:
Source:

renderTo(node)

Inserts the field into the given DOM node using dijit Widget placeAt(node) and saves a reference to it to this.containerNode.

Parameters:
Name Type Description
node HTMLElement

Target node to insert the field into

Inherited From:
Source:

setSelection(val, key)

If using a singleSelect enabled lookup this function will be called by complete and the single entry's data and key will be passed to this function.

Sets the this.currentSelection to the passed data (entire entry)

Sets the this.currentValue to the extract key/text properties

Calls setText with the extracted text property.

Parameters:
Name Type Description
val Object

Entire selection entry

key String

data-key attribute of the selected row (typically $key from SData)

Source:

setSelections(values, unloadedValues)

If using a multi-select enabled lookup this function will be called by complete in that the target view returned multiple entries.

Sets the currentValue using formatValue.

Sets the displayed text using this.textRenderer.

Parameters:
Name Type Description
values Array.<Object>
unloadedValues Array.<Object>

option.previousSelections that were not loaded by the view.

Source:

setText(text)

Sets the displayed text of the field

Parameters:
Name Type Description
text String
Source:

setValue(val, initial)

Sets the given value to this.currentValue using the initial flag if to set it as clean/unmodified or false for dirty.

Parameters:
Name Type Description
val Object/String

Value to set

initial Boolean

Dirty flag (true is clean)

Overrides:
Source:

show()

Sets hidden to false and fires onShow.

Inherited From:
Source:

validate(value) → {Boolean/Object}

The validate function determines if there is any errors - meaning it will return false for a "Error free" field.

###Basic Flow:

  • loops over each validator defined on the field

  • Evaluate the result

    • If the validator is a RegExp, use return !regExp.test(value)
    • If the validator is a function, call and return the result of the function passing the value, _Field instance, and the owner property.
    • If the validator is an object and has a test key, follow the RegExp path.
    • If the validator is an object and has a fn key, follow the function path.
  • If the result is true and the validator is an object with a message key:

    • If message is a function, call and return the result of the function passing the value, _Field instance and the owner property.
    • Otherwise, assume it is a string format and call dojo's string.substitute using the message as the format, ${0} as the value, ${1} as the fields name, ${2} as the fields label property.
    • Save the result of the function or string substitution as the result itself.
  • Return the result.

Parameters:
Name Type Description
value

Value of the field, if not passed then getValue is used.

Inherited From:
Source:
Returns:

False signifies that everything is okay and the field is valid, true or a string message indicates that it failed.

Type
Boolean/Object