Javascript API
Outlast Framework has a built-in Javascript API which aims to ease some framework-specific functionality.
All properties and methods are via the globally available zaj object which -in newer system versions- has been renamed to ofw.
You can view the full API docs below or you can see some of our specialty documentation on ajax requests, push-state support, and others (see bottom of menu on left)
Set up
To enable the Outlast Framework Javascript API, you’ll need to include the jslib-specific version of the API. Right now, we fully support jQuery, but may eventually include other libraries in the future. MooTools was supported in earlier versions.
<!-- jquery (required) -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<!-- outlast framework js (required) -->
<script language="JavaScript" src="{{baseurl}}system/js/mozajik-base-jquery.js{% cachebuster %}" type="text/javascript"></script>
<!-- bootstrap js (optional) -->
<script language="JavaScript" src="{{baseurl}}system/js/bootstrap/bootstrap.min.js" type="text/javascript"></script>
<!-- my init script (required) -->
{{ofw.js|safe}}
Notice that we’ve also included the Bootstrap js file. For some operations, Bootstrap js methods are supported. Including it is optional.
The {{ofw.js|safe}} init script is required to fully enable API features. The |safe filter is required since the variable contains javascript, but is safe from XSS vulnerabilities (see docs).
Properties
Once the init script ({{ofw.js|safe}}) has been included you have access to the following properties via the window.ofw (or more simply ofw)) global javascript object. Example usage would be:
<script> // Useless random code to illustrate JS API property access var my_baseurl = ofw.baseurl; </script>
Here are the properties:
baseurl – string – The base url. Usually the domain plus any subfolder (if app is running in a subfolder).
fullrequest – string – The full request with query string.
fullurl – string – The full url without query string.
app – string – The current app.
mode – string – The current mode.
debug_mode – boolean – True if in debug mode, false if not.
protocol – string – The current protocol. http or https.
jslib – string – The Javascript library name supported in this version of OFW API (usually jquery).
jslibver – string – The minimum Javascript library version supported in this version of OFW API.
trackevents_analytics – boolean – true – If set to true, Analytics events will be tracked via ofw.track(). You can change this setting in the site/index.php settings file as well.
trackevents_local – boolean – false – If set to false, events with ofw.track() will not be saved locally. You can change this setting in the site/index.php settings file as well.
pushstate – boolean – Will be true if the browser supports push state features.
bootstrap – boolean – Will be true if Bootstrap js is included.
bootstrap3 – boolean – Will be true if Bootstrap 3 js is included. False if just Bootstrap 2.
facebook – boolean – Will be true if Facebook js is included.
fbcanvas – boolean|object – False if canvas info not available. Will contain Facebook canvas info once it becomes available, if at all.
mobile – boolean – Will be true if this is a mobile device. It uses user-agent detection, so not typically recommended.
locale – string – The current locale string (for example ‘en_US’).
fields – object – An object of field objects. Used internally by OFW.
ofw.ready()
Ready is just a layer for various onready functions. Typically it is identical to jQuery’s $(document).ready().
{function} func The callback function.
ofw.log()
A wrapper for console.log() that does not run if the console object is not present. This makes it backwards compatible with old browsers and/or ones without developer tools installed.
{string} message The message to log.
{string} type Can be notice, warning, or error
{string} context The context is any other element or object which will be logged.
@return {boolean|object} Returns true or console.log.
There are some variations of ofw.log(). They take message and context as parameters and include the following:
ofw.error()– same as console.error()ofw.warning()– same as console.warn()ofw.notice()– same as console.info()
Unlike console methods however, ofw.* methods only take one parameter and one context object.
ofw.alert()
Custom alerts, confirms, prompts. If bootstrap is enabled, it will use modal. Otherwise the standard blocking alert() will be used.
Parameters
{string} message The message to alert.
{string|function|jQuery} [urlORfunctionORdom=null] A callback url or function on button push. If you set this to a jQuery dom object then it will be used as the modal markup.
{string|boolean} [buttonText="Ok"] The text of the button. Set to false to hide the button.
{boolean} [top=false] Set to true if you want the url to load in window.top.location. Defaults to false.
@return {jQuery} Will return the popup modal jQuery object.
There are two ways of invoking ofw.alert(). If you want to use the default markup generated by Outlast Framework using Bootstrap you can simply call it, optionally with the parameters specified:
ofw.alert('Hello world!');
ofw.alert('Hello world!', function(){ alert('you clicked done') }, 'Done');
You can also create your own Bootstrap modal markup and then use ofw alert to add content:
$('#my-bootstrap-modal').$ofw().alert('This will go in modal-body.');
ofw.redirect()
Redirect to a page. Unlike window.location() it can be relative to baseurl. It can also be an absolute url.
Parameters
{string} relative_or_absolute_url The URL relative to ofw.baseurl. If it starts with // or http or https it is considered an absolute url
{boolean} [top=false] Set this to true if you want it to load in the top iframe.
ofw.reload()
Reload the current url. It used to work differently under various browsers but it’s just window.location.reload(false);. No parameters, no return value.
ofw.track()
Track events in GA and/or locally. Event labels/etc are whatever you want them to be.
Parameters
{string} category A category.
{string} action An action.
{string} label A label.
{string} [value] A value (optional).
ofw.exception()
Send an exception to Google Analytics Exception Tracking.
Parameters
{string} message A full message containing the error information.
{boolean} fatal True if this is a fatal error. Defaults to false.
ofw.ajax.get()
Send an ajax request via GET. You can add query string parameters to the url. The URL is usually given as relative to baseurl but it can also be a full, absolute url.
@param {string} request The relative or absolute url. Anything that starts with http or https is considered an absolute url. Others will be prepended with the project baseurl.
@param {function|string|object|null} result The item which should process the results. Can be function (see docs), a string (will redirect to this relative url if success, popup if failed), a DOM element object (results will be filled in here), or it can be empty (nothing will happen on callback).
@param {string|object|boolean} [pushstate=false] If it is just a string, it will be the url for the pushState. If it is a boolean true, the current request will be used. If it is an object, you can specify all three params of pushState: data, title, url. If boolean false (the default), pushstate will not be used.
ofw.ajax.post()
Same as ofw.ajax.get() but the request is sent via POST. You can add the POST data to the request URL in the query string just like for GET.
When submitting forms, you should typically opt for ofw.ajax.submit() instead (see below).
{string} request The relative or absolute url. Anything that starts with http or https is considered an absolute url. Others will be prepended with the project baseurl.
@param {function|string|object|null} result The item which should process the results. Can be function (see docs), a string (will redirect to this relative url if success, popup if failed), a DOM element object (results will be filled in here), or it can be empty (nothing will happen on callback).
@param {string|object|boolean} [pushstate=false] If it is just a string, it will be the url for the pushState. If it is a boolean true, the current request will be used. If it is an object, you can specify all three params of pushState: data, title, url. If boolean false (the default), pushstate will not be used.
ofw.ajax.submit()
Same as ofw.ajax.post() but it sends a blocked ajax request. This meanst that while the POST is in progress, all other submit() actions will be ignored (not queued, but completely ignored) to avoid double clicks or multiple submissions. It also makes it really easy to display a progress indicator while the endpoint is processing the request. See docs on ajax requests for more info.
There is another form of this method which is usually more convenient when working with forms:
$('#formselector').$ofw().submit('/submit/to/here', function(r, rJson){ /** process results **/ });
{string} request The relative or absolute url. Anything that starts with http or https is considered an absolute url. Others will be prepended with the project baseurl.
{function|string|object|null} result The item which should process the results. Can be function (see docs), a string (will redirect to this relative url if success, popup if failed), a DOM element object (results will be filled in here), or it can be empty (nothing will happen on callback).
{string|object|boolean} [pushstate=false] If it is just a string, it will be the url for the pushState. If it is a boolean true, the current request will be used. If it is an object, you can specify all three params of pushState: data, title, url. If boolean false (the default), pushstate will not be used.
ofw.ajax.api()
Send request with structured data to an API endpoint and receive the results.
This is similar to other ajax request methods, but instead of a query string, you need to pass a data argument that contains the key/value pairs of data to be sent to the server.
{string} endpoint The relative or absolute url of the endpoint.
{object} data An object containing all of the data that should be passed in key/value pairs.
{function|string|object} result The item which should process the results. Can be function (see docs), a string (considered a url to redirect to), or a DOM element object (results will be filled in here).
{string} [method="POST"] Can be POST (the default) or GET depending on the necessary HTTP request method.
ofw.ajax.alert()
This will send an ajax request via GET and display the result using ofw.alert(). This is a useful shorthand for doing the same thing via ofw.ajax.get() with a custom callback function.
{string} request The relative or absolute url. Anything that starts with http or https is considered an absolute url. Others will be prepended with the project baseurl.
{string|function|jQuery} [urlORfunctionORdom=null] A callback url or function on button push. If you set this to a jQuery dom object then it will be used as the modal markup.
{string|boolean} [buttonText="Ok"] The text of the button. Set to false to hide the button.
{boolean} [top=false] Set to true if you want the url to load in window.top.location. Defaults to false.
{string|object|boolean} [pushstate=false] If it is just a string, it will be the url for the pushState. If it is a boolean true, the current request will be used. If it is an object, you can specify all three params of pushState: data, title, url. If boolean false (the default), pushstate will not be used.
One typical use would be to display things like terms and conditions, cookie policies, etc.
ofw.validate()
You can use validate() to perform client side validation on a standardized OFW ajax response. {string} response The response to validate. This should be a string value that is returned by an ajax request. Here’s an example:
ofw.isEmailValid()
Use isEmailValid() to check if the email address is valid. Returns true if valid, false if not.
{string} email The email address to test.
ofw.scroll()
Animated scroll to a specific position or a specific element on page. Also works within Facebook iFrames.
Scroll to a specific position:
{Number} y The pixel value of where to scroll to.
{Number} [duration=1000] The number of miliseconds for the animation. Defaults to 1 second (1000 ms).
ofw.scroll(500);
Scroll to an element:
{object|string} domORselector The jQuery object, a dom object, or a selector that you want to scroll to.
{Number} [duration=1000] The number of miliseconds for the animation. Defaults to 1 second (1000 ms).
ofw.scroll('div#myid', 2000);
ofw.inViewPort()
Checks to see if an element is in the viewport.
{string|object} el A DOM element, jQuery object, or selector string.
{boolean} [partially=true] If set to true (default), it will return true if element is at least in part visible.
@return {boolean} Returns true if element is in viewport, false if it is not.
ofw.window()
A function which opens up a new window with the specified properties.
{string} url The url of the window
{integer} width The width in pixels.
{integer} height The height in pixels
{string} options All other options as an object. (optional)
@return {window} Returns the window object.
ofw.setLang()
Set an array of objects to enable specific language variable key/value pairs. You should usually use {% langjs %} tag instead of this directly. See docs on this for more details.
{string|object} keyOrArray This can be an array of objects where each item has a key, section, and value. Or it can be just a key.
{string} value If you are using a key in the first param, this is the value.
{string} [section=null] The section in which the lang variable is found. This is optional.
ofw.urlencode()
URLencodes a string so that it can safely be submitted in a GET query. Just uses encodeURIComponent so this may be deprecated in a future version.
{string} url The url to encode.
@return {string} The url in encoded form.
ofw.queryMode()
Adds a ? or & to the end of the URL – whichever is needed before you add a query string.
{string} url The url to inspect and prepare for a query string.
@return {string} Returns a url with ? added if no query string or & added if it already has a query string.
ofw.htmlEscape()
Encode html characters.
{string} str The incoming string.
@return {string} Returns a string in which html entities are escaped.
ofw.htmlUnescape()
Decode html characters.
{string} str The incoming string.
@return {string} Returns a string in which escaped html entities are converted back to their normal state.
ofw.sortable()
Enables sortable features on a list of items. Requires jquery-ui sortable feature. Works together with zajModel::reorder() method.
Calling the method multiple times will destroy and reinitialize it.
{string} target The items to sort. Each item must have an data-sortable field corresponding to the id of item.
{string} url The url which will handle this sortable request. This handling controller typically contains the zajModel::reorder() method.
{function} callback An optional callback function which is called when the sort is completed (even on server side). It is passed an array of ids with the new order.
Here’s an example usage:
ofw.search()
When applied to text input, ofw search sends ajax requests after a specified interval to a given url. This is useful to create inline search boxes with great performance. Can work together with zajModel::search() in order to provide a quick search implementation for model data.
Unlike others, ofw.search is an object and has an initialize() and send() method. However, you’ll mostly use the jQuery object extension. This is documented below.
{string} url The url which will handle this search request. The search query is sent via GET (by default) in the $_GET[‘query’] parameter.
{string|function} receiver The jQuery selector or callback function that receives the HTML response from the search query.
{object} [options={}] Additional options you want to pass to zaj.search(). See below.
There are a few ways to use the search helper.
You can insert results directly into a specific jQuery dom object:
$('input#seachbox').$zaj().search('search/inline/', $('#results'));
You can also add a callback function to handle the results:
$('input#seachbox').$zaj().search('search/inline/', function(r){
// Do something here with the result r
}
Use the third, optional parameter to customize the zaj.search() object. Here are a list of available options:
{integer} delay=300 The delay after keyup before sending the request. A larger delay puts less strain on the server but provides less responsive UX.
{string} method="get" Defines the request method. Can be ‘get’ (the default) or ‘post’.
{boolean} allow_empty_query=true If set to true (default), it will also send the empty query (when nothing is in the text box).
{string|boolean} pushstate_url='auto' If set to ‘auto’, the url will automatically change via pushstate. If you set it to any other string, it will set the url via pushstate to that string. If you want to disable pushstate support, set this to false.
ofw.inProgress()
With inProgress method you’re able to show/hide custom “in progress” animation. The method searches for HTML elements with data-inprogress-class attribute, which represents the DOM selector class of a custom “in progress” animation element. The value of data-inprogress-class attribute will be added when you show (set inProgress to true) and removed when you hide (set inProgress to false).
For ajax request you can (and should) use visual feedback for blocking requests. You should use inProgress when you have other, time-consuming, non-ajax operations.
{boolean} show show/hide “in progress” animation element
This example code will show a Bootstrap 3 striped progress bar programmatically:
<script>
ofw.inProgress(true);
</script>
<style>
.myprogress { display: none }
.inprogress { display: block !important;}
</style>
<div class="progress myprogress" data-inprogress-class="inprogress">
<div class="progress-bar progress-bar-striped active" role="progressbar" style="width:100%">
In progress
</div>
</div>