Record List Event

 

Record List Events

Onload Event (desktop)app.record.index.show

An event triggered after the record list page is displayed on the desktop.

Function

app.record.index.show

Triggered Timing

  • After displaying the record list page
  • After displaying the record list page when clicking the "Next" or "Previous" arrow icons (the icons are displayed when all records cannot be fit into one page)
  • After sorting the record order when clicking the field titles
  • After applying the filter settings from the record list page

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
viewType String The type of the record list. This is either "list" or "calendar".
viewId Number The View ID of the record list.
viewName String The View Name of the record list.
records Array or Object An array of record objects, if the viewType is "list".
An object, including the date string as the key, and an array of record objects as the value, if the viewType is "calendar".

A "calendar" example:
{
	"2015-04-01": [record1, record2],
	"2015-04-20": [record1]
}
offset Number The offset of the list (null for "calendar" view).
size Number The number of records in the list (null for "calendar" view).
date String The month shown in the "calendar" view. April 2015 will be "2015-04" (null for "list" view).

Available Actions

Onload Event (mobile)mobile.app.record.index.show

An event triggered after the record list page is displayed on the mobile.

Function

mobile.app.record.index.show

Triggered Timing

  • After displaying the record list page
  • After saving on the record create page
    *when a record is saved on the record create page, the page loads a record list page before being directed to the record details page - this is why the record list event is triggered

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
viewId Number The View ID of the record list.
viewName String The View Name of the record list.

Available Actions

Inline Edit Eventapp.record.index.edit.show

An event triggered when an inline edit of a record starts on the record list page.

Function

app.record.index.edit.show

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
recordId Number The Record ID.
record Object A record object that holds data of the record when the inline editing started.

Available Actions

Save Submit Eventapp.record.index.edit.submit

An event triggered when the save button of the inline editing is clicked on the record list.

Function

app.record.index.edit.submit

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
recordId Number The Record ID.
record Object A record object that holds data inputted by the user.

Available Actions

Save Submit Success Eventapp.record.index.edit.submit.success

An event triggered after the record has been successfully saved after clicking the save button on the record list page on the desktop.

Function

app.record.index.edit.submit.success

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
recordId Number The Record ID.
record Object A record object that holds data of the saved record.

Available Actions

Sample

// Display the updated date time after saving.
kintone.events.on("app.record.index.edit.submit.success", function(ev) {
    var record = ev.record;
    alert("The updated date time is " + record["Updated_datetime"]["value"] + ".");
});

Notes

  • This event is only available on the Desktop.
  • This event cannot be used with an app embedded on a space.
  • The event will not trigger if the record does not successfully save.

Field Change Eventapp.record.index.edit.change.<>

An event triggered when a specified field value changes during an inline editing of a record on the record list.

Function

app.record.index.edit.change.<fieldcode>

Fields that can be Specified

  • Single choice
  • Drop-down
  • Check box
  • Multi-choice
  • User selection
  • Date
  • Time
  • Date and time
  • Single-line text
  • Number

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
record Object A record object including data inputted by the user at the time of the event.
recordId Number The Record ID.
changes Object An object including data of changed fields and rows.
changes.field Object An object of the changed field.

Available Actions

Running actions after waiting for asynchronous operations to finish

By returning a kintone.Promise object, you can run actions after waiting for asynchronous operations to finish. Refer to the sample code for the "Save Submit Event" event on the Record Create page.

Delete Submit Eventapp.record.index.delete.submit

An event triggered when the "Delete" button is clicked on the pop-up that appears when the delete icon of a record is clicked on the record list.

Function

app.record.index.delete.submit

Properties of the Event Object

PROPERTY TYPE DESCRIPTION
appId Number The App ID.
recordId Number The Record ID.
record Object A record object that holds data of the record that will be deleted.

Deleting a record after waiting for asynchronous operations to finish

By returning a kintone.Promise object, you can delete a record after waiting for asynchronous operations to finish. Refer to the sample code for the "Save Submit Event" event on the Record Create page.

Notes

  • If false is returned, the deletion will be cancelled.

Event Limitations

The below events are only available on the Desktop, and not on the mobile:

 

Available Actions

Overwrite field values

If the event handler overwrites values in the fields of the record object and returns the event object, the record is saved with those values in the object.

Sample

When saving an inline edit of a record, overwrite the field "text_0" and "text_in_table_0" with a specified string. "text_in_table_0" is a field that lies within a table with field code of "table_0".

kintone.events.on('app.record.index.edit.submit', function(event) {
	var record = event.record;
	record['text_0']['value'] = 'Overwrite with this string';
	record['table_0']['value'][0]['value']['text_in_table_0']['value'] = 'Overwrite first record in table';
	return event;
});

Fields that cannot be Overwritten

Even if the below fields are overwritten in the handler and returned, they will not take effect on the record itself

  • Calculated
  • The Field Mappings targets of the Lookup field
  • Attachment

Enable/Disable field edits

If the event handler inputs true/false in the disabled of a field of the record object and returns the event object, editing of those fields will become enabled/disabled.
Nothing will happen if this is applied to a field where you have no editing permissions.

Sample

Disable the editing of the "text_0" field when a value is selected in the drop down field "dropdown_0", during an inline edit of a record.

kintone.events.on('app.record.index.edit.change.dropdown_0', function(event) {
	var record = event.record;
	record['text_0']['disabled'] = true;
	return event;
});

Fields where editing cannot be enabled/disabled

Even if the below fields are returned with the disabled as true/false, they will not take effect on the record itself.

  • Calculated
  • The Field Mappings targets of the Lookup field

Show field errors

If the event handler inputs an error message in the error of a field of the record object and returns the event object, an error message is displayed for the corresponding field.
In this case, the overwriting of field values and the enabling/disabling of field edits are canceled.

 

Sample

Show an error message for the fields "text_0" and "dropdown_0" when saving an inline edit for a record.

kintone.events.on('app.record.index.edit.submit', function(event) {
	var record = event.record;
	record['text_0']['error'] = 'This is an error message';
	record['dropdown_0']['error'] = 'This is also an error';
	return event;
});

Fields that don't show error messages

Even if the below fields have error messages inputted by the handler and the object is returned, they will not take effect on the record itself.

  • Record number
  • Created by
  • Created datetime
  • Updated by
  • Updated datetime
  • Status
  • Assignee

Show record errors

If the event handler inputs an error message in the error of the event object and returns the event object, an error message is displayed for the record.
In this case, the overwriting of field values and the enabling/disabling of field edits are canceled.

Sample

Show an error message for the record when changing a drop down field during an inline edit of a record.

kintone.events.on('app.record.index.edit.change.dropdown_0', function(event) {
	event.error = 'This is an Error Message!';
	return event;
});

Get the object of the edited field

An object containing data of an edited field can be retrieved. 

Sample

Retrieve the object data of the field dropdown_0 when the value of dropdown_0 changes during an inline edit of a record in the record list.

kintone.events.on('app.record.index.edit.change.dropdown_0', function(event) {
    var field = event.changes.field;
});

Action Limitations

These actions are only available on the Desktop, and not on the mobile.

Was this article helpful?
0 out of 0 found this helpful
Comments
Please sign in to leave a comment.