This is an old revision of the document!


Script Library

Protogrid can be extended arbitrarily using Java script libraries. The libraries are located at the “Code”-Tab in the Design-Tab. We differentiate two types of script libraries: server-side and client-side. The can be several libraries per type. On creation of the libraries, they already contain some code and some explanations to fast understand what to do.

Server-side Script Library

Server-side libraries contain code happening at the server before sending the data to the client. Every Proto can have a server side library attached. Whenever something is done with a Card of this Proto on the server, the Server takes the assigned library into account. The server-side libraries contain mainly the following functions: on_render, on_save, get_shortname, get_title.

on_render

on_render gets called when opening a new Card. This function can be used for example to hide fields of the Card. Inside the on_render function, one has access to the card which is opening as well as to a predicate called “before_first_save” telling you whether the Card was already saved before or not (if not, if is a newly created Card).

function on_render(card, before_first_save) {
    ...
}
on_save

The on_save function can for example be used to do some computations or assertions before saving. The function has access to the card, the predicate “before_first_save” and an object called “ref_validation_errors” containing all previous validation errors thrown by Protogrid. For each field containing an error, the object contains a field key pointing to an Error String that is shown to the user. By adding new properties to this object, you can add validation Errors of your own. If this object is not empty when on_save returns, the Card will not be saved.

function on_save(card, before_first_save, ref_validation_errors) {
    ...
}
get_shortname

This function is supposed to return a string that defines a Card's shortname. Shortnames are used in relation fields and TableView columns. They should somehow identify the individual Cards. Short names must not contain confidential information (information that only a subset of users in your app may access).

function get_shortname(card) {
    ...
    return ...
}
get_title

This function should return a string that defines a Card's title. Titles are being used exclusively in the Card's title row when it is opened. By default, the Card's title is defined by its shortname if you don't override it using this function. You have access to the card and the predicate “before_first_save”.

function get_title(card, before_first_save) {
    ...
    return ...

Client-side Script Library

The client-side script library contains all the code happening locally on the clients machine. This contains all the code executed when triggered by a client action, especially the code that should be executed at button clicks.

Print/export