Blapy

Blapy is a jQuery plugin that helps you to create and manage an ajax web application without coding any javascript to do it.

The web application is built the usual way of generating web pages like with php or any standard CMS and Blapy will transform it into a dynamic web application with ajaxified contents and without coding any javascript.

So, it may help you to transform your "normal" web site in a web application too, creating easily ajax/rest calls without the hassle of changing the way you develop websites.

Who may need it?

Everyone using a CMS that generates web pages from a server and would like to transform his website to a client application-like website, ie that does not reload each page during the user navigation but only the needed blocks within the page.

Everyone who would like to keep the way he builds websites but would like to have it behaves like a web application.

The ones who gave up with AngularJS and other javascript frameworks to build web app... like me ;-)

Why should I use that?!

The concept of a web application getting data through REST Api with a client application that is doing the job of connecting the whole to build an application is quite a difficult job with a steep learning curve... Whereas PHP websites built on a standard CMS are easier to handle... The standard CMS does the page generation job quite naturally for years... Except that we reload pages when clicking a link... or we need to do ajax calls to dynamically update part of the pages...

So, the idea is to provide a simple environment that don't change your habits when creating your website without having the hassle of creating ajax calls:

Have a look on the "Hello World" demo

Go and see the demo: http://www.intersel.net/demos/intersel/Blapy/demos/helloworld/

How does it work?

The main simple idea is to automatically and dynamically bind and update html blocks in ajax during the web navigation from page to page.

Rules defined on the html blocks with data attributes will specify how the blocks should be updated with their new dynamic contents.

let's have a first html file test1.html with some blocks with special attributes we will see later on...

<body id="myBlapy">
  <h1>I'm test1.html file</h1>
  <ul>
    <li><a href="test1.html" data-blapy-link="true">Hello World!</a></li>
    <li><a href="test2.html" data-blapy-link="true">How is it going?</a></li>
  </ul>
  <div id="mainContainer" data-blapy-container="true" data-blapy-container-name="mainContainer" data-blapy-container-content="helloWorld">
    Hello World
  </div>
</body>

Let's imagine now that you would like that the website loads and updates only the "mainContainer" part without updating the whole page when we click on the test2.html link...

You surely know that you would need to call a URL in ajax, get the new content from the server and update the container with jQuery html function... Perhaps meet some problem with the browser history when going back... etc... etc...

With Blapy, just create a second test2.html file as usual: it will be quite the same than test1.html (let's imagine the files are php generated...) with a new content in the "mainContainer" part :

<body id="myBlapy">
  <h1>I am test2.html file</h1>
  <ul>
    <li><a href="test1.html" data-blapy-link="true">Hello World!</a></li>
    <li><a href="test2.html" data-blapy-link="true">How is it going?</a></li>
  </ul>
  <div data-blapy-container="true" data-blapy-container-name="mainContainer" data-blapy-container-content="Howisitgoing?">
      How is it going?
  </div>
</body>

These two html files will load and behave normally if you load them and click the links.

Well, just add at the end of your files this little script :

<script type="text/javascript" src="../Blapy.js"></script>
<script>
    $( document ).ready(function() {
        $('#myBlapy').Blapy();
    });
</script>

You will then see that when clicking on the page links, only the 'data-blapy-container' block is changed without reloading the whole page! You can see that as the title has not changed...

Tada! you've got a client web application :-)

How to configure my pages to become pages of a web application?

Identify the common blocks between your different pages

  <div id="myContainer">
      How is it going?
  </div>
  <div id="myContainer"  data-blapy-container="true" data-blapy-container-name="mainContainer" data-blapy-container-content="Howisitgoing">
      How is it going?
  </div>

You can create as many Blapy containers as you need parts of your page to be updated.

Identify the links that update contents

<a href="test1.html">Hello World!</a>
<a href="test1.html" data-blapy-link="true">Hello World!</a>
<html>
...
<body id="myBlapy">
...
<div id="myContainer"  data-blapy-container="true" data-blapy-container-name="mainContainer" data-blapy-container-content="Howisitgoing">
      How is it going?
  </div>
...
<script type="text/javascript" src="../Blapy.js"></script>
<script>
    $( document ).ready(function() {
        $('#myBlapy').Blapy();
    });
</script>
</body>
</html>

That's it: your blocks will be automatically updated by ajax calls to the other pages according to your configuration.

General algorithm of Blapy

The general algorithm of Blapy is the following:

.Blapy(options)

Blapy is the jQuery function that starts your web application. 

$("#<an id>").Blapy(options);

Options

Options is a javascript object. It can take as input the following possible option parameters :

Example:

    $( document ).ready(function() {
        $('#bodyId').Blapy({debug:true,LogLevel:2})
    });

Remarks

Blapy absolutely needs to be called on an object with an "id" set.

That means that if you'd like to bind Blapy to the "body", you have to set an id on the body element:

<body id="bodyId">
...
</body>

You can have as many separate Blapy blocks as you like.

    $( document ).ready(function() {
        $('#myBlapyApp1,#myBlapyApp2,#myBlapyApp3').Blapy();
    });

This way, you will be able to tell which application a Blapy block should update when loaded. See "data-blapy-applyon" option on Blapy blocks.

Blapy Blocks

Blapy blocks are the parts where you would like the content to be updated from external contents downloaded through ajax calls by Blapy.

A Blapy block may be any html element where you have set Blapy attributes that define the behaviour as Blapy blocks.

These attributes are analysed from the external Blapy block in order to know how the updating process should be applied on the current block.

To define a Blapy Block, you need to use the following attributes:

Attributes

Examples

        <div    data-blapy-container="true" 
                data-blapy-container-name="mainContainerApp3" 
                data-blapy-container-content="aContent2" 
                data-blapy-applyon="myBlapyApp1,myBlapyApp3"
        >
            <h3>a Content</h3>
            This is content...
        </div>
            <div    data-blapy-container="true" 
                    data-blapy-container-name="submainContainerApp1" 
                    data-blapy-container-content="aSubContent" 
                    data-blapy-update="remove"
            >
            </div>

Blapy Links

A Blapy Link is a url link that should be handled by Blapy.

A Blapy link may be attached to the html "<a>" or "<form>" tags by specifying a "data-blapy-link" attribute on it.

It may be attached to other kind of tag, then you will have to specify the "data-blapy-href" attribute to explicit the hyperlink.

To define a Blapy Link, here are its attributes:

Attributes

Remarks: if data-blapy-link is set to a form, the method configuration will be used if defined.

Examples

<ul>
    <li><a href="content1.php" data-blapy-link="true">Content 1</a></li>
    <li><a href="content2.php" data-blapy-link="true">Content 2</a></li>
</ul

Triggered events

Blapy generates the following events during the Blapy object change processing:

To listen to Blapy events, you may use the jQuery 'on' function as in this example:

    $("#myBlapy").on( "Blapy_ErrorOnPageChange", function(event,anError) {
          alert( anError );
    });

Sending events to Blapy

You can activate some features of Blapy by sending events to it with the 'trigger' function of jQuery:

$('#< id of the body tag>').trigger(<anEvent>,{aUrl:<aURL to call>,params:<someParameters>)

"loadURL" event

This event allows you to call a URL.

$('#<id of the blapy application tag>').trigger('loadUrl',{aUrl:<aURL to call>,params:{action:<anAction>}})

params

Example

$('#myBlapy').trigger('loadUrl',{aUrl:"helloworld_2.php",params:{action:'update'}})

"postData" event

$('#<id of the blapy application tag>').trigger('postData',{aUrl:<aURL to call>,params:{action:<anAction>},method:<http method>});

params

Example

$("#myBlapy").trigger('postData',{aUrl:"testForm.php",params:{fname:'couou',lname:'tatat'}})

Blapy parameters sent when calling a URL

When Blapy calls a 'Blapy Link', the following parameters are sent as GET parameters:

Knowing these parameters allow you to optimize the generated html returned by the server to the client, so sending back only the useful html blocks instead of the full html page.

Blapy animation plugin functions

It is possible to create its own animation plugin functions.

The prototype of an animation plugin function is :

theBlapy.prototype.myAnimationFunction = function (oldContainer,newContainer) {}

Have a look in the Blapy_AnimationPlugins.js and add your new functions in it inspired by the existing functions.

LIBRARY DEPENDENCIES

To work properly, you need to include the following javascript libraries:

FAQ

If you have questions or unsolved problems, you can have a look on the our FAQs or leave a message on the Issue board.

When a Blapy link is called, do the server need to send a full HTML page with a body and ...

No, you can optimize your code by only sending the useful Blapy blocks.

Is it possible to set Blapy blocks in "head" tags?

Yes, but in order to have the Blapy see them, set an id on the html tag and call Blapy on it:

Example

<html id="myBlapy">
<head>
    <title  data-blapy-container="true" 
            data-blapy-container-name="Title" 
            data-blapy-container-content="myTitle">This is a title page</title>
    <script>
        $( document ).ready(function() {
            $('#myBlapy').Blapy();
        });
    </script>
</head>
<body>
  <!--  body part -->
</body>
</html>

How to define template variables in a template

The syntax follows the one defined by json2html library : ${myVariableName}

Example

        First name: ${fname}<br>
        Last name: ${lname}<br>

How to send several json objects to a json block

You just defined an array the way you would do in javascript with your json objects

    <div id="aForm" 
        data-blapy-container="true" 
        data-blapy-container-name="resultFormJson" 
        data-blapy-container-content="resultFormJson"
        data-blapy-update="json"
    >
    [
    {fname: "Emmanuel",lname: "Durand"},
    {fname: "Maryse",lname: "Dupond"}
    ]
    </div>

Contact

If you have any ideas, feedback, requests or bug reports, you can reach me at github@intersel.org, or via my website: http://www.intersel.fr