Widget API

Widget API is designed to facilitate the communication between page widgets, i.e., you can subscribe events from a widget to update another one. All Casewhere widgets provide a set of APIs so you can, in page event handlers, call these APIs to interact with the widgets. You can event implement custom API for custom widgets to handle your custom logic.

Built-in APIs

All built-in widgets provide a set of APIs so you can, in page event handlers, call these APIs to interact with the widgets.

`refresh()`

Refresh the grid widget. Data will be reloaded from the server.

Example

var api = $scope.widgetApis['book-list'];
api.refresh();

`getSelectedDOs()`

Retrieve the user's selected items.

Example

var api = $scope.widgetApis['book-list'];
api.getSelectedDOs();

`setSelectedDOs(items)`

Set the selected items, the old ones will be replaced with the new ones.

Parameters

Name	Type	Details
items	object[]	Each item must have the `Id` field. Casewhere will ignore the items which are not found in the current widget's data.

Example

var api = $scope.widgetApis['book-list'];
var bookList = bookListApi.getWidgetData().data;

// Find the current book
var currentBook = api.getSelectedDOs()[0];

// Clear user's selection
api.setSelectedDOs([]);

var currentIndex = _.findIndex(bookList, function(book) {
    return book.Id === currentBook.Id;
});

// Select the next one
var nextBook = bookList[currentIndex + 1];
api.setSelectedDOs([nextBook]);

`runWidgetAction(widgetActionName, doIds, data)`

Run the widget action configured for the widget.

Parameters

Name	Type	Description
widgetActionName	string	Name of the action
doIds	object[]	Data objects as input for running the action. Each data object must have the `Id` field
data	object	Additional parameters for running the action

Example

var api = $scope.widgetApis['book-list'];
var parameters = {
    Name: "The Da Vinci Code",
    Author: "Dan Brown",
    Year: "2003"
};

api.runWidgetAction("Add book", null, parameters);

`setQueryParameters(parameters)`

Set the parameter for the widget data query.

Parameters

Name	Type	Description
parameters	object	A key/value object

Example

var api = $scope.widgetApis['book-list'];
var parameters = {
    Author: "Dan Brown"
};

api.setQueryParameters(parameters);

`setActionCustomInputs(widgetActionName, doIds)`

Use this method to programmatically set input for widget actions, which is useful when you want to load data to dynamically reflect the change in UI.

Parameters

Name	Type	Description
widgetActionName	string	Name of the action
doIds	object[]	Inputs for running the action

Example

var api = $scope.widgetApis['book-list'];
var bookIds = [
    {
        "Id": "Book/3ae2aa8c-7937-4d02-ba17-ae0500c5b426"
    }
];

api.setActionCustomInputs("Edit book", bookIds);

`show()`

Show the widget.

Example

var api = $scope.widgetApis['book-list'];
api.show();

`hide()`

Hide the widget.

Example

var api = $scope.widgetApis['book-list'];
api.hide();

`setState(name, value)`

Save data to the widget internal storage.

Parameters

Name	Type	Description
name	string	The name to reference the state value
value	*	The value could be anything

Example

var api = $scope.widgetApis['book-list'];
api.setState("version", 1);

`getState(name)`

Get data from the widget internal storage.

Parameters

Name	Type	Description
name	string	Name of the state

Example

var api = $scope.widgetApis['book-list'];
var version = api.getState("version"); // version: 1

`getWidgetData()`

Get the widget data in the format:

{
    data: [], // an array of items
    total: 100, // total items
    metadata: {} // the metadata of the data source used by the widget
}

Example

var api = $scope.widgetApis['book-list'];
var widgetData = api.getWidgetData();
var books = widgetData.data;
var totalBook = widgetData.total;

`updateWidgetData(widgetData)`

Update the widget data.

Parameters

Name	Type	Description
widgetData	object	An object in the following format: `{ data: // an array of items, total: // total items }`

Example

var api = $scope.widgetApis['book-list'];
var books = getBooksByGenre("Novel");
var totalBook = 1000;
var widgetData = {
    data: books,
    total: totalBook
};
api.updateWidgetData(widgetData);

`refreshByWorkflowId(workflowId)`

Gets the data changes by a workflow and then, reflects them in the grid.

Parameters

Param	Type	Details
workflowId	string	ID of the workflow to get changes.

Example

var api = $scope.widgetApis['book-list'];
var workflowId = "4aaf6240-11a3-4422-9509-ae1400d56039";
api.refreshByWorkflowId(workflowId);

`onDelete(dataObject)`

Remove the data object from the current view.

From 2.7.2, the name for this method should be delete however, you can still use onDelete.

Parameters

Param	Type	Details
dataObject	object	The object must have the`ID` field.

Example

var api = $scope.widgetApis['book-list'];
var widgetData = api.getWidgetData();
var books = widgetData.data;
api.onDelete(books[0]);

`export()`

Export the grid data to an excel file.

Example

var api = $scope.widgetApis['book-list'];
api.export();

`addColumns(columns, index)`

Add a set of columns at a specific position.

Parameters

Param	Type	Details
columns	object/object[]	Pass an object if you want to add a single column, pass an array if you want to add multiple columns. The format of each column: { "name": <string>, // name of a column "header": <string>, // header of a column "path": <string>, // a column name used for sorting a column" "template": <string>, // an AngularJS binding expression, e.g. "{{dataObject.Title}}" "minWidth": <number>, // column's minimum width in pixel "maxWidth": <number>, // column's maximum width in pixel "modes": <string[]>, // screen sizes to display a column, leave it empty or null to display on all screens "exportExpression": <string>, // a JS expression e.g. "dataObject.Title" "exportFormat": <string>, // the default formats are listed in ECMA-376 18.8.30 "pin": <string>, // Possible values: "Left", "Right", null }
index	number	[Optional] A zero-based index position where the columns are added. If not defined, Casewhere will append the columns to the last position.

Example

var api = $scope.widgetApis['book-list'];
var newColumn = {
    name: "Author",
    header: "Author",
    path: "Author",
    template: "{{dataObject.Author}}",
    exportExpression: "dataObject.Author"
};
api.addColumns(newColumn, 0);

`getQueryOptions()`

Get the current query options.

{
    QueryParameters:, // the parameters used for getting data
    Pagination: {
        PageSize:, // the number of items in each page
        PageIndex: // the current page number
    },
    clauses:, // the clauses for filtering data
    sortOptions:, // the current sorting options
    Search: // the full text search text
}

Example

var api = $scope.widgetApis['book-list'];
var queryOptions = api.getQueryOptions();

`setQueryOption(option)`

Set the data query options.

Parameters

Name	Type	Details
option	object	The object described at getQueryOptions.

Example

var api = $scope.widgetApis['book-list'];
var option = {
    Search: "Advanture"
};
api.setQueryOption(option);

`extendGridOptions(option)`

Customize the grid settings.

Parameters

Name	Type	Description
option	object	Learn more about the grid settings here.

Example

var api = $scope.widgetApis['book-list'];
var option = {
    rowHeight: 50
};
api.extendGridOptions(option);

`refresh()`

Refresh the list widget. Data will be reloaded from the server.

Example

var api = $scope.widgetApis['book-list'];
api.refresh();

`getSelectedDOs()`

Retrieve the user's selected items.

[
    {
        "Id": // first selected item's ID,
        ...
    },
    {
        "Id": // second selected item's ID,
        ...
    }
]

Example

var api = $scope.widgetApis['book-list'];
api.getSelectedDOs();

`setSelectedDOs(items)`

Sets the selected items, the old ones will be replaced with the new ones.

Parameters

Name	Type	Details
items	object[]	Each item must have the `Id` field. Casewhere will ignore the items which are not found in the current widget's data.

Example

var api = $scope.widgetApis['book-list'];
var bookList = api.getWidgetData().data;
var currentBook = api.getSelectedDOs()[0];
var currentIndex = _.findIndex(bookList, function(book) {
    return book.Id === currentBook.Id;
});
var nextBook = bookList[currentIndex + 1];
// Deselect the selected book
api.setSelectedDOs([]);

api.setSelectedDOs([nextBook]);

`runWidgetAction(widgetActionName, doIds, data)`

Run the widget action configured for the widget.

Parameters

Name	Type	Details
widgetActionName	string	Name of the action configured in the widget
doIds	object[]	Data objects as input for running the action. Each data object must have the`Id` field
data	object	Additional parameters for running the action

Example

var api = $scope.widgetApis['book-list'];
var newBook = {
    Name: "The Da Vinci Code",
    Author: "Dan Brown",
    Year: "2003"
};

api.runWidgetAction("Add book", null, newBook);

`setQueryParameters(parameters)`

Set the parameter for the widget data query.

Parameters

Name	Type	Description
parameters	object	A key/value object

Example

var api = $scope.widgetApis['book-list'];
var parameters = {
    Author: "Dan Brown"
};

api.setQueryParameters(parameters);

`setActionCustomInputs(widgetActionName, doIds)`

Sometimes, the inputs for an action are not available in the widget itself, but from an external place. In those cases, use this method to manually set the inputs for the action.

Parameters

Param	Type	Details
widgetActionName	string	Name of the action
doIds	object[]	Inputs for running the action

Example

var api = $scope.widgetApis['book-list'];
var bookIds = [
    {
        "Id": "Book/3ae2aa8c-7937-4d02-ba17-ae0500c5b426"
    }
];

api.setActionCustomInputs("Edit book", bookIds);

`show()`

Show the widget.

Example

var api = $scope.widgetApis['book-list'];
api.show();

`hide()`

Hide the widget.

Example

var api = $scope.widgetApis['book-list'];
api.hide();

setState(name, value)`

Save data to the widget internal storage.

Parameters

Name	Type	Description
name	string	The name to reference the state value
value	*	The value could be anything

Example

var api = $scope.widgetApis['book-list'];
api.setState("version", 1);

`getState(name)`

Get data from the widget internal storage.

Parameters

Name	Type	Description
name	string	Name of the state

`getWidgetData()`

Gets the widget data in the following format.

{
    data:, // an array of items
    total:, // total items
    metadata: // the metadata of the data source used by the widget
}

Example

var api = $scope.widgetApis['book-list'];
var widgetData = api.getWidgetData();
var books = widgetData.data;
var totalBook = widgetData.total;

`updateWidgetData(widgetData)`

Sets the widget data.

Parameters

Name	Type	Description
widgetData	object	An object in the format: `{ data: // an array of items, total: // total items }`

Example

var api = $scope.widgetApis['book-list'];
var books = getBooksByGenre("Novel");
var totalBook = 1000;
var widgetData = {
    data: books,
    total: totalBook
};
api.updateWidgetData(widgetData);

`refreshByWorkflowId(workflowId)`

Gets the data changes by a workflow and then, reflects them in the list.

Parameters

Name	Type	Description
workflowId	string	ID of the workflow to get changes.

Example

var api = $scope.widgetApis['book-list'];
var workflowId = "4aaf6240-11a3-4422-9509-ae1400d56039";
api.refreshByWorkflowId(workflowId);

`getQueryOptions()`

Get the current query options.

{
    QueryParameters:, // the parameters used for getting data
    Pagination: {
        PageSize:, // the number of items in each page
        PageIndex: // the current page number
    },
    clauses:, // the clauses for filtering data
    sortOptions:, // the current sorting options
    Search: // the full text search text
}

Example

var api = $scope.widgetApis['book-list'];
var queryOptions = api.getQueryOptions();

`setQueryOption(option)`

Set the data query options.

Parameters

Name	Type	Description
option	object	An object in the format described at getQueryOptions.

Example

var api = $scope.widgetApis['book-list'];
var option = {
    Search: "Advanture"
};
api.setQueryOption(option);

`selectTab(tabName)`

Select a tab by name.

Parameters

Name	Type	Description
tabName	string	Name of the tab you want to select

Example

var api = $scope.widgetApis['book-categories'];
api.selectTab("Advanture");

`selectTabByIndex(tabIndex)`

Selects a tab by index.

Parameters

Name	Type	Description
tabIndex	number	A zero-based index

Example

var api = $scope.widgetApis['book-categories'];
api.selectTabByIndex(0);

`clearCache()`

Remove the cached content of inactive tabs, so Casewhere will reload them when they are activated.

Example

var api = $scope.widgetApis['book-categories'];
api.clearCache();

`showTab(tabName)`

Show a tab by name.

Parameters

Name	Type	Description
tabName	string	Name of a tab.

Example

var api = $scope.widgetApis['book-categories'];
api.showTab("Advanture");

`hideTab(tabName)`

Hide a tab by name.

Parameters

Name	Type	Description
tabName	string	Name of a tab.

Example

var api = $scope.widgetApis['book-categories'];
api.hideTab("Advanture");

`showTabByIndex(tabIndex)`

Show a tab by index.

Parameters

Param	Type	Description
tabIndex	number	A zero-based index

Example

var api = $scope.widgetApis['book-categories'];
api.showTabByIndex(0);

`hideTabByIndex(tabIndex)`

Hides a tab by index.

Parameters

Name	Type	Description
tabIndex	number	Index starts from 0

Example

var api = $scope.widgetApis['book-categories'];
api.hideTabByIndex(0);

`widgetApis`

To reference the child widgets by their names.

Example

var bookCategoriesApi = $scope.widgetApis['book-categories'];
var adventureBookListApi = bookCategoriesApi.widgetApis["adventure-book-list"];
adventureBookListApi.refresh();

`show()`

Show the widget.

Example

var api = $scope.widgetApis['book-categories'];
api.show();

`hide()`

Hides the widget.

Example

var api = $scope.widgetApis['book-categories'];
api.hide();

`setState(name, value)`

Save data to the widget internal storage.

Parameters

Name	Type	Description
name	string	The name to reference the value
value	*	The value could be anything

Example

var api = $scope.widgetApis['book-categories'];
api.setState("version", 1);

`getState(name)`

Get data from the widget internal storage.

Parameters

Name	Type	Description
name	string	Name of the state

Example

var api = $scope.widgetApis['book-categories'];
var version = api.getState("version"); // version: 1

`setTabCounterNumber(tabName, counterNumber)`

Set counter number (total list items) displayed on a tab header.

Example

var counterNumber = 12
$scope.widgetApis['cwgm-my-pagev2'].setTabCounterNumber('cwgm_tasks', counterNumber)

`triggerWorkflow(options)`

Trigger and load the associated workflow.

Parameters

Param	Type	Details
options	object	[Optional] An object in the following format: `{ "caseId": <string>, // case to run the workflow "inputs": <object[]>, // inputs for running the workflow "parameters": <object>, // external data for the workflow "showHeaderCloseButton": <boolean>, // false to hide the close button "widgetId": <string>, // the tab container widget ID "container": <object>, // e.g. { containerId: "7e28d777-0723-424e-837d-ac39004337cd", containerType: "Page" } }`

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
api.triggerWorkflow();

`closeWorkflow()`

Close the workflow container.

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
api.closeWorkflow();

`setWorkflowParameters(caseId, inputs, parameters)`

Set the parameters to trigger workflow.

Parameters

Name	Type	Description
caseId	string	The case to run the workflow. It is required if the workflow definition is Edit Case
inputs	object[]	[Optional] An array of data objects. All item must have the field `Id`
parameters	object	[Optional] Additional data to run the workflow

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
var caseId = "413e1752-ed1a-4c87-96b9-ae1500ad5d5f";
api.setWorkflowParameters(caseId);
api.triggerWorkflow();

`setCaseId(caseId)`

Set the case ID to trigger workflow. It is required if the workflow definition is Edit Case.

Parameters

Name	Type	Description
caseId	string	[Required] A case to run the workflow

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
var caseId = "413e1752-ed1a-4c87-96b9-ae1500ad5d5f";
api.setCaseId(caseId);
api.triggerWorkflow();

`setInputs(inputs)`

Set inputs for triggering workflow.

Parameters

Param	Type	Details
inputs	object[]	[Optional] An array of data objects. All item must have the field `Id`

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
var inputs = [{ Id: "Book/55e601e6-8566-49e4-94fe-ae0500c677bb" }];
api.setInputs(inputs);
api.triggerWorkflow();

`setParameters(parameters)`

Set additional data for triggering workflow.

Parameters

Param	Type	Details
parameters	object	[Optional] Additional data to run the workflow

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
var parameters = {
    publishedYear: 2022
};
api.setParameters(parameters);
api.triggerWorkflow();

`workflowShellApi`

Access to the workflow shell API object.

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
var workflowShellApi = api.workflowShellApi;
workflowShellApi.saveAndClose();

`show()`

Show the widget.

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
api.show();

`hide()`

Hide the widget.

Example

var api = $scope.widgetApis['edit-book-workflow-container'];
api.hide();

`runWidgetAction(widgetActionName, doIds, data, refreshCallback, reloadDataCallback)`

Run the widget action.

Parameters

Param	Type	Details
widgetActionName	string	[Required] Name of the widget action
doIds	object[]	[Optional] Inputs for running the action. The data item must have the `Id`field
data	object	[Optional] Additional data for running the action.
refreshCallback	function	[Optional] This method is called after an automatic workflow is run.
reloadDataCallback	function	[Optional] Calls after an UI workflow or a page action is run.

Example

var bookListApi = $scope.widgetApis['book-list'];
var newBook = {
    Name: "The Da Vinci Code",
    Author: "Dan Brown",
    Year: "2003"
};

bookListApi.runWidgetAction("Add book", null, newBook);

`setQueryParameters(parameters)`

Set the parameter for the widget data query.

Parameters

Name	Type	Description
parameters	object	A key/value object

Example

var api = $scope.widgetApis['book-list'];
var parameters = {
    Author: "Dan Brown"
};

api.setQueryParameters(parameters);

`setActionCustomInputs(widgetActionName, doIds)`

Use this method to programmatically set input for widget actions, which is useful when you want to load data to dynamically reflect the change in UI.

Parameters

Name	Type	Description
widgetActionName	string	Name of the action
doIds	object[]	Inputs for running the action

Example

var api = $scope.widgetApis['book-list'];
var bookIds = [
    {
        "Id": "Book/3ae2aa8c-7937-4d02-ba17-ae0500c5b426"
    }
];

api.setActionCustomInputs("Edit book", bookIds);

`show()`

Show the widget.

Example

var api = $scope.widgetApis['book-list'];
api.show();

`hide()`

Hide the widget.

Example

var api = $scope.widgetApis['book-list'];
api.hide();

`setState(name, value)`

Save data to the widget internal storage.

Parameters

Name	Type	Description
name	string	The name to reference the value
value	*	The value could be anything

Example

var bookListApi = $scope.widgetApis['book-list'];
bookListApi.setState("version", 1);

`getState(name)`

Get data from the widget internal storage.

Parameters

Name	Type	Description
name	string	Name of the state

Example

var bookListApi = $scope.widgetApis['book-list'];
var version = bookListApi.getState("version"); // version: 1

`getQueryOptions()`

Get the query options for loading data.

{
    QueryParameters:, // the parameters used for getting data
    Pagination: {
        PageSize:, // the number of items in each page
        PageIndex: // the current page number
    },
    clauses:, // the clauses for filtering data
    sortOptions:, // the current sorting options
    Search: // the full text search text
}

Example

var bookListApi = $scope.widgetApis['book-list'];
var queryOptions = bookListApi.getQueryOptions();

`setQueryOption(option)`

Set the data query options.

Parameters

Name	Type	Description
option	object	An object in the format described at getQueryOptions.

Example

var bookListApi = $scope.widgetApis['book-list'];
var option = {
    Search: "Advanture"
};
bookListApi.setQueryOption(option);

Casewhere allows you to implement custom API for custom widgets. In the below example, we're going to add two new methods: getABook and getAllBooks

$scope.$watch('widgetApi', function () {
    if (!$scope.widgetApi) {
        $scope.widgetApi = {};
    }

    $scope.widgetApi.getABook = function(name) {
        return $scope.books[name];
    };

    $scope.widgetApi.getAllBooks = function() {
        return $scope.books;
    };
});

Built-in APIs

Grid widget

refresh()

getSelectedDOs()

setSelectedDOs(items)

runWidgetAction(widgetActionName, doIds, data)

setQueryParameters(parameters)

setActionCustomInputs(widgetActionName, doIds)

show()

hide()

setState(name, value)

getState(name)

getWidgetData()

updateWidgetData(widgetData)

refreshByWorkflowId(workflowId)

onDelete(dataObject)

export()

addColumns(columns, index)

getQueryOptions()

setQueryOption(option)

extendGridOptions(option)

List widget

refresh()

getSelectedDOs()

setSelectedDOs(items)

runWidgetAction(widgetActionName, doIds, data)

setQueryParameters(parameters)

setActionCustomInputs(widgetActionName, doIds)

show()

hide()

setState(name, value)`

getState(name)

getWidgetData()

updateWidgetData(widgetData)

refreshByWorkflowId(workflowId)

getQueryOptions()

setQueryOption(option)

Tab container widget

selectTab(tabName)

selectTabByIndex(tabIndex)

clearCache()

showTab(tabName)

hideTab(tabName)

showTabByIndex(tabIndex)

hideTabByIndex(tabIndex)

widgetApis

show()

hide()

setState(name, value)

getState(name)

setTabCounterNumber(tabName, counterNumber)

Workflow container widget

triggerWorkflow(options)

closeWorkflow()

setWorkflowParameters(caseId, inputs, parameters)

setCaseId(caseId)

setInputs(inputs)

setParameters(parameters)

workflowShellApi

show()

hide()

Custom widget

runWidgetAction(widgetActionName, doIds, data, refreshCallback, reloadDataCallback)

setQueryParameters(parameters)

setActionCustomInputs(widgetActionName, doIds)

show()

hide()

setState(name, value)

getState(name)

getQueryOptions()

setQueryOption(option)

Implement custom API for custom widget

`refresh()`

`getSelectedDOs()`

`setSelectedDOs(items)`

`runWidgetAction(widgetActionName, doIds, data)`

`setQueryParameters(parameters)`

`setActionCustomInputs(widgetActionName, doIds)`

`show()`

`hide()`

`setState(name, value)`

`getState(name)`

`getWidgetData()`

`updateWidgetData(widgetData)`

`refreshByWorkflowId(workflowId)`

`onDelete(dataObject)`

`export()`

`addColumns(columns, index)`

`getQueryOptions()`

`setQueryOption(option)`

`extendGridOptions(option)`

`refresh()`

`getSelectedDOs()`

`setSelectedDOs(items)`

`runWidgetAction(widgetActionName, doIds, data)`

`setQueryParameters(parameters)`

`setActionCustomInputs(widgetActionName, doIds)`

`show()`

`hide()`

`getState(name)`

`getWidgetData()`

`updateWidgetData(widgetData)`

`refreshByWorkflowId(workflowId)`

`getQueryOptions()`

`setQueryOption(option)`

`selectTab(tabName)`

`selectTabByIndex(tabIndex)`

`clearCache()`

`showTab(tabName)`

`hideTab(tabName)`

`showTabByIndex(tabIndex)`

`hideTabByIndex(tabIndex)`

`widgetApis`

`show()`

`hide()`

`setState(name, value)`

`getState(name)`

`setTabCounterNumber(tabName, counterNumber)`

`triggerWorkflow(options)`

`closeWorkflow()`

`setWorkflowParameters(caseId, inputs, parameters)`

`setCaseId(caseId)`

`setInputs(inputs)`

`setParameters(parameters)`

`workflowShellApi`

`show()`

`hide()`

`runWidgetAction(widgetActionName, doIds, data, refreshCallback, reloadDataCallback)`

`setQueryParameters(parameters)`

`setActionCustomInputs(widgetActionName, doIds)`

`show()`

`hide()`

`setState(name, value)`

`getState(name)`

`getQueryOptions()`

`setQueryOption(option)`