MicroApp Dev: JavaScript Helper Functions

These functions (callable by app.______), are available within your app's local context, and can be helpful in providing basic interactivity and other standard functionality within your app.

Note: While app.data is available most everywhere, the app helper functions mentioned in this document are only available within the context of the this.callback function. Please ensure that you have defined a this.callback function to ensure full access to the functions below.

Table of Contents
app.alert
app.click
app.delete
app.form
app.get
app.grid
app.modal
app.options
app.post
app.put
app.refresh
app.render
app.update

app.alert(options)

This function initiates a temporary popup alert based on the options supplied.

Argument	Type	Description
options	String / Object	This required field is either an alert String or Object which configures the alert.
options.title	String	Optional title affiliated with the alert
options.content	String	Optional body affiliated with the alert
options.status	String	Optional color of the alert: (info, warning, error, success)

// Examples
app.alert({"title":"Hello","content":"World!","status":"warning"})
app.alert("Hello World!")

app.click(selector, callback)

This function registers a callback which is triggered when a user clicks on a DOM element matching the specified selector.

Argument	Type	Description
selector	String	This is the CSS selector string which maps to the element that should trigger a click event
callback	Function	This is the function that is called when the click event is triggered

// Example
app.click('#my-button',function(e) {
  // The button was clicked!
});

app.delete(resource_name, data, callback_success, callback_failure?)

This function performs an AJAX request to a resource using the HTTP 'DELETE' verb.

Note: the contents of the supplied "data" object are sent as x-www-form-urlencoded data to the defined resource API. For example {"id":0} is translated to id=0 and sent with a Content-Type: application/x-www-form-urlencoded header. This may change to support Content-Type: application/json encoded payloads at a later date, but is not supported currently

Argument	Type	Description
resource_name	String	This is the name of the resource as defined in the micro app definition
data	Object	This is an object which contains the data to be sent. (Data is encoded as x-www-form-urlencoded data as part of the request. The "x-www-form-urlencoded" header is sent as part of the request.)
callback_success	Function	This is the function which will be called upon success (HTTP "200" Response Code)
callback_failure	Function	This is an optional function which will be called upon failure (Non "200" Response Code)

// Example
app.delete('colors',{'id':0},function(response) {
  // Hooray!
},function(response) {
  // There was an error :-(!
});

app.form(form,selector?)

This function instantiates and returns an instance of the GrapheneForms form as defined in Micro App "Forms" tab, and optionally binds to a specified DOM element. Subsequent calls to app.form with the same form name will return the same form which was previously instantiated. Once a form has been bound to an element, it cannot be rebound to a different element without first destroying the form.

Argument	Type	Description
form	String / Object	This required field is either the name of a form (as defined in the Micro App "Forms" tab, or a GrapheneForms object definition.
selector	String	This optional field is a "css selector" to a given DOM element contained within the Micro App. Example: "#my-form"

// BASIC FORM EXAMPLE
// This will bind the form with the name "myForm" to a DOM element with the class "my-form-here"
// When a user clicks the save button (triggers the save event), the form data will be
// printed to the console.
app.form('myForm','.my-form-here').on('save',function(form_event){ 
  form_data = form_event.form.get();
  console.log(form_data)
});

// BASIC FORM-MODAL EXAMPLE
// When a user clicks the "save" button (triggers the save event), the form data will be
// printed to the console, and the modal will be closed.
// When a user clicks the "cancel" button, the modal will be closed with no further actions
app.form('myForm').modal().on('save',function(form_event){ 
  console.log(form_event.form.get())
  form_event.form.trigger('close');
}).on('cancel',function(form_event){ 
  form_event.form.trigger('close');
});

// PRE-SETTING DATA EXAMPLE
// The form will be pre-populated with first_name "John", and last_name "Doe"
app.form('myForm','.my-form-here').set({'first_name':'John','last_name':'Doe'});

// VALIDATION EXAMPLE
// Form validation is checked
app.form('myForm','.my-form-here').on('save',function(form_event){ 
  if (form_event.form.validate()) {
    app.alert('Form Passed Validation');
  } else {
    app.alert('Form Failed Validation');
  }
});

app.get(resource_name, data, callback_success, callback_failure?)

This function performs an AJAX request to a resource using the HTTP 'GET' verb.

Note: the contents of the supplied "data" object are appended as query parameters to the resource URL. For example {"id":0} is translated to ?id=0.

Argument	Type	Description
resource_name	String	This is the name of the resource as defined in the micro app definition
data	Object	This is an object which contains the data to be sent. (Data is encoded as a standard URI "query" as part of the request)
callback_success	Function	This is the function which will be called upon success (HTTP "200" Response Code)
callback_failure	Function	This is an optional which will be called upon failure (Non "200" Response Code)

// Example
app.get('colors',{'id':0},function(response) {
  // Hooray!
},function(response) {
  // There was an error :-(!
});

app.grid(name, options)

This function instantiates and returns an instance of the GrapheneDataGrid grid.

Argument	Type	Description
name	String	This required field is the name of a grid
options	Object	This required field contains the options for configuring your GrapheneDataGrid

// Examples
app.grid('Data',{
   el: '#my-form-element', 
   resource: "gridData",
   form:"myForm"
})

app.modal(options)

This function opens a modal based on the options supplied.

Argument	Type	Description
options	Object	This required field is an Object which configures the modal.
options.title	String	Optional title affiliated with the modal
options.content	String	Optional body affiliated with the modal
options.status	String	Optional color of the modal title bar: (info, warning, error, success)

// Examples
app.modal({"title":"Hello","content":"Here is the content!","status":"warning"})

app.options(data)

Sets the user's "user options" for the current app instance.

Argument	Type	Description
data	Object	Set the user options to the value of the data object

// Example
app.options({"settings":true});

app.post(resource_name, data, callback_success, callback_failure?)

This function performs an AJAX request to a resource using the HTTP 'POST' verb.

Note: the contents of the supplied "data" object are sent as x-www-form-urlencoded data to the defined resource API. For example {"id":0} is translated to id=0 and sent with a Content-Type: application/x-www-form-urlencoded header. This may change to support Content-Type: application/json encoded payloads at a later date, but is not supported currently

Argument	Type	Description
resource_name	String	This is the name of the resource as defined in the micro app definition
data	Object	This is an object which contains the data to be sent. (Data is encoded as x-www-form-urlencoded data as part of the request. The "x-www-form-urlencoded" header is sent as part of the request.)
callback_success	Function	This is the function which will be called upon success (HTTP "200" Response Code)
callback_failure	Function	This is an optional which will be called upon failure (Non "200" Response Code)

// Example
app.post('colors',{'color':'blue},function(response) {
  // Hooray!
},function(response) {
  // There was an error :-(!
});

app.put(resource_name, data, callback_success, callback_failure?)

This function performs an AJAX request to a resource using the HTTP 'PUT' verb.

Note: the contents of the supplied "data" object are sent as x-www-form-urlencoded data to the defined resource API. For example {"id":0} is translated to id=0 and sent with a Content-Type: application/x-www-form-urlencoded header. This may change to support Content-Type: application/json encoded payloads at a later date, but is not supported currently

Argument	Type	Description
resource_name	String	This is the name of the resource as defined in the micro app definition
data	Object	This is an object which contains the data to be sent. (Data is encoded as x-www-form-urlencoded data as part of the request. The "x-www-form-urlencoded" header is sent as part of the request.)
callback_success	Function	This is the function which will be called upon success (HTTP "200" Response Code)
callback_failure	Function	This is an optional which will be called upon failure (Non "200" Response Code)

// Example
app.put('colors',{'id':0,'color':'red},function(response) {
  // Hooray!
},function(response) {
  // There was an error :-(!
});

app.refresh()

This function completely refreshes the application. This includes refetching / initializing the data, and redrawing all templates, etc. This function accepts no parameters.

// Example
app.refresh();

app.render(template, data)

This function returns a rendered mustache template (via a specified template name), using the data provided.

Argument	Type	Description
template	String	The name of a template, as defined in the "Templates" section of the Micro App
data	Object	Data to pass to the mustache renderer

// Example 1:
// test_template content:
// My Favorite Color is: {{color}}

var output = app.render('test_template',{"color":"blue"})
console.log(output)

// Printed to Console:
// My Favorite Color is: blue

app.update(data?)

This function does the following:

• Updates the app.data object
• Instructs the template rendering engine (Ractive) to re-render the templates (with updated data)
• Instructs the form engine (Graphene Forms) to reprocess / reload any resources (with updated data)

This function should be called whenever the app data object is updated. Optionally, this function may accept parameters which will directly update the app data object.

Argument	Type	Description
data	Object	This is an optional data object which will be merged into the existing app data object, and serves as an easy way to update the app data object without performing an additional external assignment

// Examples
app.data.favorite_color = blue;
app.update();

app.update({"favorite_color":"blue"});