Skip to content

zAppDev Developer JS API Reference

Global Objects


$formExtend

This function is used to add functionality to the form controller.

Attention

It is important to wrap your logic related code inside this is function, since it is invoked when everything has loaded. Otherwise script exceptions will occur.

$formExtend = function() {
    console.log("Form extension code executed!");

    $form.customAction = function(user) {
        console.log("User object", user);
    }

    $events.on.SignIn = function (UserName, Time) {
        alert(UserName, Time);
    }

    ...
}

$onFormLoaded

Use this function to execute code after form has completely loaded.

$onFormLoaded = function() {
    console.log("Form Loaded! Model object:", $form.model);
}

$form

The form's angular scope. You may access all scope's variables and functions, including model.

function example() {
    alert("Model Username: " + $form.model.User.UserName);
}

In mark up

<h1>{{model.UserName}}</h1>

$master

The master form's angular scope, just like above

function example() {
    alert("Page Title: " + $master.model.Title);
}

$actions

The form's controller action entry points, as JS functions.

function example() {
    $actions.SayHelloAction($form.model.User.UserName);
}

$masterActions

The MASTER form's controller action entry points, as JS functions.

function example() {
    $masterActions.SignOutUser();
}

$api

All exposed api models of the application and their operations as JS functions. Operations accept parameters as defined in their model and return a regular JS promise object with a response parameter.

Structure of Response

Property Description
data Actual response data of the API
config Request configuration
headers Request headers
status Request status
statusText Request's statusText
function example() {
    $api.UserApi.GetAll(10, 0).then(function(response) { 
        console.log(response.data); 
    });
}

$domain

All domain model classes and their operations as JS functions.

Attention

All operations are static, with their first parameter being this.

function example() {
    $domain.User.IsInRole($form.model.User, "Administrator");
}

$localization

An object containing localization info, according to current user preferences

Structure of Object

Property Description
locale A string representing current locale (e.g. "en")
decimalSeparator The character used to mark number radix points (e.g. ".")
groupSeparator The character used to mark number groups (e.g. ",")
function example() {
    console.log($localization.locale);
}

$info

An object containing general info for current form and application

Structure of Object

Property Description
action Current entry point controller action
controller Current controller (form name)
masterForm Forms master form name
siteRoot Site URL root (e.g. 'http://localhost:8080/myApp')
pathAndQuery The url after site root (e.g. '/HomePage/Render?anonymous=true')
devMode True if app runs in development mode
dirty True if framework has detected changes in form model
modal True if form has been loaded inside modal
function example() {
    console.log($info.dirty);
}

$events.on.{eventName}

Add event handlers to the form. Handler function must have the same parameters in terms of order and name as defined in zAppDev.

Attention

Form must be configured to listen the desired event via Form Editor Events tab

$formExtend = function() {
    $events.on.SignIn = function (UserName, Time) {
        alert(UserName, Time);
    }
}

form.user

The currently logged in user object

function example() {
    console.log($form.$user.UserName);
}

It can be used directly in your HTML markup

<h1>Hello, {{$user.UserName}}</h1>

form.username

The currently logged in username.

function example() {
    console.log($form.$username);
}

It can be used directly in your HTML markup

<h1>Hello, {{$username}}</h1>

form.appName

The Application Name

function example() {
    console.log($form.$appName);
}

It can be used directly in your HTML markup

<h1>Welcome to {{$appName}} Application!</h1>

Global Functions


form.userHasRole(role: string)

Checks if currently logged in user has the specified role

function example(role) {
    return $form.$userHasRole(role);
}

It can be used directly in your HTML markup

<button ng-if="$userHasRole('Admin')">Go to Admin Panel</button>

form.userHasPermission(permission: string)

Checks if currently logged in user has the specified permission

function example(perm) {
    return $form.$userHasPermission(perm);
}

It can be used directly in your HTML markup

<button ng-if="$userHasPermission('ManageUsers')">Go to Users Page</button>

form.res(key: string)

Returns a local resource value in the current language

function example() {
    console.log($form.$res('RES_MY_RESOURCE'));
}

It can be used directly in your HTML markup

<h1>{{$res('RES_WELCOME_MESSAGE')}}</h1>

form.resGlobal(key: string)

Returns a global resource value in the current language

function example() {
    console.log($form.$resGlobal('RES_MY_GLOBAL_RESOURCE'));
}

It can be used directly in your HTML markup

<h1>{{$resGlobal('RES_APP_TITLE_RESOURCE')}}</h1>

form.resMaster(key: string)

Returns a Master Page's local resource value in the current language.

function example() {
    console.log($form.$resMaster('RES_MY_MASTER_RESOURCE'));
}

It can be used directly in your HTML markup

<h1>{{$resMaster('RES_MY_MASTER_RESOURCE')}}</h1>

form.resPartial(key: string, partialControlName: string)

Returns a Partial Page's local resource value in the current language

Parameters

Property Description
key Resource Key
partialControlName Partial Control Name
function example() {
    console.log($form.$resPartial('RES_MY_MASTER_RESOURCE', 'PartialControl2'));
}

It can be used directly in your HTML markup

<h1>{{$resPartial('RES_MY_MASTER_RESOURCE', 'PartialControl2')}}</h1>

$updateBindings()

Triggers UI update, according to bindings. It must be called after every change applied to the model programmatically.

function example(username) {
    $form.model.Users.push({ UserName: username }); 
    $updateBindings();
}

$refreshLogic()

Reevaluates Forms Logic (Conditional Formattings, Data Validations and Calculated Expressions).

Attention

Only rules that run ON CHANGE will be evaluated.

function example() {
    $refreshLogic();
}

$controlChanged(control: HtmlElement, newValue: any, [dontMakeFormDirty: boolean])

Notifies the zAppDev App that a control's value has been changed. This can only be used for zAppDev built-in widgets, found in the toolbox.

Parameters

Property Description
control The html element representing the control
newValue The control's new value
dontMakeFormDirty Don't make the form dirty (optional)
function example() {
    var $control = $("#MyInputControl");
    $control.val("NewValue!");

    $controlChanged($control.get(0), $control.val(), true);
}

$showMessage(text: any, type: string, [redirectUrl: string])

Displays a pop up with a message.

Parameters

Property Description
text Pop up text
type Pop up type ('Info', 'Success', 'Warning', 'Error',
redirectUrl (optional) A url to redirct when Pop up OK button is clicked
function example() {
    $showMessage("Form Loaded!", "Success");
}

$closeForm()

Closes form. Redirects to the previous page.

function example() {
    $closeForm();
}

$redirectToUrl(url: string)

Redirects to a url

function example() {    
    $redirectToUrl('www.in.gr');       
}

$redirectToAction(controller: string, action: string, [...params: any])

Redirects to an entry point controller action.

Parameters

Property Description
controller Controller Name
action Action Name
params Action's parameters
function example(user) {    
    $redirectToAction('ManageUser', 'EditUser', user.UserName);       
}

$dataSets.get(dataSetName: string, options: object)

Fetches a form's DataSet.

Note

DataSets requiring parameters or Manual DataSets are not available at the moment.

Parameters

Property Description
dataSetName DataSet Name
options An options object with:
Property Description Remarks
fields An array with field names to be retrieved Example: (['UserName', 'Name', 'Email', 'Roles[].Name', 'Roles[].Permissions.Name'])
Note: When traversing collections the '[]' mark must be used ('Roles[]').
Note: Wrong field names or paths will result in error.
pageSize A number indicating how many records will be retrieved Optional property. Default is 50
startRow A number indicating the first record to be retrieved Optional property. Default is 0
done A callback function that is invoked when data is succesfully retrieved Optional
error A callback function that is invoked when data fails to be retrieved. Optional
complete A callback function that is invoked when request completes Optional
args Arguments array regarding filtering, sorting and grouping Optional. May be structured like:
  • field: the field's name
  • dataType: the fields dataType
  • orderBy: (optional) set ordering for this field. Accepted values are:
    • 'ASC' (for sorting ascending)
    • 'DESC' (for descending)
    • 'LESS_THAN'
    • 'GREATER_THAN'
    • 'LESS_THAN_OR_EQUAL_TO'
    • 'GREATER_THAN_OR_EQUAL_TO'
    • 'LIKE' (default)
    • 'RANGE'
    • 'HAS_VALUE'
    • ''HAS_NO_VALUE''
  • groupBy: (optional) use this to group results by this field. Accepted values are:
    • true (for getting groups with data)
    • 'DATA' (for getting groups with data)
    • 'GROUPS' (for getting groups only)
  • filters: (optional): An array with filter objects for this field. A filter object may be structured like:
    • value: filter value
    • operator: (optional) filter operator. Accepted values are:
      • 'EQUAL_TO'
      • 'NOT_EQUAL_TO'
      • 'LESS_THAN'
      • 'GREATER_THAN'
      • 'LESS_THAN_OR_EQUAL_TO'
      • 'GREATER_THAN_OR_EQUAL_TO'
      • 'LIKE' (default)
      • 'RANGE'
      • 'HAS_VALUE'
      • ''HAS_NO_VALUE''
    • rowOperator: (optional): a logical operator indicating how this filter is combined with others. Accepted values are:
      • 'AND'
      • 'OR' (default)
      • 'GROUPS' (for getting groups only)
    • secondValue: filter value
    • value: second filter value. Use this in combination with 'RANGE' operator.

Structure of Response Object

Property Description
Data an array containing the retrieved record objects
TotalRows the number of ALL rows in this DataSet
Groups an hierarchical object represing the DataSet grouping, when requested
function simpleExample() {
    $dataSets.get("OperationsDataSet", {
        fields: ['Name', 'ParentControllerName'],
        done: function(response) { 
            console.log(response.Data); 
            console.log(response.TotalRows); 
        }
    });
}
function groupingExample() {
    $dataSets.get("OperationsDataSet", {
        fields: ['Name', 'ParentControllerName'],
        args: [
            { field: 'ParentControllerName', dataType: 'string', groupBy: true }
        ],
        done: function(response) { 
            console.log(response.Data); 
            console.log(response.Groups); 
        }
    });
}
function filteringExample() {
    $dataSets.get("UsersDataSet", {
        fields: ['Name', 'UserName', 'Roles[].Name'],
        args: [{
            field: 'UserName',
            dataType: 'string',
            filters: [{ value: 'Admin', operator: 'LIKE'}]
            orderBy: 'asc', 
        }],
        done: function(response) { 
            console.log(response.Data); 
        }
    });
}

$masterDataSets

Same as above for master form's DataSets

$form.dataSets.{controlName}

This is a Javascript object that contains information related to the DataSet of the specified control, as it was last fetched.

Structure

Property Description
Data An array containing all fetched instances
TotalRows The number of total rows in the DataBase that match search filters (if any)
Groups Groups information, if groups were requested
request The DataSet request as sent to the Server

Example in mark up

Total Rows:<b>{{dataSets.List1.TotalRows}}</b>

$master.dataSets.{controlName}

Same as above for master form's DataSets

$events.raise(eventName: string, [...params: any])

Raise an application event.

Parameters

Property Description
eventName Event name
params Event parameters as defined in zAppDev
function example(user) {
    $events.raise("SignIn", user.UserName); 
}