Zengine provides several services for you to inject as dependencies when developing your plugin.
znMessage
A service that displays a temporary alert message at the top of the page.
znMessage(message, [type], [duration])
Param
Type
Details
message
string
The message to display.
type (optional)
string
Determines the background color of the message. Valid types: 'info', 'saved', 'error', 'warning'. Default is 'info'.
duration (optional)
integer
How long the message is displayed in milliseconds. Default is 4000.
Forces any open messages to close.
znMessage(false);
znConfirm
A service that displays a confirmation dialog.
znConfirm(message, [callback])
Param
Type
Details
message
string
The message to display in the dialog.
callback (optional)
function
If defined, will add a 'Yes' button to the dialog, which when clicked, will execute the callback.
znModal
A service that displays a modal dialog. For an alternative modal service, try Angular bootstrap’s$modal.
znModal(options)
Param
Type
Details
options
Object
The object has the following properties:
title - {string} - The dialog title.
template - {string} - Raw HTML to display as the dialog body.
templateUrl - {string} - Takes precedence over the template property. Works the same as the 'templateUrl' option when registering a directive. Corresponds to the id of the script tag that wraps the HTML to display as the dialog body. For more info, see the Angular docs on the script directive.
classes - {string} - One or more (space-separated) CSS classes to add to the dialog.
closeButton - {boolean} - A close button is included by default. Passing false won't include it.
unique - {boolean|string} - Whether to close any other open dialogs. true means close any other dialogs. Alternatively, a CSS class name can be passed to close related dialogs. If you are using the plugin location zn-plugin-form-top, in order for the modal to work this must be set to true.
btns - {Object} - An object hash of buttons to include. Each button is a key-value pair, where the key is name used for the button text, and the value is a hash object that can include the following properties:
one of three possible keys to determine background color: success, danger, or primary.
action callback to run when the button is clicked. By default, the action callback is called with no arguments, but this can be enhanced by calling the function setBtnAction(name, onClick), which is available on the modal scope (more detail on modal scope below). The first argument, name, is the name of the button specified as the key in the btns hash. The second argument, onClick, is a function that is called on click of the button, instead of the original callback. When called, onClick is passed a wrapper function that takes two arguments: data and keepOpen. When the wrapper function is called within the onClick function, it calls the original actioncallback with its first argument data, and unless keepOpen is true, closes the modal.
scope - {Object} - This property determines which scope to use in the modal template. (If you are familiar with Angular, this property is similar to how the scope property works with a directive.) There are three options for the scope to be used:
By default, the modal creates a child scope, which prototypically inherits from the $rootScope.
To create a child scope, which prototypically inherits from a different parent (i.e. the scope where the modal is being used), you can pass a reference like this: scope: $scope.
To create an isolated scope, which does not prototypically inherit, so that it is completely isolated from its parent, you can pass an object like this: scope: { ... } .
In addition the scope associated with modal's content is augmented with the method setBtnAction(name, onClick).
znFiltersPanel
znFiltersPanel is a service that allows you to view and build a data filter by opening a modal. This is different from the znInlineFilter directive, which displays the filter builder directly in the page. The filter returned from the panel can be used to query records, save to a data view, and build and run calculations.
znFiltersPanel.open(options)
Param
Type
Details
options
Object
The object has the following properties:
formId - {integer} - Form ID of the form you want to filter on.
filter - {Object} - Existing filter to open with the panel. Does not apply to znInlineFilter directive.
onSave - {function(filter)} - A callback executed when the filter panel is saved. Does not apply to znInlineFilter directive.
subfilters - {boolean} - Whether to allow subfiltering on related fields. Defaults to true.
groups - {boolean} - Whether to allow nested conditions. Defaults to true.
dynamicValues - {boolean} - Whether to allow dynamic values such as logged-in-user. Defaults to true.
operators - {array} - A list of operators to allow filtering on. Defaults to ['and', 'or'] but ['and'] or ['or'] can also be passed.
attributeBlacklist - {array} - A list of specific fields to prevent the user from filtering on. The list can contain an attribute like 'field123', where 123 is the ID of a field belonging to the form. The list can also contain the following attributes: 'folder.id', 'createdByUser.id', 'created', and 'modified'.
prefixBlacklist - {array} - A list of prefixes to prevent the user from filtering on. The following is a list of valid prefixes:
""
"not"
"contains"
"not-contains"
"starts-with"
"ends-with"
"min"
"max"
"not-validates"
fieldTypeBlacklist - {array} - A list of field types to prevent the user from filtering on. The following is a list of valid field types:
calculated-field
checkbox
country-select
date-picker
dropdown
file-upload
heading
hidden-field
html
link-counter
linked
member
numeric
page-break
radio
spacer
state-select
summary
text
text-area
text-input
year
For a more complete reference, see the API documention on form field taxonomy.
znFilterMatcher
The znFilterMatcher service lets your plugin compare a record against a filter and determine if it’s a match. It uses the same matching as querying records using a filter or for conditional field rules. One case you might use this for is to filter down a list of records that have already been fetched without making an additional request to the API.
For the matching to work properly, the data you are filtering on must be present in the record. Additionally, subfilters of fields on other forms and dynamic conditions, such as logged-in-user, are not supported.
znData
The znData service provides a collection of resources that should be used for accessing data via the Zengine REST API. After passing the name of the resource to the service, you get back an object that can use the methods described below: get, query, save, update, delete, saveAll, updateAll and deleteAll. All methods return a standard Angular promise object.
Optional if the resource has no required URL parameters and a POST is desired. Valid URL parameters are defined for each resource here. If the paramsobject is passed, any keys that aren't URL parameters are sent as query parameters in the request. Some examples of valid query parameters are limit, related, sort, and attributes. If the id param is included in this object, a PUT is made. If not, a POST is made.
data
Object
Sent as the payload of the request.
successCallback
function(data, metaData, headers)
The function to execute if the request succeeds.
data - {Object} - The data of the response.
metaData - {Object} - An object containing the following info about the response:
status
code
totalCount
limit
offset
Click here for more info about the response format.
headers - {function([headerName])} – Getter function for the HTTP response headers.
errorCallback
function(resp)
The function to execute if the request fails. Click here for more info about the format of the failure response.
Available Resources
The parameterized URL is used to query the Zengine REST API. For example, if the resource name is FormFields, the parameterized URL is /forms/:formId/fields/:id. In this case, formId is a required URL paramter, and must be passed to the params argument of any get(), query(), delete(), or save() called on znData('FormFields'). The id parameter on the other hand, may or may not be passed, depending on whether the request is intended for a single object or multiple objects. This is true for the id parameter of any resource URL.
The Zengine REST API has more querying options for pagination, sorting, filtering, and relational data.
The znPluginData service is used to communicate with Plugin Services, similar to how znData makes requests to the REST API. Instead of passing a resource name, you pass the plugin namespace and service route. The methods available are: get, post, put, and delete. The methods return an Angular promise object.
The param workspaceId is always required and must be a workspace where the plugin is installed. Query string parameters should be passed as params.
znPluginEvents is service that acts as a wrapper for the Angular pub-sub system, and is meant for communication between plugins and the core app.
znPluginEvents.$on(name, listener)
Same as Angular $on. This method can be used to listen for the following broadcasted events:
zn-ui-record-overlay-record-loaded
zn-data-resource-name-action
Events in this format are triggered by a successful response to a call via the znData service. The resource name is the hyphenated version of the resource names listed here. The action can be one of the following: read, saved, deleted, saved-all, updated-all or deleted-all. For example, calling znData('FormRecords').save() will trigger the 'zn-data-form-records-saved' event.
Important: Make sure to deregister your listeners when your plugin is destroyed. Not deregistering listeners will cause listeners to duplicate and pile up, which will degrade the performance of your plugin and the app. The code below shows listeners being registered and deregistered on $scope $destroy.
znLocalStorage
This service gives you basic access to browser local storage and fallbacks to browser cookies if support is not available.
znLocalStorage.set(key, value)
Set an item in browser local storage.
znLocalStorage.get(key)
Get an item in browser local storage.
znLocalStorage.remove(key)
Remove an item in browser local storage.
znLocalStorage.isSupported
Checks if the browser support local storage.
znCookies
This service gives you basic access to browser cookies.