Iris exposes all of its methods and properties on the iris object:
- Core
- Util
- Event
- Language & Regional
- Components
- Classes
Since: v0.5.0
Set the base URL applied to load Iris components like screens, UIs & resources.
// You can define paths as
iris.path = {
screen : {
js: "./path/to/iris/components/screen.js",
html: "./path/to/iris/components/screen.html"
}
};
// Or you can use iris.baseUri to short paths
iris.path = {
screen : {
js: "screen.js",
html: "screen.html"
}
};
iris.baseUri("./path/to/iris/components/");Since: v0.5.0
Set or get a boolean value that indicates whether Iris' calls are cached or not. In local environments (localhost, 127.0.0.1) the cache are disabled by default.
// Getter
iris.cache();
// Setter
iris.cache(true);Since: v0.5.0
Set or get a value that will be added as query parameter in all Iris' ajax calls. You can use it to force Iris' components to be cached with a version string. By default cache version is disabled.
// Getter
iris.cacheVersion();
// Setter
iris.cacheVersion("v1.0");Since: v0.5.0
Disable browser cache adding a timestamp param (e.g.: url?_=1374053849520) on each HTTP call when the environment match with the current URL.
// By default iris executes:
iris.noCache("localhost", "127.0.0.1");Since: v0.5.0
Enable or disable the iris.log outputs according to the current URL.
// Enable logs only in development hosts
iris.enableLog("localhost", "dev.example.com", "int.example.com");Since v0.5.5, you can enable or disable iris logs using a boolean, e.g.:
iris.enableLog(false); // Disable all iris logsSince: v0.5.0
Prints the parameters values to the console for debugging purposes.
If logging is disabled, it doesn't print any.
To enable or disable logging use iris.enableLog.
It uses the native console.log and works in all modern browsers and IE8+.
// Basic example
iris.log("Hello world!");// Multiple parameters
iris.log("obj = ", obj, " obj2 = ", obj2);// Enable logs only in the development machine
iris.enableLog("127.0.1.30");
iris.log("This is only printed in 127.0.1.30");Since: v0.5.7
Returns true if document.location.href contains localhost or 127.0.0.1.
if ( iris.isLocalhost() ) {
// do something
}Since: v0.5.0
Perform an HTTP (Ajax) request. Accepts the same parameters as jQuery.ajax() See JQuery Ajax for more details. Returns a jQuery jqXHR object.
iris.ajax({
"url" : "http://www.example.com/",
"type" : "GET"
}).done(successCallback).fail(errorCallback);Since: v0.5.0
Get value from Javascript object using a label string. You can use dot to get object's children.
var book = {
author : {
name : "value"
}
};
var authorName = iris.val(book, "author.name");Since: v0.5.0
Formats a Date object or timestamp to the specified format and according to the current locale. See Language & Regional for more information. You can use the following special characters:
- a 'a.m.' or 'p.m.'
- A 'AM' or 'PM'
- b Month, textual, 3 letters, lowercase. 'jan'
- d Day of the month, 2 digits with leading zeros. '01' to '31'
- D Day of the week, textual, 3 letters. 'Fri'
- F Month, textual, long. 'January'
- h Hour, 12-hour format. '01' to '12'
- H Hour, 24-hour format. '00' to '23'
- i Minutes. '00' to '59'
- l Day of the week, textual, long. 'Friday'
- m Month, 2 digits with leading zeros. '01' to '12'
- M Month, textual, 3 letters. 'Jan'
- n Month without leading zeros. '1' to '12'
- s Seconds, 2 digits with leading zeros. '00' to '59'
- U Seconds since the Unix Epoch (January 1 1970 00:00:00 UTC)
- y Year, 2 digits. '99'
- Y Year, 4 digits. '1999'
iris.date(new Date(),"ymd");
iris.date(1331954654564,"d/m/y h:i:s"); // "17/03/12 04:24:14"
iris.date("Thu Feb 14 2013 12:42:49 GMT+0100 (CET)", "d-m-Y"); // "14-02-2013"Since: v0.5.0
Formats a number according to the current locale or config values.
See Language & Regional for more information.
Default config value are:
{
formatPos: "n",
formatNeg: "- n",
decimal: ".",
thousand: ",",
precision: 2
}e.g. :
iris.locale(
"es_ES", {
number : {
decimal: ",",
thousand: ".",
precision: 2
}
}
);
iris.number(5600.899); // "5.600,90"
iris.number(5600.899, { precision: 0 }); // "5.601"
iris.number(5600.899, {
decimal: ".",
thousand: ",",
precision: 1
}); // "5,600.9"Since: v0.5.0
Formats a amount according to the current locale or config values.
See Language & Regional for more information.
Default config value are:
{
formatPos: "sn",
formatNeg: "(sn)",
symbol : "$"
}e.g. :
iris.locale(
"es_ES", {
currency : {
formatPos: "n s",
formatNeg: "- n s",
decimal: ",",
thousand: ".",
precision: 2,
symbol : "$"
}
}
);
iris.currency(5600.899); // "5.600,90 €"
iris.currency(-5600.899); // "- 5.600,90 €"
iris.currency(5600.899, { symbol : "" }); // "5.600,90"Since: v0.5.1
Returns an object with the browser information using user-agent.
It contains flags for each of the four most prevalent browser classes (Internet Explorer, Mozilla, Webkit, and Opera) as well as version information.
Because it uses navigator.userAgent to determine the platform, it is vulnerable to spoofing by the user or misrepresentation by the browser itself. It is always best to avoid browser-specific code entirely where possible.
Available flags are:
- chrome
- webkit
- safari
- opera
- msie
- mozilla
Example: Returns true if the current useragent is some version of Microsoft's Internet Explorer:
iris.browser().msie;Example: Show the browser info object:
console.log( iris.browser() );Since: v0.5.5
Inheritance with the prototype chain.
// Basic example
// SuperClass
function Mammal (name) {
this.name = name;
}
Mammal.prototype.sayName = function() {
console.log('[Mammal "' + this.name + '"]');
}
// SubClass
function Cat (name) {
Mammal.call(this, name); // Call SuperClass constructor
}
// Cat will inherit the Mammal prototyped functions
iris.inherits(Cat, Mammal);
var kitty = new Cat('Kitty');
kitty.sayName(); // [Mammal Kitty]Since: v0.5.0
Triggers an event.
See iris.on and iris.off for more details.
iris.notify("my-event", {param : value});
iris.notify("my-event");Since: v0.5.0
Adds an event listener.
See iris.notify and iris.off for more details.
iris.on("my-event", listener);Since: v0.5.0
Removes an event listener.
See iris.notify and iris.on for more details.
If listener is not specified, all listeners are removed.
iris.off("my-event", listener);
iris.off("my-event"); // remove all listenersSince: v0.5.0
Removes a collection of event listeners.
iris.destroyEvents("my-event", [listener1, listener2]);Since: v0.5.0
Adds an event listener associated with a component. When the component is destroyed, the listener will be deleted.
For more details, see iris.on.
self.on("my-event", listener);Since: v0.5.0
Removes an event listener.
Updated in v0.5.5, listener are not required. If listener is undefined, all component's listeners for eventId will be removed.
self.off(iris.BEFORE_NAVIGATION, onBeforeNavigation); // Unsubscribe one listener
// Since v0.5.5
self.off(iris.BEFORE_NAVIGATION); // Remove all listenersSince: v0.5.0
Removes an event listener.
See iris.notify for more details.
Since: v0.5.0
Fired before do a navigation.
iris.on(iris.BEFORE_NAVIGATION, function () {
iris.log("before navigation : " + document.location.hash)
});Since: v0.5.0
Fired after do a navigation.
iris.on(iris.AFTER_NAVIGATION, function () {
iris.log("after navigation : " + document.location.hash)
});Since: v0.5.0
Fired when a resource ajax call fails.
iris.on(iris.RESOURCE_ERROR, function (request, textStatus, errorThrown) {
iris.log("resource error", request, textStatus, errorThrown);
});Since: v0.5.2
Fired when a navigation fails.
iris.on(iris.SCREEN_NOT_FOUND, function (path) {
iris.log("Upss, path[" + path + "] not found");
// Use location.replace instead of iris.navigate or location.hash
window.location.replace("#/404"); // navigation without history saving
});Since: v0.5.0
Translates a text using the locale.
// Add the translations
iris.translations("es_ES", {GREETING : "Saludos"})
iris.translate("GREETING", "es_ES");
iris.translate("GREETING"); // Using default locale ( iris.locale() )If no locale is passed, Iris will use the default locale.
Since: v0.5.0
Adds translations in a particular language. This method can be called multiple times with the same language.
terms: Object containing the definitions in format text: definition. It admits a multi level hierarchy. See example.
file: Path to a file with the terms definitions in JSON format.
Object with two attributes (success and error) containing the functions called after retrieve the terms.
iris.translations("en_US", {
GREETING: "Hi!",
GREETINGS: {
MORNING: "Good Morning",
AFTERNOON: "Good Afternoon",
NIGHT: "Good Night"
}
});The translations can be in a JSON file. The call is asynchronous.
iris.translations("fr_FR", "./lang_FR.json", {"success" : onFRSuccess, "error" : onFRError });Since: v0.5.0
Defines or gets the locale format. You can use the available locales.
//Example of regional definition. Sets de locale to "en_US" if locale is not set:
iris.locale(
"en_US", {
dayNames: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
monthNames: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
dateFormat: "m/d/Y h:i:s",
currency: {
formatPos: "s n",
formatNeg: "(s n)",
decimal: ".",
thousand: ",",
precision: 2,
symbol: "$"
},
number : {
decimal: ".",
thousand: ",",
precision: 2
}
}
);//To set the locale
iris.locale("en_US");
//To get the current locale
var locale = iris.locale();Since: v0.5.0
Gets a regional value according to the setting locale.
If label is not passed, returns all the regional definition.
iris.regional("dayNames");Since: v0.5.1
Load the components using the paths array parameter. When all files are loaded, executes the callback function.
You can load and use iris resources before call to the iris.welcome function, eg:
iris.path = {
user_resource : "resource/user.js",
welcome : "screen/welcome.js"
};
iris.include([iris.path.user_resource], function () {
iris.resource(iris.path.user_resource).checkUserInSession().done(loginDone).fail(loginFail);
});
function loginDone () {
iris.welcome(iris.path.welcome);
}
function loginFail () {
alert("forbidden");
}Since v0.5.2, you can load external JS files (before only relative paths), e.g.:
iris.include(["http://www.example.com/js/file.js", "http://www.example.com/js/file2.js"], function(){
console.log("file.js & file2.js has been loaded.");
});Since: v0.5.0
The welcome screen is the root of all screens. You must define always the welcome screen in your initial script. This function establishes the welcome screen and navigates to it.
// All Iris applications start in the welcome screen
// Remember to define iris.path before
iris.welcome(iris.path.welcome.js);Since: v0.5.0
Navigates to a screen changing the hash URL (this function is equivalent to document.location.hash = path).
Iris looks for the target screen using the hash URL (path parameter) and wakes the target screen and its parents. The previous screens will sleep, if its canSleep() functions allows it. The screens are not destroyed, the screens change their status to sleeping. If you want destroy the hidden screens, use iris.destroyScreen(path). Use self.screens(container_id, screens) inside screen to define screen childs. When a parameter value is changed, the screen awake function is called again (the same for its child screens). The welcome screen never can sleep, it is always visible. Show the lifecycle for more details.
The iris.BEFORE_NAVIGATION event is triggered on new navigation. When the navigation finished iris.AFTER_NAVIGATION is triggered. If the screen is not found the iris.SCREEN_NOT_FOUND event is notified.
Since v0.5.6, you can use the matrix paramaters (;name=value;name2=value2...) to send them data, e.g.: #;param0=value0/screen1;param1=value1;param2=value2/screen2
In this example the welcome screen receives param0, screen1 receives param1 & param2, the screen2 doesn't receive any parameter. Use self.param(name) inside the screen to retrieve parameter values.
// Navigate without params
iris.navigate("#/screen1/child_of_screen1");
// Send parameters to the welcome screen
iris.navigate("#;param=value/screen1/child_of_screen1");
// Send parameters to other screen
iris.navigate("#/screen1;param=value;param2=value2/child_of_screen1");
// More examples
// To get the param value, use self.param('mode') inside welcome screen
iris.navigate('#;mode=offline/dashboard');
// If the param is changed, the welcome screen awake function
// is called (the same for its child screens)
iris.navigate('#;mode=online/dashboard');
// If you want to navigate to another screen, the dashboard screen
// will sleep and otherscreen will wake up
iris.navigate('#;mode=online/otherscreen');
// Another examples
iris.navigate('#/book/17354;show=details');
iris.navigate('#/user/me/friends;filter=all;show=nearest');Before v0.5.6 (Deprecated, use matrix params instead of): To send parameters to screen use this format (query params): /screen?param1=value1¶m2=value2. You can get the value of this parameters in the self.awake(params) function.
Since: v0.5.0
Defines a Screen component.
iris.screen(
function (self) {
//Called once when the Component is created
self.create = function () {
self.tmpl(iris.path.screen.example.html);
};
//Called when the Component is showed.
self.awake = function () {
...
};
//Called when the component is hidden because you navigate to another Screen
self.sleep = function () {
...
};
//Called before hiding component.
//If the method returns false, the navigation is interrupted and not hidden nor self.seelp method is called
//This method only is applied to the Screens components
self.canSleep = function () {
...
};
//Called when the component is destroyed
self.destroy = function () {
...
};
}, iris.path.screen.example.js
);Since: v0.5.0
Destroys a Screen component. Cannot delete the current screen or its parents.
iris.destroyScreen('#/user/help');Since: v0.5.0
Defines an UI Component.
iris.ui(function(self){...});Since: v0.5.0
Loads the template in memory and associates it to a path.
iris.tmpl("screen/welcome.html","<div>...</div>");See self.tmpl for more details.
Since: v0.5.0
Defines or creates a Resource Component.
//To define
iris.resource(function(self){
//Some RESTful methods
self.load = function (id) {
return self.get("service/book/" + id);
};
self.create = function (params) {
return self.post("service/book", params);
};
self.update = function (id, params) {
return self.put("service/book/" + id, params);
};
self.remove = function (id) {
return self.del("service/book/" + id);
};
}, iris.path.resource.js);//To create
iris.resource(iris.path.resource.js);Since: v0.5.7
Enables or disables the iris debug mode.
When iris debug mode is enabled, the application is listening for the combination of keys: Ctrl + Alt + Shift + D to show or hide the debug information layer. By default it is enabled in local enviroments (127.0.0.1 and localhost).
If the the combination of keys is detected, the application prints/hide a visual lines to highlight the components (screens and UIs) and prints information about its presenter and template paths, hash-URL or data-id.
// Force to disable iris debug mode
//('Ctrl + Alt + Shift + D' wont work)
iris.debug(false);Since: v0.5.0
Gets o sets a value attribute.
//To set
self.setting("attribute_name", {...});//To get
var attribute_value = self.setting("attribute_name");Since: v0.5.0
Sets multiples and complex attributes values.
self.settings({ person: { name:"test name"}, money: -67890.678, region: { country: "country test" }});
var attribute_value = self.setting("person.name");Since: v0.5.0
Loads the template of the component into the DOM.
This method must be called in the self.create method.
Example:
// UI
iris.ui(function(self) {
...
self.create = function () {
self.tmplMode(self.APPEND);
self.tmpl(iris.path.ui.login.html);
}
...
});// Screen
iris.screen(function(self) {
...
self.create = function () {
self.tmpl(iris.path.ui.login.html);
}
...
});Mode: When self.APPEND or self.PREPEND are passed as the third parameter, the template container will not be replaced with the template, otherwise the container will be replaced by the template. The default mode is self.REPLACE.
Since: v0.5.0
Gets the JQuery object whose data-id matches with the param. If no data-id is passed, the JQuery root DOM node will be returned.
<p data-id="paragraph">The name is John</p>self.get("paragraph").text("Anna");Since: v0.5.0
Write text, change the visibility, change attributes values, etc... in template elements using data-jq-* attributes.
The data-jq-* attributes invoke jQuery functions:
data-jq-html == $(element).html()
data-jq-text == $(element).text()
data-jq-val == $(element).val()
data-jq-toggle == $(element).toggle()
data-jq-attr-xxx == $(element).attr(xxx)
data-jq-prop-xxx == $(element).prop(xxx)self.inflate() function can do boring tasks for us, e.g.:
- Set element text:
In the presenter:
self.inflate( {user : { name: "John Doe" }} );In the template:
<!-- The text "Not set yet" will be replaced by "John Doe" -->
<span data-jq-text="user.name">Not set yet</span>- Change the visibility of an element:
In the presenter:
self.inflate( {user : { isAdmin: true }} );In the template:
<!-- Show or hide the admin panel, according to the user -->
<div data-jq-toggle="user.isAdmin">
...
</div>- Set multiple attributes:
In the presenter:
self.inflate( {user : { name: "John Doe", avatarUrl: "/img/john.jpg" }} );In the template:
<!-- Set the src attribute with the user's avatar URL -->
<!-- Set the title attribute with the user's name -->
<img data-jq-attr-src="user.avatarUrl" data-jq-attr-title="user.name" />- Set input value:
In the presenter:
self.inflate( {user : { name: "John Doe" }} );In the template:
<!-- Set the value attribute with the user's name -->
<input type="text" data-jq-val="user.name" />Since: v0.5.0
Create a new UI Component and replaces or adds it to the container.
Example:
In the template of the parent:
...
<div data-id="ui_container"></div>
...In the presenter of the parent:
...
self.ui("ui_container", iris.path.ui.my_ui.js, {name: "John"}, self.APPEND);
//The name parameter may be recovered in my_ui's presenter with the *self.setting* method.
...For help about the templateMode parameter see self.tmpl method.
Since v0.5.2 you can use self.ui(<data-id>) to retrieve UIs, e.g.:
- When the UI has template mode ==
self.REPLACE(default)
iris.screen(function (self) {
...
self.create = function () {
self.ui("example", iris.path.ui.example);
}
function example () {
self.ui("example").sayHi();
}
...
}- When the UI has template mode ==
self.APPEND
iris.screen(function (self) {
...
self.create = function () {
self.ui("example", iris.path.ui.example);
self.ui("example", iris.path.ui.example);
self.ui("example", iris.path.ui.example);
}
function example () {
// Destroy the first UI for example
self.ui("example")[0].destroyUI();
}
...
}Since: v0.5.0
Destroy the UI component. If ui_component is not specified, destroy the current UI (auto-destroy).
var my_ui = self.ui("ui_container", iris.path.ui.my_ui.js);
self.destroyUI(my_ui);// Auto-destroy
self.destroyUI();Since: v0.5.0
Destroy all the UI in a container.
var my_ui = self.ui("ui_container", iris.path.ui.my_ui.js);
self.destroyUIs("ui_container");Inherit methods from Component, Settable & Event classes
Since: v0.5.0
Sets the template mode. This method must be called before the tmpl.method.
The possible values are:
self.APPEND: Adds the UI to as the last element in the container.self.PREPEND: Adds the UI to as the first element in the container.self.REPLACE: Replace the container with the UI template. This is the default behavior.
Inherit methods from Component, Settable & Event classes
Since: v0.5.2
Retrieve the parameter value using the parameter name.
Since v0.5.6 you can define pretty URLs using path & matrix parameters.
E.g. (Since v0.5.6): navigate to the welcome screen with matrix params (#;paramName=paramValue):
// Welcome screen
iris.screen(function (self) {
self.awake = function () {
...
console.log( self.param("paramName") ); // prints "paramValue"
...
}
}, iris.path.screen.welcome.js);E.g. (Since v0.5.6): navigate to a example screen with path params (#/user/1234):
// Welcome Screen
iris.screen(function (self) {
self.create = function () {
...
self.screens("screens",[
[ "user/:user_id", iris.path.screen.user.js]
]);
...
}
}, iris.path.screen.welcome.js);
// User screen (iris.path.screen.user.js)
iris.screen(function (self) {
self.awake = function () {
...
var id = self.param("user_id"); // id == "1234"
...
}
}, iris.path.screen.example.js);Old style (Before v0.5.6), path & matrix params are not allowed, you can only get query params (#?paramName=paramValue):
iris.screen(function (self) {
self.awake = function () {
...
var value = self.param("paramName"); // value == "paramValue"
...
}
});Old style (Before v0.5.2), the only way to get query parameters is using the awake function parameter, e.g.: (#?paramName=paramValue)
iris.screen(function (self) {
...
var value;
self.awake = function (params) {
if ( params && param.hasOwnProperty("paramName") ) {
value = param.paramName;
}
}
function example () {
console.log(value); // value == "paramValue"
}
...
});Since: v0.5.0
Registers Screens and allows to navigate to them. This method can be called once for each component.
self.screens("screens", [
["home", iris.path.home.js],
["help", iris.path.help.js]
]);
//The first parameter is the data-id attribute of the containerSince v0.5.6, "pretty URLs" are allowed, you can register screens with path params and the / character is also allowed, e.g.:
// Welcome screen
iris.screen(function (self) {
self.create = function () {
...
self.screens("screens", [
["user/:user_id/detail", iris.path.screen.user_detail.js],
["user/:user_id/friends/list", iris.path.screen.friends.js],
["user/:user_id/friend/:friend_id/detail", iris.path.screen.friend_detail.js]
]);
...
}
}, iris.path.screen.welcome.js);
// Friend detail screen
iris.screen(function (self) {
self.awake = function () {
...
// If the current hash is: #/user/1234/friend/4321/detail
var userId = self.param("user_id"); // "1234"
var friendId = self.param("friend_id"); // "4321"
...
}
}, iris.path.screen.friend_detail.js);Inherit methods from Settable class
Since: v0.5.0
Perform an asynchronous HTTP (Ajax) request of type GET.
Returns a jQuery jqXHR object.
self.get(path).done(function() {
alert("done");
}).fail(function() {
alert("fail");
});Since: v0.5.0
Perform an asynchronous HTTP (Ajax) request of type POST.
Returns a jQuery jqXHR object.
self.post(path).done(function() {
alert("done");
}).fail(function() {
alert("fail");
});Since: v0.5.0
Perform an asynchronous HTTP (Ajax) request of type PUT.
Returns a jQuery jqXHR object.
self.put(path).done(function() {
alert("done");
}).fail(function() {
alert("fail");
});Since: v0.5.0
Perform an asynchronous HTTP (Ajax) request of type DEL.
Returns a jQuery jqXHR object.
self.del(path).done(function() {
alert("done");
}).fail(function() {
alert("fail");
});