Pre-General Availability: 2018-5-8

Widget: recordView

QuickNav

Options

Methods

recordView

RecordView is a dynamically generated form for editing a record from an APEX view model. It uses standard APEX column items to display and edit record fields.

The markup expected by this widget is simply an empty div. The record view displays and optionally edits data stored in an APEX view model (see apex.model namespace). If the record view is editable then the div must be proceeded by a div with class "u-vh" (to visually hide the contents) that contains each of the rendered column items. Each column item needs to be wrapped in a div with class a-GV-columnItem. See the markup in the xxx example.

Functional css takes care of hiding the column items off screen.

RecordView is designed to share the same column/field configuration and column items with a grid widget but it can also be used standalone. What the grid widget calls column configuration recordView calls field configuration.

xxx Field configuration: xxx can have groups

Editing

The record view can be editable or not editable. This is controlled by the editable option. If not editable then no UI is provided to do any editing, however it will still respond to any changes to the model data. The editable property can be changed after the record view is created provided the necessary column items are available on the page. See the model documentation for how it can be used to provide fine grained control over what kinds of edits are allowed. The field definition can specify fields that are read-only.

Column Edit Items: When the record view is editable and a field can be edited, it is a column item that does the editing. Column items are essentially the same as page items except they edit a column/field value rather than a page item. A grid and recordView on the same page can share the same column items as long as the two widgets are not visible or actively in edit mode at the same time.

Initializer

$(".selector").recordView(options)

Creates a recordView widget.
Parameters:
Name Type Description
options Object A map of option-value pairs to set on the widget.
Since:
  • 5.1
Example

Create a xxx.

HTML:
   <div class="a-GV-columnItemContainer u-vh" aria-hidden="true">
   <div class="u-vh" aria-hidden="true">
       <div class="a-GV-columnItem">column item markup goes here</div>
       ...
   </div>

Extends

Options

actionsContext :actions

Actions context to use. If not provided a new context is created. Specifying a context allows this widget to be contained within another one and share the same context.

Type:

alwaysEdit :boolean

Only applies if editable is true. If true, the recordView will start out in edit mode and double click, enter, and escape will not change the mode. Calling setEditMode(false) can still change the edit mode.

Type:
  • boolean
Default Value:
  • false

autoAddRecord :boolean

Specifies if a new record should be automatically added when the model doesn't contain any data. If supported by the derived view a new record may be added when moving beyond the last record in the view while editing. Must only be true if the model and view are editable and the model allows adding records.

Type:
  • boolean
Inherited From:
Default Value:
  • false

editable :boolean

Determine if the view allows editing. This is independent of the model editability. If true the view data can be edited according to what the model allows. Only applies if the view supports editing.

Type:
  • boolean
Inherited From:
Default Value:
  • false

fieldGroups :xxx

todo Field Group definitions: label: {string} The label text of the group heading. Does not allow markup. heading: {string} The text of the group heading. Allows markup. This is used if the label is not given but markup is escaped. parentGroupName: {string} Optional name of the parent field group.
Type:
  • xxx

fields :Array.<object>

Defines the fields in the model and recordView form. The value is an array of exactly one object that maps the field name to a field definition object. The properties are the field names. The property value is a field definition. Wrapping the object in an array simply keeps the widget from making a copy of the fields so that the same definition can be shared.

The same structure can be shared with the view model and a grid widget.

Type:
  • Array.<object>
Properties:
Name Type Description
* object The property is the field name. By convention it is the uppercase database column name. The value is an object that defines the field. All properties are optional unless specified otherwise.
Properties
Name Type Description
elementId string Id of DOM element used to edit this field or null if not editable.
label string The label text of the field. Does not allow markup. At least one of label or heading should be specified.
heading string The text of the field header. Allows markup. This is used if the label is not given but markup is escaped.
fieldCssClasses string Extra CSS classes to apply to the field
fieldColSpan integer Integer between 1 and 12 specifying how many forum grid columns the field will span. This can be used to put two (or more) fields side by side.
cellTemplate string An HTML template that defines the field content. The template syntax is the same as APEX server side templates. See apex.util.applyTemplate for template syntax. The substitutions are field names from this field configuration and they are replaced with data values from the current record of the model.
escape boolean If false the column value may contain trusted markup otherwise the column value is escaped.
seq number Determines the order of the field among all the others. Lower numbers come first.
groupName string Name of field group.
useGroupFor string If not present or if the string contains "srv" then the group given in groupName will be used.
canHide boolean Determines if the user is allowed to show or hide the field. If true the user can choose to hide or show the field. If false the user cannot change the hidden state.
hidden boolean If true the field is hidden otherwise it is shown.
readonly boolean If true the field cannot be edited.
linkText string The anchor content. Allows markup. Allows substitutions just like the cellTemplate property. If not given the rendered display value of this field is used as the content. If the display value of the field is empty then the link URL is used. To display a link, at least one of linkTargetColumn or the field metadata url property must must be given. Note: if the field is editable it is always the data value of the field that is edited. So if you want to edit the link text it is best to omit linkText and use linkTargetColumn.
linkTargetColumn string The name of the column that contains the anchor href. If not given the href comes from the field metadata url property. If there is no url property then this field is not a link.
linkAttributes string Additional anchor attributes. Allows substitutions just like the cellTemplate property. Ignored unless a link is present.
isRequired boolean If true this field is required when editing. This should correspond with the required setting of the underlying editable column item.
helpid string Help id for the field. If present there will be a help icon button and keyboard shortcut to access help text for the field. todo need more details
virtual boolean If true the field is completely ignored by the recordView widget.
property string Do not specify this property. It is added automatically and the value is the field name.

Determine if the view will include a footer to show status and pagination controls and information. If true a footer is shown at the bottom of the view. If false no footer is shown.

Type:
  • boolean
Inherited From:
Default Value:
  • true

hasSize :boolean

This affects scrolling and how any header (if the view has a header) or footer position is handled.

Set to true if the view is in a container that has a specific height defined. When hasSize is true the record content will scroll within the bounds of the region.

Set to false if the view does not have a defined height. The view height will be as large as needed to contain the view records as determined by pagination settings. The view may scroll within the browser window. Other options may control if the header (if the view has a header) or footer sticks to the window.

The container width must always be defined.

Type:
  • boolean
Inherited From:
Default Value:
  • false

hideDeletedRows :boolean

Determine if deleted rows (records) are removed from the view right away or shown with a strike through effect to indicate they are going to be deleted. If true (and the view is editable) deleted records will not be visible, otherwise they are visible but have a visual indication that they are deleted. The actual records are not deleted on the server until the model is saved.

Type:
  • boolean
Inherited From:
Default Value:
  • false

highlights :object

Defines highlight color information for the view. Only applies to views that support highlighting. Style rules are injected into the document based on the highlight object.

The object is a mapping of highlight id to color definition.

Type:
  • object
Properties:
Name Type Description
* object A highlight ID. A unique ID for the highlight rule. The object can contain any number of highlight rules. The model record or field highlight metadata (see model.RecordMetadata) is used to associate the model data with the highlight rule. One of color or background must be given.
Properties
Name Type Attributes Description
seq number A number that defines the order of the CSS rule that is added.
row boolean If true the highlight applies to the record/row.
color string <nullable>
 The foreground color. If given, must be a valid CSS color value.
background string <nullable>
 The background color. If given, must be a valid CSS color value.
cssClass string <nullable>
 The class name for the rule. This is the class used in the rule and given to the appropriate element in the view so that the desired highlight colors are applied. The cssClass defaults to the highlight id prefixed with "hlr_" if row is true and "hlc_" otherwise.
Inherited From:

idPrefix :string

The prefix to use when generating ids. To avoid duplicate element ids either give the widget element an id or specify this property.

Type:
  • string

modelName :string

Name of model that this view widget will display data from. Can include an instance as well. The model must already exist. This option is required.

Type:
  • string
Inherited From:

noDataMessage :string

Text to display when there is no data.

Type:
  • string
Inherited From:

pagination :object

Pagination settings.

Type:
  • object
Properties:
Name Type Description
scroll boolean If true the scroll bar is used to page through the results a.k.a infinite scrolling or virtual paging. If false then next and previous buttons are shown. Default is false.
loadMore boolean If true show a load more button rather than auto paging. Only applies if scroll is true and the model doesn't know the total rows. Default is false.
showPageLinks boolean If true show page links between buttons. Only applies if scroll is false The model must know the total number of rows for this to be true. Default is false.
maxLinks number The maximum number of links to show when showPageLinks is true. Default is 5.
showPageSelector boolean If true show a drop down page selector between the buttons. Only applies if scroll is false. The model must know the total number of rows for this to be true. Default is false.
showRange boolean If true the range of rows/records is shown. It is shown between the buttons unless showPageLinks or showPageSelector is true. The range is shown as "X to Y" if the model doesn't know the total rows and "X to Y of Z" if the model does know the total number of rows. Default is true.
firstAndLastButtons boolean Only applies if scroll is false. If true first and last buttons are included. For this to be true the model must know the total number of rows.
Inherited From:

progressOptions :object

Options object to pass to apex.util.showSpinner. The default depends on the hasSize option.

Type:
  • object
Inherited From:
Default Value:
  • { fixed: !options.hasSize }

recordOffset :interger

Zero based index of record in model to display/edit in this recordView.

Type:
  • interger

rowsPerPage :boolean|null

Determine how many rows to show in one page. Only applies if pagination.scroll is false, otherwise this value is ignored. If null this value is determined by the viewport height

Type:
  • boolean | null
Inherited From:
Default Value:
  • null

selectionStatusMessageKey :string

The text message key to use for showing the number of selected rows/records in the footer. The message key must have exactly one parameter %0 which is replaced with the number of rows/records selected.

Type:
  • string
Inherited From:
Default Value:
  • "APEX.GV.SELECTION_COUNT"

showNullAs :string

Text to display when the value is null or empty string.

Type:
  • string
Default Value:
  • "-"

skipDeletedRecords :boolean

If true (and the recordView is editable) deleted records/rows will skipped over; the next non-deleted record is shown. Otherwise they are visible but have a visual indication that they are deleted this has no effect if the model deletes records right away.

Type:
  • boolean
Default Value:
  • false

Determine if the footer will stick to the bottom of the page. Only applies if hasSize is false and footer is true. If false the footer will not stick to the bottom of the page. If true the footer will stick to the bottom of the page.

Type:
  • boolean
Inherited From:
Default Value:
  • false

toolbar :object

Toolbar options. A default toolbar is provided. If null then there will be no toolbar.

Type:
  • object

Methods

fieldElement(pFieldName) → {*}

Given a pFieldName (field/column name) return the jQuery object for the element that wraps the label and the field.
Parameters:
Name Type Description
pFieldName field/column name
Returns:
jQuery object
Type
*

focus()

Give focus to the recordView. Focus is given to the first field.

getActions() → {actions}

Returns the actions context for this recordView instance. See {apex.actions} for details on how to use the actions context.
Returns:
the actions context for this instance.
Type
actions
Example
var a = $("#myview").recordView("getActions");
a.toggle("exclude-null-values");
a.invoke("next-record");
a.invoke("delete-record");
// to get a list of all actions from the browser javascript console
console.log(JSON.stringify($("#myview").recordView("getActions").list(), null, 4));

getActiveRecord() → {model.record}

Returns the active record or null if there is no active record. The active record is the one currently being edited.

Inherited From:
Returns:
active record
Type
model.record

getActiveRecordId() → {string}

Returns the identity of the active record or null if there is no active record. The active record is the one currently being edited.

Inherited From:
Returns:
active record id
Type
string

getRecord() → {Object|Array}

Returns the current model record that this view is viewing/editing.
Returns:
the current record from the model that the recordView is viewing/editing
Type
Object | Array

getToolbar() → {jQuery}

Returns the toolbar widget element.
Returns:
jQuery object of the recordView toolbar or null if there is no toolbar
Type
jQuery

gotoField(pRecordId, pColumnopt)

Put focus in the field given by pRecordId and pColumn. This is used to focus records and fields that have errors. This will change the current record as needed to focus the cell. The record must be in the model. If pColumn is null then the first field is focused.
Parameters:
Name Type Attributes Description
pRecordId String the record id of the record to go to.
pColumn String <optional>
 column name of the field to go to.

inEditMode() → {Boolean}

Determine if recordView is in edit mode rather than navigation mode.
Returns:
true if in edit mode and false otherwise.
Type
Boolean

lockActive()

Call to lock the active row while async processing is in progress.

The view edits one row/record at a time. This is known as the active row. In edit mode as the user changes the focused cell with the mouse, tab or enter keys if the new cell is on a different row the previous row is deactivated and the new row is activated. Any dynamic actions or other code that manipulates Column items are acting on the active row. If any actions are asynchronous such as using ajax to set a column item value then the row must not be deactivated while the async action is in progress otherwise the result would be applied to the wrong row!

So this method must be called before starting an async operation. It can be called multiple times if there are multiple async operations. For each call to lockActive there must be exactly one call to unlockActive.

If the view is part of an APEX region plugin, that region should implement the beforeAsync and afterAsync functions on the object returned from region.getSessionState by calling lockActive and unlockActive respectively. Then if an appropriate target option is passed to apex.server.plugin then the locking will be done automatically. Dynamic Actions that act on column items pass the correct target option. The bottom line is that for Dynamic Actions on columns of an Interactive Grid these lock/unlock methods are called automatically.

Inherited From:

refresh(pFocusopt)

Refreshes the recordView with data from the model. This method is rarely needed because it is called automatically when the model changes, widget options change, or when the record changes.
Parameters:
Name Type Attributes Description
pFocus boolean <optional>
 if true put focus in the recordView

refreshFields()

Let the record view know that field metadata has changed so that the next time it is refreshed all the fields will be rendered. Call this method after any field metadata has changed external to this widget. Refresh must be called after this but typically this happens due to the model refresh notification.

resize()

Call this method anytime the container that the recordView is in changes its size.

setActiveRecordValue(pColumn)

Use after a column item value is set without triggering a change event to update the model and grid view. Has no effect if there is no active record.

todo improve doc
Parameters:
Name Type Description
pColumn string The name of the column.
Inherited From:

setEditMode(pEditMode)

Set the current edit mode. Should only be used if the recordView model is editable.
Parameters:
Name Type Description
pEditMode boolean if true enter edit mode if false enter navigation mode

unlockActive()

Call to unlock the active row after async processing is complete.

Call after the async operation completes. See tableModelViewBase#lockActive for more information.

Inherited From: