Index

tartJS

tartJS is a performance-focused JavaScript framework based on well-tested Google Closure Tools suite. It provides rapid and responsive mobile app infrastructure.

Check out the documentation and join us on for anything about tartJS.

Track issues on

Closure Compiler optimizes, checks and cleans up your annotated JavaScript code with best minification rates while helping you to catch errors.

Getting Started

From scratch

Add tartJS to your project as a submodule:

    git submodule add git@github.com:tart/tartJS.git js/lib/tartJS

Boilerplates/Examples

For TodoMVC implementation and generic boilerplate:

http://github.com/tart/tartjs-todomvc
For working mobile project:

https://github.com/tart/tartjs-mobile-demo
Generic boilerplate:

https://github.com/tart/BoilerPlate

Documentation

(More coming soon)

Annotation

With help of Closure Compiler, class based inheritance and type safety is widely used in tartJS. See Annotating JavaScript for the Closure Compiler how JSDoc annotation works.

Directory structure

tart : Contains core Tart libraries
tools : Contains tools like Google Closure Compiler, Google Closure Linter etc (submodule to tart/GUI-Tools)
third_party : Contains third party libraries like Google Closure Library, Jasmine, jQuery etc.

Examples

Outstanding web audio processor for guitar players:

Pedalboard.js
Example TodoMVC application (useful as a web application boilerplate):

tartjs-todomvc
Example TV show mobile app (useful as a mobile boilerplate):

tartjs-mobile-demo

Contributing

Want to contribute? Great! Fork it, create a branch, make your changes, push and open pull request to contribute. Your pull request may not be merged immediately until necessary changes were made to match coding-style, pass tests. We do follow Google JavaScript Style Guide.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

base/Model.js

tart.base.Model base model.

base/plugin/BasePlugin.js

tart.base.plugin.BasePlugin to get common properties for a plugin in one class.

base/plugin/Filter.js

tart.base.plugin.Filter model filter plugin.

base/plugin/Pager.js

tart.base.plugin.Pager model pager plugin to handle pagination.

base/plugin/Sorter.js

tart.base.plugin.Sorter model sorter plugin.

Builder.js

Generic builder class to build and modify DOM elements.

Carousel/Carousel.js

tart.Carousel is an event driven Carousel/Image Slider class which handles next and previous events and gets visible items on viewport.

Example usage:

var items = [
    {name : 'one'},
    {name : 'two'},
    {name : 'three'},
    {name : 'four'},
    {name : 'five'},
    {name : 'six'},
    {name : 'seven'}
]; //seven items

var carousel = new tart.Carousel(items);

carousel.setItemPerViewport(2); //only 2 items is visibile

goog.events.listen(carousel, tart.Carousel.EventTypes.NEXT, function (e) {
    console.info('items moved next');
    console.log (e.itemsToBeRemoved);
    console.log (e.itemsToBeInserted);
    console.info(carousel.getVisibleItems());
});

goog.events.listen(carousel, tart.Carousel.EventTypes.PREV, function (e) {
    console.info('items moved prev');
    console.log (e.itemsToBeRemoved);
    console.log (e.itemsToBeInserted);
    console.info(carousel.getVisibleItems());
});

//items : 'one', 'two'
carousel.next(1);
//items : 'two', 'three'
carousel.next(4);
//items : 'six', 'seven'
carousel.next(1);
//items : 'six', 'seven' which is end of items, for circular navigation use tart.CircularCarousel instead
carousel.prev(1);
//items : 'five', 'six'
carousel.prev(99999);
//items : 'one', 'two'

CircularCarousel/CircularCarousel.js

tart.CircularCarousel is an event driven Carousel/Image Slider class which handles next and previous events and gets visible items on viewport.

Example usage:

var items = [
    {name : 'one'},
    {name : 'two'},
    {name : 'three'},
    {name : 'four'},
    {name : 'five'},
    {name : 'six'},
    {name : 'seven'}
]; //seven items

var carousel = new tart.CircularCarousel(items);

carousel.setItemPerViewport(2); //only 2 items is visibile

goog.events.listen(carousel, tart.Carousel.EventTypes.NEXT, function (e) {
    console.info('items moved next');
    console.log (e.itemsToBeRemoved);
    console.log (e.itemsToBeInserted);
    console.info(carousel.getVisibleItems());
});

goog.events.listen(carousel, tart.Carousel.EventTypes.PREV, function (e) {
    console.info('items moved prev');
    console.log (e.itemsToBeRemoved);
    console.log (e.itemsToBeInserted);
    console.info(carousel.getVisibleItems());
});

carousel.prev(3);
carousel.next(1);

Collection.js

tart.Collection is a useful data construct that also features an "active item". It is a key-value pair collection with easy to use methods. It is also event-driven, so observers are notified when the index of the active item changes.

Example usage:

var items = { foo : 'bar' };
var list = new tart.Collection(items);

var items = ['A','B', 'C', 'D'];
var list = new tart.Collection(items);

var items = { foo : 'bar', baz:'zoo' };
var list = new tart.Collection(items, 1); // Set activeItemIndex to 1

components/Carousel/Controller.js

tart.components.Carousel.Controller is a base class for all carousel Controller's.

components/Carousel/Model.js

tart.components.Carousel.Model is a base class for all carousel Model's.

components/Carousel/Template.js

tart.components.Carousel.Template is a base class for all carousel Template's.

components/Carousel/View.js

tart.components.Carousel.View is a base class for all carousel View's.

components/Carousel/Widget.js

tart.components.Carousel.Widget is a base for all carousel widgets.

components/Controller.js

tart.components.Controller is a base class for all components Controller's.

Example usage:

 var ViewClass = function () {
     goog.base(this);
 };
 goog.inherits(ViewClass, tart.components.View);

 ViewClass.prototype.render = function () {
     return "<h1>Foo</h1>";
 };
 var view = new ViewClass();

 var ModelClass = function () {
     goog.base(this);
 };
 goog.inherits(ModelClass, tart.base.Model);


 var model = new ModelClass();

 var ControllerClass = function () {
     goog.base(this);
 };
 goog.inherits(ControllerClass, tart.components.Controller);

 var controller = new ControllerClass(model, view);
 var dom = controller.buildDOM();

components/RemoteModel.js

tart.components.RemoteModel RemoteModel which gets data from Xhr.

components/View.js

tart.components.View is a base class for all components View's.

Example usage:

SubViewClass = function() {
    goog.base(this);

    this.domMappings = {
        HEADER: 'h1'
    };
};
goog.inherits(SubViewClass, tart.components.View);

SubViewClass.prototype.templates_header = function(text) {
    text = text || '';
    return '<h1>' + text + '</h1>';
};

SubViewClass.prototype.render = function() {
    return this.templates_header();
};

var subView = new SubViewClass();

var dummyDiv = tart.dom.createElement(subView.render());

subView.setDOM(dummyDiv);
subView.get(subView.domMappings.HEADER);

Known issues:

Templates will be injected withing Templates object

components/Widget.js

tart.components.Widget is a base class for all components Widget's.

dataProxy/Abstract.js

tart.dataProxy.Abstract base abstract class for local and xhr data proxies.

dataProxy/CircularLocal.js

tart.dataProxy.CircularLocal XHR data proxy.

dataProxy/Local.js

tart.dataProxy.Local XHR data proxy.

dataProxy/Xhr.js

tart.dataProxy.Xhr XHR data proxy.

date/date.js

This file provides utility functions and classes for dates.

date/DateRange.js

This file provides utility functions and classes for dateranges.

dom/dom.js

This file provides commonly used DOM functions.

DropdownList/DropdownBuilder.js

Builder class for dropdown lists.

DropdownList/DropdownList.js

Dropdown list class is an example of an HTML select box.

Example usage:

var items        = {key1:'val1',key2:'val2',key3:'val3'};
var builder      = new tart.DropdownBuilder('elementId');
var selectedItem = 1;
var list = new tart.DropdownList(items, builder, selectedItem);
list.getAll(); // Outputs [{key1:'val1'},{key2:'val2'},{key3:'val3'}]
list.getDOM(); // Returns a select (dropdown) menu in jquery format jQuery(select#elementId)
list.setActiveItemIndex(2); // Sets key3:val3 option element selected property to TRUE;
list.getActiveItemIndex(); // Returns an Object { key3="val3" }

Err.js

tartJS error library and utility functions.

events.js

Event Manager.

Provides browser event handling routines.

This module extends goog.events for additional support.

events/GestureHandler.js

GestureHandler adds the ability to capture gesture events on touch enabled devices. It listens to 'touchstart', 'touchmove' and 'touchend' events and generates 'tap' or 'swipe' events with inherent heuristics.

Currently, the tap algorithm begins with a touchstart, checks for touchend. Any touchmove greater than 3px cancels the tap event, and if a touchend is captured without a touchmove after a touchstart; it's registered as a tap, and the GestureHandler dispatches a tap event on the touchend target.

Swipe up, left, right and down gestures are also supported.

Example usage:

goog.events.listen(document.body, tart.events.EventType.TAP, function() {
    console.log('tapped!');
});

events/HoverHandler.js

Google Closure Library doesn't like mouseenter and mouseleave events, and provides no easy way to listen to it. Therefore, HoverHandler provides a consistent behavior of mouseenter and leave actions.

Example usage:

var handler = new tart.events.HoverHandler(elementToListen); // default is body.
goog.events.listen(handler, tart.events.EventType.MOUSEENTER, function() {
    console.log("i'm on hover");
});

externs/jquery-1.4.4.externs.js

Externs for jQuery 1.4.4. Note that some functions use different return types depending on the number of parameters passed in. In these cases, you may need to annotate the type of the result in your code, so the JSCompiler understands which type you're expecting. For example:

var elt = /** @type {Element} * / (foo.get(0));

See:

http://api.jquery.com/

FormValidator/FormValidator.js

tart.FormValidator is a form validation library which uses tart.Validation instance as validator.

Example usage:

var form = $("form");
var validationForSubmit = function (errors) {
    //do some stuff with 'errors' object
};
var validationForBlur = function (errors) {
    //do some stuff with 'errors' object
};
tart.FormValidator(form).validateOnSubmit(validationForSubmit);
tart.FormValidator(form).validateOnBlur(validateOnBlur);

More examples can be seen from spec/FormValidationSpec.js file

List.js

tart.List to handle List typed data structures extended from tart.Collection.

mvc/Application.js

This class implements the base application. The users of tart.mvc should extend this class in order to create their own MVC application.

mvc/IApplication.js

This file combines the requirements of tart.mvc in a single requirement called tart.mvc so that projects that use the tart.mvc need only require tart.mvc. It also implements the base application. The users of tart.mvc should implement this tart.mvc.IApplication class.

mvc/Layout.js

The instances of this class will hold the root HTML markups for the MVC application.

mvc/mvc.js

This file provides a single namespace to include tart.mvc in your application. It also sets the basic needs such as type definitions.

mvc/uri/Redirection.js

This is a special return value that is used to identify a redirection. If a redirection is in place the tart.mvc.Router returns an instance of this class, so that the redirector won't resume after the redirection takes place.

mvc/uri/Router.js

URI Router class that takes a given URI and resolves the necessary controller / action.

mvc/View.js

The View class.

Pagination/Pagination.js

tart.Pagination is an event driven Pagination object.

Example usage:

var paginator = new tart.Pagination();

paginator.setTotalPage(5);
paginator.setCurrentPage(2);

goog.events.listen(paginator, tart.Pagination.EventTypes.PAGE_CHANGED, function (e) {
    console.log("page changed");
    console.log("old page : " + e.oldValue);
    console.log("new page : " + e.newValue);
});

paginator.setCurrentPage(4); // oldPage : 2, newPage : 4
paginator.setCurrentPage(7); // oldPage : 4, newpage : 5 (totalPage)
paginator.prev(); // oldPage : 5, newPage: 4
paginator.setCurrentPage(0); // oldPage : 4, newpage : 1 (at least 1)
paginator.next(); // oldPage : 1, newPage : 2

Registry.js

tart.Registry is a convenience class that wraps goog.structs.Map and is intended to use as a global registry across a web application.

StateMachine/State.js

State class is used in conjunction with tart.StateMachine. It is a value object that holds two properties; a function that is executed when the state machine is in this state, and a transitions object for events that may happen in this state.

StateMachine/StateMachine.js

This class is an implementation of a Moore state machine that is common in digital electronics, etc.

The state machine is by it's nature an event-driven system. Events that come at the right state will put the state machine in another expected state.

To keep the implementation simple, many details are omitted. The state machine doesn't keep a record of its states, new states cannot be added after a state machine is started, etc. These rules do not prevent the functioning of the machine though.

This class is a base class and not intended to be used on its own. To use a state machine, the developer has to subclass this base class and override the createStates_ method. This method should hold the initialization of states in the state machine and should return the first state the machine should begin with.

This implementation features lazy loading in the sense that the createStates_ method is not called until the first call to startMachine method.

Example usage:

Foo.MooreMachine = function(){
    goog.base(this);
}
goog.inherits(Foo.MooreMachine, tart.StateMachine);

// Having an enumerated type for events helps readability
Foo.MooreMachine.Events = {
    CLICK: '0',
    DOUBLECLICK: '1'
}

Foo.MooreMachine.prototype.createStates_ = function(){
    var STATE1 = new tart.State(function(){
        console.log("state 1");
    });

    var STATE2 = new tart.State(function(){
        console.log("state 2");
    });

    STATE1.transitions[Foo.MooreMachine.Events.CLICK] = STATE2;
    STATE2.transitions[Foo.MooreMachine.Events.DOUBLECLICK] = STATE1;

    this.addState_(STATE1);
    this.addState_(STATE2);

    return STATE1;
}

var myMachine = new Foo.MooreMachine();
myMachine.startMachine();

storage/Storage.js

This file provides localStorage extensions that are essential to Tart. Basically, the localStorage only allows you to store strings. tart.storage.Storage can store any type of object via serialization.

Example usage:

var storage = new tart.storage.Storage();
storage.set('foo', {bar: 'baz'});
storage.get('foo');
// you can still iterate through localStorage as before with for .. in;
for (var key in localStorage) {
    var object = storage.get(key);
    //do something with the object
}

string/string.js

Provides utility functions for string operations.

Tabs/TabPanel.js

Creates an instance with a tab and panel for using with an existing tabpanel.

Example Usage:

var panel1 = new tart.TabPanel({
    title: 'Tab 1',
    html: 'This is a basic text'
});

Tabs/Tabs.js

Tabs is a fully working and customizable tab panel creator class.

Example Usage:

var tabPanel = new tart.Tabs({
    activeTab: 1
});

var panel1 = new tart.TabPanel({
    title: 'Tab 1',
    html: 'This is a basic text'
});
var panel2 = new tart.TabPanel({
    title: 'Tab 2',
    html: 'Lorem ipsum dolor sit amet'
});
var panel3 = new tart.TabPanel({
    title: 'Tab 3',
    html: 'Lorem ipsum dolor sit amet is a dummy text'
});

tabPanel.addTabPanel(panel1);
tabPanel.addTabPanel(panel2);
tabPanel.addTabPanel(panel3);

var dom = tabPanel.buildDOM();
$('body').append(dom);

tart.js

tartJS base.

ui/Component.js

This class offers a component architecture for projects that include highly interactive user interfaces. Unlike tart.Component which features a classical MVC role seperation - with 5 or 6 classes, which is also a heavy implementation - tart.ui.Component uses 3 classes and joins the roles of the Template, View and Controller into one Component class.

The other roles help responsibility seperation that is necessary enough for a UI component.

The Component class is useful for event management; it listens to DOM events, map these to related functions in the model and vice versa.

The model is responsible for all the states of the component and the business logic. The component shouldn't keep state and should be as dummy as possible; any state change on the model is dispatched via an event to the Component class to update itself. This decoupled architecture makes it possible that business critical unit tests of the component can run fully functionally without a DOM. The model may also be responsible for dealing with the data in any way (remote requests, other events to other modules in the system, etc).

Finally, the third, optional class is a value class, which is like a POJO. It keeps all the related data in an instance. This allows one to exchange data in the application with very lightweight data objects - make it through a constructor class and you get to keep object oriented design.

So, the data the component displays or deals with resides in a value class. The model keeps its state and business logic, and the Component class makes the representation.

ui/ComponentManager.js

Registry for tart.ui.DlgComponent. Manages DOM event interactions for these components.

ui/ComponentModel.js

This class offers a base class for model implementations. It makes no enforcements as how to shape your model, it's just a basic container. Subclasses of this class should accept either a JS object or a value class instance.

See tart.ui.Component for details on the model's responsibilities.

ui/DlgComponent.js

Delegated Component class offers a component architecture that is an improved version of tart.ui.Component. Like tart.ui.Component, it carries Controller, View and Template in classical MVC role separation.

Now, this class is not listening to any of dom events itself. Additionally, it uses ComponentManager which keeps components and controls user interactions of these components. For this reason templates of all components have to include a unique id attribute.

ui/input/DateComponent.js

This component displays the date entered in a predefined date format and returns that date's value in milliseconds format when asked. If the entered value is not suitable, getDateTime function returns 'NaN' value.

ui/input/RevealingPassword.js

This component handles the password entrance and display mode toggling of password string. It takes an optional value defining the minimum length requirement of the password string. If the minimum length requirement is not being meet, it returns an empty string. The display toggler works like a switch for displaying mode. When the value of related variable 'displayPassword' is equal to false, the input area conceals the string entered and displays '*' chars instead. Otherwise, the password string is being displayed as it is.

ui/tooltip/TooltipComponent.js

ui/tooltip/TooltipComponentModel.js

Validation/Validation.js

tart.Validation is a validation library which checks for variable's format (such as email, number) or attribute (such as char length).

Example usage:

var validator = tart.Validation;
var isValidEmail = validator.is.email("foo@bar.com"); //returns boolean true
var isNumeric = validator.is.numeric("123foo"); // returns boolean false
var hasMaxLength10 = validator.has.maxLength("foobar", 10); //returns boolean true

More examples can be seen from spec/ValidationSpec.js file

XhrManager.js

tart.XhrManager static class to handle XHR requests.

TartJS

Index

tartJS

Getting Started

From scratch

Boilerplates/Examples

Documentation

Annotation

Directory structure

Examples

Contributing

License