Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
protogrid:script_library [2017-11-10 10:57] sblprotogrid:script_library [2022-05-16 15:35] (current) – [Execute JS on field change] dru
Line 1: Line 1:
-====== Script Library ======+====== ScriptLibrary ======
  
 Protogrid can be extended arbitrarily using [[https://www.w3schools.com/js/|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. Protogrid can be extended arbitrarily using [[https://www.w3schools.com/js/|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 ScriptLibrary =====
  
-Server-side libraries contain code happening at the server before sending the data to the client. Every [[protogrid:proto|Proto]] can have a server side library attached. Whenever something is done with a [[protogrid:card|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.  +Server ScriptLibraries contain code happening at the server before sending the data to the client. Every [[protogrid:proto|Proto]] can have a server side library attached. Whenever something is done with a [[protogrid:card|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 ==== 
-on_render gets called when opening a new Card. This function can be used for example to [[protogrid:hide_field| 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).  +on_render gets called when opening a new Card. This function can be used for example to [[protogrid:hide_field| 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, it is a newly created Card).  
-<code>+<code javascript>
 function on_render(card, before_first_save) { function on_render(card, before_first_save) {
     ...     ...
 } }
 </code> </code>
-==on_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. 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.
-<code>+<code javascript>
 function on_save(card, before_first_save, ref_validation_errors) { function on_save(card, before_first_save, ref_validation_errors) {
     ...     ...
Line 21: Line 21:
 </code> </code>
  
-== get_shortname == +==== get_shortname ==== 
-This function is supposed to return a string that defines a Card'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). +This function is supposed to return a string that defines a Card'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). 
-<code>+<code javascript>
 function get_shortname(card) { function get_shortname(card) {
     ...     ...
Line 30: Line 30:
 </code> </code>
  
-== get_title ==+==== 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". 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".
-<code>+<code javascript>
 function get_title(card, before_first_save) { function get_title(card, before_first_save) {
     ...     ...
     return ...     return ...
 +}
 +</code>
 +
 +===== Client ScriptLibrary =====
 +The client-side script library contains all the code happening locally on the clients machine. This contains all the code executed when [[protogrid:trigger|triggered]] by a client action, especially the code that should be executed at [[protogrid:button|button]] clicks.
 +
 +Please note that all your code should reside within a enclosing function in order to limit its scope and avoid naming conflicts. Protogrid supports you in this by automatically providing such an enclosing function in the default Client ScriptLibrary and dynamically replacing the identifier of this enclosing function with the name of the Client ScriptLibrary before loading it into the browser. However, you are free to set your own static unique identifier for this function.
 +
 +==== Execute JS on card load ====
 +
 +To execute some JavaScript code at the time, a card is loaded, there are two options. 
 +
 +If you want to execute this code only for one proto, you add the code inside a Client ScriptLibrary and make sure you have a Trigger on the Proto which is linked with this ScriptLibrary. This will make the browser to load all code when the cards are loaded and the browser will execute all code on loading of the ScriptLibrary, which is not enclosed in a function. So just add in the ScriptLibrary:
 +
 +<code javascript>
 +on_load();
 +function on_load() {
 +    alert("Hello World!");
 +    //do something more useful
 +}
 +</code>
 +
 +If you want the code to be executed on load of every card, write your code into a separate JavaScript file and load it into the attachments section on the "Code"-Card. This attachments will be loaded whenever any Card is loaded and therefore will be executed on any card load.
 +
 +==== Execute JS on field change ====
 +
 +To execute some JavaScript when a field value changes, you need to add the following code-snippet to a client-side Script library, which is linked to the Proto with some Trigger. The variable "field_key_my_field" has to be set to the [[protogrid:field|fieldkey]] of the field you want to observe. "my_function()" is the function you want to call when something changes.
 +
 +<code javascript>
 +function my_function(){
 +    //do something here
 +}
 +
 +function document_ready_trigger() {    
 +    $("#" + field_key_my_field).on('change', function () {
 +        my_function();
 +    });
 +}
 +
 +$(document).ready(function () {
 +    document_ready_trigger();
 +});
 +</code>
 +
 +The function document_ready_trigger tells your card that you want something to happen when a value changes. The call "$(document).ready(...)" itself calls the function "document_ready_trigger" as soon as the card is fully loaded.
 +
 +==== Activate Save Buttons ====
 +After a manipulation of Fields on a Card you might want to activate the save buttons in order to let the user save the modified Card. Just call modifications_on_current_card() after setting a field value:
 +<code javascript>
 +var csl_helpers = mod_csl_helpers();
 +csl_helpers.set_value(csl_keys.field_key_sample_field, "just a test");
 +modifications_on_current_card();
 +</code>
 +==== Manipulate Contet of Rich Text Field ====
 +
 +<code javascript>
 +var rich_text_editor = $("#" + $.escapeSelector(rich_text_field_id))[0].editor;       // Get object of Rich Text Editor
 +
 +var content = rich_text_editor.getDocument().toString();                              // Get complete content as string
 +var current_range = rich_text_editor.getSelectedRange();                              // Get cursor posistion / selected text range
 +
 +rich_text_editor.setSelectedRange([0, 0]);                                            // Set cursor to position 0
 +rich_text_editor.setSelectedRange([0, 10]);                                           // Set text selection from position 0 to position 10
 +rich_text_editor.insertString("Hello!"                                              // Insert String at selected position
 +rich_text_editor.insertHTML("<strong>Hello World!</strong>");                         // Insert HTML at selected position
 +rich_text_editor.insertLineBreak();                                                   // Insert line break
 +rich_text_editor.deleteInDirection("forward");                                        // Delete selected range
 +rich_text_editor.activateAttribute("bold"                                           // Activate attribute at selected range
 +rich_text_editor.deactivateAttribute("strike"                                       // Deactivate attribute at selected range
 </code> </code>
  
-=== Client-side Script Library === +Please see https://github.com/basecamp/trix for details.
-The client-side script library contains all the code happening locally on the clients machineThis contains all the code executed when [[protogrid:trigger|triggered]] by a client action, especially the code that should be executed at [[protogrid:button|button]] clicks+
Print/export