====== Writing Custom JavaScript ======

There are several places within ViziApps where you can insert JavaScript code to transform data, generate and catch events, and extend functionality. This guide will help you get started. If you aren't familiar with JavaScript, please see the **[[#references|References]]** section. 

===== JavaScript in the HTML Header =====
Text that you insert in the HTML header {{::html_header_button.png?nolink&100|}} is simply included into your app's **[[http://www.w3schools.com/html/html_head.asp|HTML header]]** when it runs. JavaScript variables and functions that you define in the HTML header have global scope and may be used throughout your ViziApps app. You are allowed to use %%<meta>, <link>, <style>, and <script>%% tags. You must enclose all JavaScript within %%<script>%% tags when inserting code into the HTML Header, like so:<code>
<script>
var wholename;
function setWholeName( last, first ) {
    wholename = getFieldValue( last ) + ', ' + getFieldValue( first );
    return wholename;
}
</script>
</code>

JavaScript code appearing in the HTML Header executes before your app actually runs (note that function defintions don't actually run unless they are called). This may be useful in certain cases, however you shouldn't reference field names until after the app has been initialized. Here is the way to put code in the HTML Header that won't execute until the app is ready:
<code>
<script>
function appReady() {
    setFieldValue( 'startTimeLabel', (new Date()).toLocaleString() );
}
document.addEventListener("DOMContentLoaded", appReady );
</script>
</code>

===== JavaScript in Field and Data Management Events =====
{{ ::button_tap_event_javascript.png?direct&300|}}There are several places where short snippets of JavaScript can be inserted:
  * Button and Image Button field tap event
  * Table field row tap event
  * Switch and Checkbox field change event
  * Picker field selection event
  * Data Management, Add Device Action

For each event, there are two separate areas where JavaScript can be entered: the first will be called to execute before the event is triggered, and the second will be called after the event completes. This calling sequence is always sequential, however, be aware that JavaScript is an event-driven language, and it's possible that you may call a function in the code before the event triggers, but the called function may not complete until a later time, even after the event and final JavaScript code is executed.

{{ ::data_mgmt_device_action_js.png?direct&300|}}For any Data Management query, you can also insert JavaScript before or after any data command by clicking on the **Add Device Action** button. Like the field events, the data management commands and device action JavaScript are executed in sequential order. This capability for inserting JavaScript is especially handy for manipulating data before or after a command - for example, your app may receive separate firstname and lastname fields from a database, but you would rather show a single string such as:<code>
setWholeName( 'lastname', 'firstname' );
</code>

===== Access to ViziApps Fields =====

=== Get and Set Field Values ===

Many ViziApps fields contain a value that can be set or read through several non-coding methods, such as preset values in the field's properties box; a data query that transfers web data into or out of the field; or a user action such as checking a box or moving a slider. JavaScript lets you programmatically get or set the value of these fields just as if a non-coding action had get or set the value. So for a Hidden Field named //lastname// and a Text Label field named //lastNameLabel//, you could have this code:
<code>
setFieldValue( 'lastNameLabel', 'LAST NAME: ' + getFieldValue( 'lastname' ) );
alert( 'Field set to ' + getFieldValue( 'lastNameLabel' ) );
</code>

=== Table and Picker Selected Values ===

ViziApps Table Fields and Picker Fields work a little differently since they store an array of values, not just a single value. You may have defined a Table with two text fields and a hidden field, so within a Table Field named //contactsTable//, you might have defined field names such as //lastname//, //address//, and //userid//. You can get or set the Table Field name, in which case you would be referencing the particular row that the user has last selected, such as:
<code>
alert( 'The user selected ' + getFieldValue('lastname') + ' at ' + getFieldValue('address') );
</code>

=== Get and Set Array Values ===

There are times where you might want to get or set all of the values held in the Table Field, not just the most recently selected value. In this case, each fieldname represents an array of string values in the order that they appear in the table, so you must set new values with a string array. For example you may have defined a Table Field called //daynameTable// with a variable that is an array of strings named //dayNames//, as in:
<code>
var dayNames = ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'];
setFieldArray( 'dayNameField', dayNames );
console.log( 'The day names are: ' + getFieldArray( 'dayNameField' ) );
// result - The day names are: Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
</code>

===== ViziApps built-in functions (APIs) =====

See the **[[ViziApps JavaScript Function Reference]]** for a list and description of the functions that are available for you to use. These functions can: get and set ViziApps field values; change the page; get GPS values; and more. Following are examples of a few important functions.

=== Page Control ===

Programatic change to a new page is often done as a Device Action within Data Management, or as a response to a user tap event before a query.
<code>
v.gotoPage('page_name');
</code>

=== Alert ===

To popup an alert named 'alert_field_name':
<code>
v.showAlert('alert_field_name','Important, Please Read:','This is the alert message');
</code>

=== Loading Indicator ===

To show and hide a loading indicator to the user:
<code>
// shows the loading indicator for 5 seconds
function doneLoadingHandler() {
    v.hideLoading();
}
v.showLoading();
setTimeout( doneLoadingHandler, 5000 );
</code>

=== Hide and Show a Field ===

ViziApps fields can be hidden or made visible:
<code>
function showHideField( fieldName, showConditionField ) {
    var showit = v.getFieldValue( showConditionField );
    if ( showit === false || showit === 'false' || showit === 'off' || showit === 0 )
        v.hideField( fieldName );
    else
        v.showField( fieldName );
}
showHideField( 'optionButtonField', 'optionConditionHiddenField' );
</code>

===== References =====

<WRAP col2>

**[[http://www.w3schools.com/js/default.asp|W3Schools JavaScript Tutorial]]**

**[[http://www.w3schools.com/jsref/default.asp|W3Schools JavaScript Reference]]**

**[[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide|Mozilla Developer Network JavaScript Guide]]**

**[[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference|Mozilla Developer Network JavaScript Reference]]**

**[[http://www.pagecolumn.com/tool/regtest.htm|Online JavaScript Regular Expression Tester]]**

**[[http://dl.e-book-free.com/2013/07/javascript_cookbook.pdf|O'Reilly JavaScript Cookbook]]**

**[[http://cordova.apache.org/docs/en/edge/|Apache Cordova Documentation]]**

</WRAP>