JPolite Documentation (Draft)

JPolite Programming Guide

About – the Motivation Behind JPolite

Motivation

JPolite V1 was inspired by Netvibes, the goal is to help web developers handle content integration tasks in a rapid and convenient manner.

JPolite V2 is a major upgrade with focus on:

  • Better User Experience – Grid system based layout with theme and persistence support
  • Better Developer Support – Well organized code structure and behavior abstraction, separation of concerns, customization at ease
  • Unbounded Extensibility – Easy integration of 3rd party plug-ins

Design Philosophy

  • Less is more – A smaller core with more powerful customizability
  • Separation of Concern – Content in but HTML + Content-independent CSS Framework + Unobtrusive JavaScript
  • Convention over configuration – Little extra efforts needed to tailor by conventions

Buzz on Major Features

  • Smaller Core – 3K minimized
  • jQuery UI Integration – controls + themes
  • Event & Message Processing – for resource management and beyond
  • Various module types & templates
  • Layout Persistence
  • XDO – RESTful resource representation
  • Theme Support

Some Key New Features

  • SEO Support – Support static modules pre-loaded in index.html, visible to search engines.
  • Live Theme Switcher – Support fast switch between different themes.
  • Layout Persistence – Module layout can be stored and retrieved to your desired store, e.g., cookie, remote server or HTML5 local data store.
  • Popup & Dropdown Menu – A module popup menu is provided for users to add modules to current tab. Dropdown menu provides additional navigation support beyond horizontal tabs.

DOM Architecture

 JPolite DOM Architecture

Defining Tabs (Main Menu)

The main navigation menu is actually an UL list, with each LI member represents one “Tab”, uniquely identified through the LI’s ID. In case you need more tabs, just add one more LI member with a new ID in index.html under UL#main_nav.

To include sub-menu items under a tab, include a DL inside the parent LI, with each DD represents one menu item, a.k.a. tab. For example:

<li> … <dl><dd>Same content, another layout</dd></dl></li>

Here t2 and t21 represent two different tabs, although DD#t21 is enclosed inside LI#t2.

To make things simpler, deeper levels of sub-menu is NOT supported in current version.

Organizing Content

Content are represented as modules, which can be dynamically or statically loaded. A module is uniquely defined in modules.js in the _modules variable:

var _modules = {
       m101:{url:"modules/m101.html", title:"Motivation"},
       m102:{url:"modules/m102.html", t:"Philisophy"},
       …
};

Wherein:

  1. m101, m102 – unique module ID
  2. url – url of this module relative to index.html
  3. title – title of the module when loaded

Each module is physically attached to one container node (DIV.cc) and logically associated with one Tab. Switching tab will render all modules logically associated with current tab visible and other modules hidden. To associate modules to tabs, refer to _moduleLayout variable in modules.js:

var _moduleLayout = {
       t1:["m101:c1:red", "m102:c2:yellow", "m103:c3:green"],
       t2:["m200:c1", "m201:c2", "m202:c3", "m203:c4"],
       t3:["m301:c1", "m302:c2::B", "m303:c3::C"],
       …
};

Wherein:

  • t1, t2 – Tab ID
  • m101, m102 – module ID, as defined in _modules variable
  • c1, c2 – column ID, as defined in index.html
  • red, green – optional module color class, which can be defined in style.css
  • C – optional module display template name. Templates are included in index.html as DIV. module_template and uniquely identified by ID. The one template without an ID is treated as the default.

Simply put, t1:[“m101:c1:red”, “m102:c2:yellow”, “m103:c3:green”] means module m101, m102 and m103 will appear inside column c1, c2 and c3 respectively when tab t1 is selected, and dressed in red, yellow and green respectively in default template.

Defining Layout of Modules

Grid System

V2 is built on BlueTrip CSS Framework and a suggested way to handle customization is to keep 2 separate CSS files:

  • Screen.css – the main definitions of BlueTrip, better keep it as is.
  • Style.css – your own definitions, which may override part of BlueTrip. For example: the full width of content container is 950px, as defined in screen.css as class “container”. To support wide screens, you may customize the definition of container class in style.css as 950px + n*40px (to align with the grid column width custom).

Managing Content Containers

There are 4 content containers, a.k.a., columns defined as DIV.cc, with IDs “c1”, “c2”, “c3” and “c4” (you may add more if needed). Column width is defined through Grid system class, e.g., “span-8” which stands for 310px, and all modules inside a column shall appear in full width of their parent column.

What’s more, the column width is customizable for each tab! Check out the _columnLayout variable in modules.js:

var _columnLayout = {
       _default: {
              bg: 'normal',
              c1: 'span-8',
              c2: 'span-8',
              c3: 'span-8 last',
              c4: 'span-24'
       },
       t2:{  bg:' darker',
              c1: 'span-24 last',
              c3: 'span-8',
              c4: 'span-8 last'
       },
       …
};

Wherein:

  • _default – default class definitions of columns, which is used when no definition is given for a tab. In this case, c1, c2 and c3 will bear same width in a row, and c4 will occupy full width of the content container
  • t2 – column class definitions for a given tab
  • bg – class definition for the entire page, which can be switched when changing tabs. It is included here just to make definition simpler.
  • c1, c2, c3 – class definitions for columns

As shown in the example, when tab2 is selected, the background will become “darker”, and c1 will appear 950px, while c2, c3 and c4 will appear in a row with the same width 310px.

Module Template Definition

A default template is included in index.html as DIV.module_template without an ID, the structure is shown below:

 

When a new module is inserted into a container according to _moduleLayout definition, e.g., module m101, its title as defined in _modules.m101.t will be inserted into DIV.moduleTitle, and the actual content from external file indicated by _modules.m101.url will be loaded into DIV.moduleContent through AJAX.

Custom module templates can be included as DIV.module_template with unique IDs. All components in a module template are optional except DIV.moduleContent, and each component may have further class or inline style properties.

Layout Persistence

By default, JPolite makes use of local cookie to save and retrieve layout. However you can change the persistence method to fit your need in the jQuery ready function in jpolite.ext.js:

$(function(){
       …
       s.layoutPersistence = [
              function() {    //callback function to load saved layout
                     return window["eval"]("(" + $.cookie('jpolite2layout') + ")")
              },
              function(s) {   //callback function to save current layout
                     return $.cookie('jpolite2layout', s);
              }
       ];
       …
};

 You can replace the functions to save layout data to remote server or HTML5 local storage, and retrieve accordingly. Layout save is triggered whenever end user makes a drag-n-drop action.

UI Controls

Control Initialization Process

Controls are specific HTML segments with certain behavior, e.g., tabs and accordion … A control is defined in a module file as plain HTML segment identified by certain class names, e.g., “tabs” or “accordion”. For example the definition of an accordion is like below:

<dl>
       <dt>Title 1</dt>
       <dd>Content 1</dd>
       <dt>Title 2</dt>
       <dd>Content 2</dd>
       <dt>Title 3</dt>
       <dd>Content 3</dd>
</dl>

To initialize a control, a jQuery plug-in method will be called upon.

When a module is inserted into a container, the associated external content file will be loaded into the DIV.moduleContent node. By now the control is still plain HTML carrying only the look of an accordion but not yet the behavior. JPolite will then go through a control registry to check for possible existence of each registered control and call the initialization method accordingly.

 The control registry can be expanded through method $.addControls. Example usage is included in jpolite.ext.js under function myControls:

$.addControls({
       ".tabs":                  [$.fn.Tabs],
       ".accordion":         [$.fn.Accordion],
       ".jqmWindow":      [$.fn.jqm, {toTop:true}],
       …
});

Wherein:

  • “.jqmWindow” – Selector (usually class names) to find desired control existence in a new module’s content section
  • [$.fn.jqm, {toTop:true}] – control initialization method, as well as necessary parameters, enclosed in an array 

You can include a new control through the following steps:

  • Include associated CSS files of the control in index.html
  • Include associated JavaScript files of the control in index.html
  • Call $.addControls({“.myControl”, [$.fn.InitMyControl, {InitParameters: “if any”}]}) in jpolite.ext.js or elsewhere.

Tested Controls

  • JPolite native: Tabs, Accordion, Local Link, Tab Link
  • jQuery UI 1.7.2 + theme
  • 3rd Party Controls: Gritter, jqModal

Theoretically all controls defined as jQuery plug-in can work in JPolite. However certain plug-ins only support one-time initialization, and subsequent calls on new modules may not work.

Customization

Tabs Behavior

As you’ve already experienced when opening this page, you can choose among 3 options to customize behavior of the tabs, namely, ‘Kwicks, ‘LavaLamp‘ and ‘Traditional’. While ‘Traditional’ is just a simple native implementation with tricks from Dragon Interactive, the other two are jQuery user interface plugins integrated directly without modification.

So for your system, you can pick one tab style given above or select another plugin from the jQuery plugin diretory.

Page Background

Page background under a certain tab can be customized in _columnLayout variable in modules.js, e.g.,

       …

       _default: { bg:’normal’,

       …

       },

       t2:{ bg:’darker’,

       …

       },

       …

The value ‘normal’ and ‘darker’ refers to two class names defined in styles.css. That is, you customize page background with CSS classes, which can include both colors and images.

Known Issues:

Currently JPolite2 uses jQuery UI’s switchClass function to make a smooth transition between different background settings. But this feature does not work under WebKit based browsers, i.e., Google Chrome & Apple Safari. Even worse, the background stay unchanged between tabs. So far there seems no sound solution yet that you need to make a decision here:

  1. Forget about transition, use plain attr(“class”, “new_class “) for maximum compatibility.
  2. Forget about WebKit, make switchClass a special treat for non-WebKit browsers.

Themes

Three sample themes named “modern”, “silver” and “classic” are included in index.html:

<head>
…
<link rel="alternate stylesheet" title="classic" href="css/style0.css"/>
<link rel="alternate stylesheet" title="silver" href="css/style.css"/>
<link rel="stylesheet" title="modern" href="css/style1.css"/>
…
</head>

You can use the following code to live switch theme:

function switchTheme(t) {     //t = ‘modern’, ‘silver’ or ‘classic’
       $('link[title]','head').each(function(){
              this.disabled = true;
              this.disabled = (this.title != t);
       });
       return false;
};

 For now I have not yet defined a JPolite CSS Framework with clear cut between structural and themeable (e.g., color, font) styles. Nonetheless, I’m trying on a LESS file which shall make it easy to build custom CSS themes, with reference to the jQuery UI CSS Framework.

Navigation Tab Behavior

JPoltie V2 demo allows you to choose among 3 options to customize behavior of the tabs, namely, ‘Kwicks, ‘LavaLamp‘ and ‘Traditional’. While ‘Traditional’ is just a simple native implementation with tricks from Dragon Interactive, the other two are jQuery user interface plug-ins integrated directly without modification. This means you can use your favorite navigation tab style to meet your design goal. Check out the jQuery ready function in jpolite.ext.js for details.

Misc. Initialization Parameters

Here’s a list of init arguments you can set when calling $.jpolite.init:

cts Navigation Tab container id, default = “#main_nav”. So you can use a different ID in your HTML. You can even try to use two or more separate tabs.
its Navigation Tab item selector, e.g., “dd” for a DL, default = “li, dd”
t1 Content transition Out callback when traversing between tabs, default = $.fn.fadeOut
t2 Content transition In callback, default = $.fn.fadeIn
navInit Navigation Tab Initialization callback, default = TraditionalTabs (find out more in jpolite.ext.js).
navInitArguments Navigation Tab Initialization parameters, default = {}
moduleSortable Whether to allow module drag-n-drop, default = true
layoutPersistence Methods to load/save layout of modules, default = [none, none]

XDO and Thin Server Architecture

Drop me a note in case you need further assistance on building web apps differently.

Refer to the follow for more:

Developer Resources

Download

Get latest version from Google Code > jpolite2

Links

  • Netvibes – the personalized web portal for inspiration
  • BlueTrip CSS Framework – exemplifies the best way to use CSS frameworks
  • Gritter – awesome Growl look-a-like plugin for jQuery
  • REST – the architectural style that makes the web
  • Chain JS – Better JavaScript template engine
Advertisements

31 comments on “JPolite Documentation (Draft)

  1. Pingback: JPolite V2 Document Draft « Trilancer Official Weblog

  2. Amazing, simple amazing. Unfortunately I’m not a programmer, so I won’t give you any suggesting.. I was just wondering how to import RSS feed on it…

  3. I am new to web design and am trying to figure out where JPolite fits in. Is it similar to Sproutcore/Qooxdoo, or more like jquery/mootools, or something else?

    Very nice design!

    • JPolite simply try to make it really simple to build a Netvibes/iGoogle like front-end for web applications.
      It is built on top of jQuery, and you can use jQuery UI as well as 100s of jQuery plugins.
      Its core job is multi-tab module layout management, and I believe you can Sproutcore or Qooxdoo along with it.

    • For V3, a number of things is on my mind:

      1.Full HTML5 (tags, WebSocket, WebWorker …) + CSS3 (transform, transition …) integration
      2.iPad / iPhone version
      3.More advanced OO and modular design

      For technical support, feel free to drop me mails for now.

  4. Love this JPolite suite! Currently working to have a website utilize it with one page of portlets and the rest of the pages the company’s current content. I’m not much a jquery guy, yet… but looking to how to make the tabs go to actual physical pages versus different module loaded via the JS File. I only need one tab with portal content.

  5. I love this plug-in, hope to use it in a project f mine.

    one thing I’d like to see in v3 would be ability to lock a column.

    for example, Facebook has the center column reserved for news/comments, I’d like to do something similar for my project, but it looks like that’s not possible as of yet for this plug-in.

    keep up the great work.

  6. Hi, this plugin seems what I was looking for.

    I had two questions:

    1. Is history supported (ie. browser back / direct link to container) ?
    2. How can I link content from a module and display it in the same module ?

    Thanks for your great work

    • Marione:
      1. History is not supported yet, at the time of development, I tried several jquery history plugins but doesn’t seem to work right, so it’s left out of the build
      2. If you’d a link to replace content of the current module, add a class=”local” attribute and it’ll work

  7. Excellent work… I have been working with V2 recently as part of an internal project, with an ASP.Net MVC / SQL Server backend.

    I admire your choice of using a Grid based approach rather than the JQuery UI Sortable, as it has given me far greater control over site look and feel.

  8. Correction – I of course realise you do use JQuery UI Sortable to detect module drag and drop, I meant that the Grid layout is much more flexible than the typical UL / LI approach that Sortable it is typically combined with.

    • I didn’t work out a complete theming system, for I don’t think it necessary for many apps.
      So you may need to custom-build a theme CSS file, based on the 3 sample themes.

  9. do you have better material on the XDO and TSA – i ported everything to jsp however, it seems that i am loosing the context when i submit a form via ajax. i cant do much with the results.

    • @G,
      XDO is a very lightweight data representation layer that I used in my projects, that it requires lots customization code to support complex apps. If you intent to write data heavy apps, I suggest you study Backbone.js, which provides more complete framework and documentation.

  10. thanks for the suggestion, I will look at backbone. My current project is also light, do you know where i can find a doc on XDO or is it something that you created? It seems useful and is already in the framework so i was looking for something to get more familiar with it.

    • @G, XDO was created in my earlier projects to build MVC web apps, never had the chance to perfect it and document it. While Backbone seems more complete but somehow heavy for simple requirements to me.

  11. i am having an issue.. on where i should write my custome jquery code like
    $(“#A”).click(function(){alert(“S”);});

    also how do i submit a html form with a post request

    and to make a PHP GET Request.

    • If your custom code is just for one element, you can put it anywhere in [jpolite.ext.js] as long as you make sure the node is available when you call the code.

      If it’s for dynamic nodes loaded in modules, better write a jQuery plugin first, e.g., $.fn.MyPlugin = function(){…} Then find function myControls() in [jpolite.ext.js], and add your code in the list, e.g. “.myClass”:[$.fn.MyPlugin], and it will be automatically applied on newly loaded modules. You can apply this method on forms, e.g., “.myForm”:[$.fn.myFormSubmit]

      As for mere GET, check out the sample under XDO tab to see how it works.

  12. hi thank you very much trilancer. yes i couldn’t find a way so i actually used the second method of creating the jquery plugin and then calling it up.

    Re the GET i am still not clear on how its loaded. in to the table. could you explain that to me.

    • You need to define a name for the RESOURCE you load from server side, and define corresponding methods to handle when those resources arrive.

  13. Hi,
    First of all, sorry for my very bad english.
    I’m a newbie with JQuery and Jpolite. I would like to know if I can manage user session ? and store this information somewhere in database for example?
    Can I connect Jpolite to mysql database for example ?
    how can I create new modules and store them in database for example. How to know the “state” of module ex : load or not load yet on my page ?

    thanks
    Best regards,

    • Bilou,

      JPolite is a pure JavaScript framework, that can be connected to any backend server or database. So it’s up to you how to handle sessions.
      A module takes a title string and link to a link to any server side script or static HTML.

  14. Greetings, thank you for writing such a wonderful framework. Any time frame about the version 3? I’m thinking of using it for my project but I’m not sure if I should use version 2 or wait for version 3.

    If I’m using version 2, would it be hard to convert it to version 3?

    Thanks,

    Michael

    • Michael,

      Actually I’m still struggling what features to put into V3, e.g., Pinterest/Flipboard like layout, touch screen support, horizontal swipe to scroll between tabs … so I’d like to hear your requirements if any.

      For now, you’d better use V2 for your current project.

      BTW: I’m also considering using Nodejs as the backend engine, so the layout can be generated on server side (for SEO, e.g.) or client side with the same codebase.

      • Thanks for the reply trilancer. I’ve looked deeper into the JPolite and it looks like what I need. There is only one thing I’m not sure of. I’ll appreciate if you can answer it.

        My project needs both fixed and fluid/percentage layout. But seems Bluetrip natively supports fixed width. Although I found a plugin on the Web to override the default fixed width with fluid one, I’m not sure if it works with JPolite. ( http://snipplr.com/view.php?codeview&id=9786 )

        Michael

      • Michael,

        If you take a look at modules.js variable
        _columnLayout = {
        _default: { bg:'normal',
        c1:'span-8',
        c2:'span-8',
        c3:'span-8 last',
        c4:'span-24'
        },
        t2:{ bg:'darker',
        c1:'span-24 last',
        c2:'span-8',
        c3:'span-8',
        c4:'span-8 last'
        }
        ...

        span-8, span-24 … are class names you can assign to body and containers. Here you can add an additional attributes for div#content (the container of containers), e.g., _default: { … CT:’container’…}, t3:{…CT:’fluid’…}

        And see the method rePosition in jpolite.core.js, which changes container and body class name when you switches tabs, add 2 more lines to change the class name od div#content

        rePosition: function (tab_id) {
        var x = $.extend({}, _columnLayout._default, _columnLayout[tab_id]),
        bc = $('body').attr('class') || 'normal';

        if (bc != x.bg) $('body').switchClass(bc, x.bg);
        delete x.bg;

        $('#content').attr('class', x.CT); //Add this line
        delete x.CT; //And this line

        for (var c in x) this[c].attr('class', 'cc ' + x[c]);
        }

        And you can switch between fixed and fluid layout at will

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s