{"id":26674191,"url":"https://github.com/intersel/blapy","last_synced_at":"2025-04-12T06:53:55.021Z","repository":{"id":35520022,"uuid":"39790509","full_name":"intersel/Blapy","owner":"intersel","description":"jQuery plugin that helps you to create and manage ajax and single page web applications (SPA) with almost no javascript coding to do it","archived":false,"fork":false,"pushed_at":"2024-01-29T19:59:38.000Z","size":4310,"stargazers_count":30,"open_issues_count":3,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-12T06:53:47.074Z","etag":null,"topics":["ajax-call","javascript","jquery","jquery-plugin","single-page-applications","spa"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intersel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-07-27T18:20:10.000Z","updated_at":"2024-07-03T15:40:30.000Z","dependencies_parsed_at":"2024-01-29T21:12:42.574Z","dependency_job_id":null,"html_url":"https://github.com/intersel/Blapy","commit_stats":{"total_commits":310,"total_committers":5,"mean_commits":62.0,"dds":0.1806451612903226,"last_synced_commit":"3a84eb45b17aca0c9ebf74432a7e190f3cc66bcf"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersel%2FBlapy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersel%2FBlapy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersel%2FBlapy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersel%2FBlapy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intersel","download_url":"https://codeload.github.com/intersel/Blapy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248530588,"owners_count":21119595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajax-call","javascript","jquery","jquery-plugin","single-page-applications","spa"],"created_at":"2025-03-26T02:17:53.552Z","updated_at":"2025-04-12T06:53:55.000Z","avatar_url":"https://github.com/intersel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blapy\n\n\n\u003e If you like Blapy, I'll be pleased that you star it :-)\n\n\nBlapy is a jQuery plugin that helps you to create and manage ajax and single page web applications (SPA) with almost no javascript coding to do it.\n\nYour 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.\n\nSo, it may help you to transform your \"normal\" web site in a web application without the hassle of changing the way you develop websites.\n\nBlapy will speed up your page load too as it won't load all the internet files every page change but only the requested new contents.\n\nBlapy is json compliant too and eases the integration of ajax/rest API with templating and routing services very simple to use... Blapy will be the \"V-iew\" in an MVC application approach...\n\nThe best of all is that your web application will be fully SEO compliant as Blapy uses normal URLs to do the routing and your html rendering output from your server to update your application blocks!\n\n# Have a look on the \"Hello World\" demo and other demos\n[Go and see the demo: https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/helloworld/](https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/helloworld/)\n\nYou can have a look on a more complete example based on the [SB Admin 2 - Free Bootstrap Admin Theme](https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/startbootstrap-sb-admin-2/pages/) (you can see the original one [here](http://startbootstrap.com/template-overviews/sb-admin-2/))\n\nor test the [\"To do list\" web Apps demo](https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/todomvc/) made with Blapy and inspired from [TodoMVC](http://todomvc.com/)\n\n[This one allows to dynamically load and display blapy block contents](https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/bootstrap-four-column-gallery/) that were hidden and which need to be displayed as they became visible.\n\nAll the demos found in the demos directory can be tested there : [https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/](https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/)\n\nWe invite you to have a deep look in the code source of the demos as they use quite every possible features and configurations available in Blapy as they are used to test the library.\n\n# How to install\n\nAs it is a simple jQuery plugin... copy all the provided Blapy directories somewhere in your project, then include the needed javascript libraries in your code then call the Blapy function... and you're done...\n\nAs an \"Hello world\" example:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003c!-- To run the current sample code in your own environment, copy this to an html page. --\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003c!-- load of the external libraries needed by Blapy (provided in the package) --\u003e\n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/extlib/jquery-3.3.1.min.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/extlib/sammy/lib/sammy.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/extlib/iFSM/extlib/jquery.dotimeout.js\"\t\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/extlib/iFSM/extlib/jquery.attrchange.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/extlib/json2html/json2html.js\"\u003e\u003c/script\u003e  \n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/extlib/iFSM/iFSM.js\"\u003e\u003c/script\u003e\n  \u003c!-- load of the Blapy script --\u003e\n  \u003cscript type=\"text/javascript\" src=\"\u003cmyrootdir\u003e/Blapy.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003c!-- start Blapy --\u003e\n\u003cbody id=\"myBlapy\"\u003e\n  \u003cdiv  id=\"mainContainer\"\n        data-blapy-container=\"true\"\n        data-blapy-container-name=\"mainContainer\"\n        data-blapy-container-content=\"helloWorld Test1\"\u003e\n  \tHello World...\n  \u003c/div\u003e\n  \u003cscript\u003e\n  \t$( document ).ready(function() {\n  \t\t$('#myBlapy').Blapy();\n  \t});\n  \u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nTable of Contents\n=================\n\n  * [Blapy](#blapy)\n  * [Have a look on the \"Hello World\" demo and other demos](#have-a-look-on-the-hello-world-demo-and-other-demos)\n  * [Who may need it?](#who-may-need-it)\n  * [Why would I use that?!](#why-would-i-use-that)\n  * [How does it work?](#how-does-it-work)\n  * [How to configure my pages to become pages of a web application?](#how-to-configure-my-pages-to-become-pages-of-a-web-application)\n  * [General algorithm of Blapy](#general-algorithm-of-blapy)\n  * [.Blapy(options)](#blapyoptions)\n  * [Blapy Blocks](#blapy-blocks)\n  * [Blapy Links](#blapy-links)\n  * [Triggered events](#triggered-events)\n    * [Blapy_PageLoaded](#blapy_pageloaded)\n    * [Blapy_PageReady](#blapy_pageready)\n    * [Blapy_beforePageLoad](#blapy_beforepageload)\n    * [Blapy_beforeContentChange](#blapy_beforecontentchange)\n    * [Blapy_afterContentChange](#blapy_aftercontentchange)\n    * [Blapy_doCustomChange](#blapy_docustomchange)\n    * [Blapy_ErrorOnPageChange](#blapy_erroronpagechange)\n  * [Sending events to Blapy](#sending-events-to-blapy)\n    * [\"loadURL\" event](#loadurl-event)\n    * [\"postData\" event](#postdata-event)\n    * [\"updateBlock\" event](#updateblock-event)\n  * [Blapy parameters sent when calling a URL](#blapy-parameters-sent-when-calling-a-url)\n  * [Blapy animation plugin functions](#blapy-animation-plugin-functions)\n  * [LIBRARY DEPENDENCIES](#library-dependencies)\n  * [FAQ](#faq)\n  * [Problem resolutions](#problem-resolutions)\n  * [Contact](#contact)\n\n\n# Who may need it?\nEveryone 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.\n\nEveryone who...\n* would like to keep the way he builds websites but would like to have it behaves like an ajax web application.\n* gave up with AngularJS and other javascript frameworks to build web app... like me ;-)\n* wants to integrate json REST API with a simple approach without coding...\n* is starting with Javascript...\n* does not want to learn a Nth new framework to do websites...\n* wants to keep the application SEO compliant with google...\n\nAnd, as I just discovered it recently, for those who are using [pjax](https://github.com/defunkt/jquery-pjax), Blapy may be a good alternative too... You'll tell me!\n\n# Why would I use that?!\nThe 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...\n\nWhereas PHP -or whatever web server languages- websites built on a standard CMS are easier to handle... Any standard CMS does the page rendering job quite naturally for years... Except that it reloads pages when clicking a link... or it needs to develop ajax calls to dynamically update parts of the page...\n\nSo, 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.\n\nThe benefits of using Blapy?\n\n* no difficult framework to understand how to build a web application\n* no REST or Ajax url end points to develop. Of course, you can do that if you like to have your application that way ;-)\n* no change in your habit to develop website: building the pages with Blapy don't change from the \"static\" usual way of doing a website, meaning you can continue to use your standard LAMP and CMS environement\n* configuration is simple and quite natural: it uses html5 \"data\" attributes to configure the Blapy configuration and there is quite nothing to do from an existing website :-)\n* the ajax things are done behind the scene with no js lines of code to implement them\n* the history of browsing is kept as any smart framework\n* completly compliant with any existing html/js code\n* SEO compliant as the server keeps the control on the application behaviour on the loaded pages and blocks, and so it is able to deliver correct contents to search engines as google.\n\n# How does it work?\n\nThe main simple idea behind Blapy is to automatically and dynamically bind and update html blocks in ajax during the web navigation from page to page.\n\nSimple ;-) but powerful...\n\nRules defined on the html blocks with data attributes will specify how the blocks should be updated with their new dynamic contents.\n\nlet's have a first html file test1.html with some blocks with special attributes we will see later on...\n\n```html\n\u003cbody id=\"myBlapy\"\u003e\n  \u003ch1\u003eI'm test1.html file\u003c/h1\u003e\n  \u003cul\u003e\n  \t\u003cli\u003e\u003ca href=\"test1.html\" data-blapy-link=\"true\"\u003eHello World!\u003c/a\u003e\u003c/li\u003e\n  \t\u003cli\u003e\u003ca href=\"test2.html\" data-blapy-link=\"true\"\u003eHow is it going?\u003c/a\u003e\u003c/li\u003e\n  \u003c/ul\u003e\n  \u003cdiv id=\"mainContainer\" data-blapy-container=\"true\" data-blapy-container-name=\"mainContainer\" data-blapy-container-content=\"helloWorld\"\u003e\n  \tHello World\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\n**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...**\n\nYou 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...\nPerhaps meet some problem with the browser history when going back... etc... etc...\n\nWith 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 :\n\n```html\n\u003cbody id=\"myBlapy\"\u003e\n  \u003ch1\u003eI am test2.html file\u003c/h1\u003e\n  \u003cul\u003e\n  \t\u003cli\u003e\u003ca href=\"test1.html\" data-blapy-link=\"true\"\u003eHello World!\u003c/a\u003e\u003c/li\u003e\n  \t\u003cli\u003e\u003ca href=\"test2.html\" data-blapy-link=\"true\"\u003eHow is it going?\u003c/a\u003e\u003c/li\u003e\n  \u003c/ul\u003e\n  \u003cdiv data-blapy-container=\"true\" data-blapy-container-name=\"mainContainer\" data-blapy-container-content=\"Howisitgoing?\"\u003e\n\t  How is it going?\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\nThese two html files will load and behave normally if you load them and click the links.\n\nWell, just add at the end of your files this little script :\n\n```javascript\n\u003c!-- load of the external libraries needed by Blapy (provided in the package) --\u003e\n\u003cscript type=\"text/javascript\" src=\"extlib/jquery-3.3.1.min.js\"\t\t\t\t\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"extlib/sammy/lib/sammy.js\"\t\t\t\t\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"extlib/iFSM/extlib/jquery.dotimeout.js\"\t\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"extlib/iFSM/extlib/jquery.attrchange.js\"\u003e\u003c/script\u003e\n\u003cscript type=\"text/javascript\" src=\"extlib/iFSM/iFSM.js\"\t\t\t\t\t\u003e\u003c/script\u003e\n\u003c!-- load of the Blapy script --\u003e\n\u003cscript type=\"text/javascript\" src=\"Blapy.js\"\u003e\u003c/script\u003e\n\u003c!-- start Blapy --\u003e\n\u003cscript\u003e\n\t$( document ).ready(function() {\n\t\t$('#myBlapy').Blapy();\n\t});\n\u003c/script\u003e\n```\n\nYou 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...\n\nTada! you've got a **client web application** :-)\n\n# How to configure my pages to become pages of a web application?\n\n## Identify the common blocks between your different pages\n* Identify the common blocks (div, p, ... html tags) between your pages. When you use a CMS, these blocks are the same ones than those you identified when building your website.\n\n```html\n  \u003cdiv id=\"myContainer\"\u003e\n\t  How is it going?\n  \u003c/div\u003e\n```\n\n* Tell to Blapy that these blocks are the ones that may be updated from page to page:\n  * add a \"data-blapy-container\" attribute set to true in order to configure this container as a Blapy container\n  * give a name identifier to the container with the \"data-blapy-container-name\" attribute in order to identify this content block as unique.\n  * give a content name to identify each unique page content to be used with the \"data-blapy-container-content\" attribute.\n\n```html\n  \u003cdiv id=\"myContainer\"  data-blapy-container=\"true\" data-blapy-container-name=\"mainContainer\" data-blapy-container-content=\"Howisitgoing\"\u003e\n\t  How is it going?\n  \u003c/div\u003e\n```\n\nYou can create as many Blapy containers as you need parts of your page to be updated.\n\n## Identify the links that update contents\n* Identify the links pointing to pages that have contents you would like to use to update the content blocks of your current page.\n\n```html\n\u003ca href=\"test1.html\"\u003eHello World!\u003c/a\u003e\n```\n\n* Tell the links that they need to be handled by Blapy by using the \"data-blapy-link\" attribute.\n\n```html\n\u003ca href=\"test1.html\" data-blapy-link=\"true\"\u003eHello World!\u003c/a\u003e\n```\n\n* Call Blapy jquery script on the body of your page (or any main div in your page)... **The html block should have an \"id\" attribute**.\n\n```html\n\u003chtml\u003e\n...\n\u003cbody id=\"myBlapy\"\u003e\n...\n\u003cdiv id=\"myContainer\"  data-blapy-container=\"true\" data-blapy-container-name=\"mainContainer\" data-blapy-container-content=\"Howisitgoing\"\u003e\n\t  How is it going?\n  \u003c/div\u003e\n...\n\u003cscript type=\"text/javascript\" src=\"../Blapy.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\t$( document ).ready(function() {\n\t\t$('#myBlapy').Blapy();\n\t});\n\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nThat's it: your blocks will be automatically updated by ajax calls to the other pages according to your configuration.\n\n\n# General algorithm of Blapy\n\nThe general algorithm of Blapy is the following:\n\n* when a link is called (clicked) and if it is a \"blapy-link\",\n  * get the new content from the clicked page through an ajax call\n  * get all the \"blapy-container\" of the current page\n  * for each \"blapy-container\" of the current page\n     * Get the \"blapy-container\" with the same name (\"blapy-container-name\") from the new page\n     * Compare \"blapy-container-content\" : is the current \"blapy-container-content\" different from the new one?\n         * if \"yes\", then change the \"blapy-container\" with the new one\n\n\n# .Blapy(options)\n\nBlapy is the jQuery function that starts your web application.\n\n```javascript\n$(\"#\u003can id\u003e\").Blapy(options);\n```\n\n## Options\nOptions is a javascript object. It can take as input the following possible option parameters :\n\n* **debug**: (default:false) if true, then log things in the console\n* **LogLevel**: (default:1) log level: 1: error ; 2: warning; 3: notice\n* **AlertError**: (default:false) show an alert box on error messages if true\n* **activeSammy**: (default:false) if set to true, will use Sammy for URL routing\n* **pageLoadedFunction**: (default:null) function to call when the page is loaded\n* **pageReadyFunction**: (default:null) function to call when the page is ready\n* **beforePageLoad**: (default:null) function to call before the page load the new content\n* **beforeContentChange**: (default:null) function to call when a Blapy bloc will have its content changed\n* **afterContentChange**: (default:null) function to call after a Blapy bloc has its content changed\n* **afterPageChange**: (default:null) function to call when the page had all its content changed\n* **onErrorOnPageChange**: (default:null) function to call when the page got an error during change\n* **fsmExtension**: (default:null) Finite State Machine (iFSM) definition in order to extend the default blapy's iFSM engine\n\n## Example:\n\n```javascript\n\t$( document ).ready(function() {\n\t\t$('#bodyId').Blapy({activeSammy:true,debug:true,LogLevel:2})\n\t});\n```\n\n## Remarks\n\n**Blapy absolutely needs to be called on an object with an \"id\" set.**\n\nThat means that if you'd like to bind Blapy to the \"body\", you **have to** set an id on the body element:\n\n```html\n\u003cbody id=\"bodyId\"\u003e\n...\n\u003c/body\u003e\n```\n\n**You can have as many separate Blapy blocks as you like.**\n\n```javascript\n\t$( document ).ready(function() {\n\t\t$('#myBlapyApp1,#myBlapyApp2,#myBlapyApp3').Blapy();\n\t});\n```\n\nThis way, you will be able to tell which application a Blapy block should update when loaded.\n\nSee \"data-blapy-applyon\" option on Blapy blocks.\n\n# Blapy Blocks\nBlapy blocks are the parts where you would like the content to be updated from external contents downloaded through ajax calls by Blapy.\n\nA Blapy block may be any html element where you have set Blapy attributes that define the behaviour as Blapy blocks.\n\nThese attributes are analysed from the external Blapy block in order to know how the updating process should be applied on the current block.\n\nTo define a Blapy Block, you need to use the following attributes:\n\n## Attributes\n\n* **data-blapy-container**: set to \"true\", tells that the current html tag is Blapy block.\n* **data-blapy-container-name**: gives the name of the Blapy block. It will identify the block.\n* **data-blapy-container-content**: gives the subject of the content. It will identify the content of the block.\n* **data-blapy-update** (option, default:'update'): tells how Blapy should update the Blapy block when an external page or content is loaded.\n  * **update**: if the container-name is found from the external content and its container-content is different from the current page,\n the Blapy block of the current page is to be replaced by the new one\n  * **force-update**: if the container-name is found from the external content, the Blapy block of the current page is to be replaced by the new one\n  * **append**: if the container-name is found from the external content, the external content should be added to the end of the current Blapy block content.\n  * **prepend**: if the container-name is found from the external content, the external content should be added before the current Blapy block content.\n  * **replace**: if the container-name is found from the external content, the inner content of the external content should replace the current Blapy block content.\n  * **json**: the content of the current container is considered to be a (Mustache or json2html) template to apply on json data.\n When the blapy block needs to be updated, then it is considered that the new content is a json object or an array of json objects that will be parsed with the given template.\n These json data will be applied on the template. These parameters allows the json configuration:\n      * **data-blapy-template-file** (option): defines a URL called to get the template to apply on json data if the container (that is used to define the template) is empty\n      * **data-blapy-template-wrap** (option): once the json data are rendered, it is possible to wrap the result by giving the wrap html tag (ex: \"```\u003ctable\u003e```\")\n      * **data-blapy-template-header** (option): once the json data are rendered, it is possible to set a header (ex: \"```\u003ctr\u003e\u003cth\u003eheader\u003c/th\u003e\u003c/tr\u003e```\")\n      * **data-blapy-template-footer** (option): once the json data are rendered, it is possible to set a footer (ex: \"```\u003ctr\u003e\u003cth\u003efooter\u003c/th\u003e\u003c/tr\u003e```\")\n      * **data-blapy-template-default-id** (option): if multiple templates are set, set the default one to use on initialization. Default to the first found one.\n      * **data-blapy-template-mustache-delimiterStart** (option): available for mustache template, blapy will change the default start and end delimiters and use the new mustache delimiters when parsing the block. Actually, the new delimiters are set at the beginning of the template just before rendering, allowing blocks parsed within blocks with different rendering tags. Example: \"\u003c%\"\n      * **data-blapy-template-mustache-delimiterEnd** (option): available for mustache template and should be defined if  data-blapy-template-mustache-delimiterStart is defined. Example: \"%\u003e\"\n      * **data-blapy-template-init** (option): a (REST) URL to get json data to use to initialize the block\n        * **data-blapy-template-init-params** (option): json string of the parameters to send to the URL\n        * **data-blapy-template-init-method** (option): 'GET' (default) || 'POST' || 'PUT' || 'DELETE'\n        * **data-blapy-template-init-fromproperty** (option): path to the property in the returned json that should be used as data input. eg: \"data.results\" will use the object found in jsonReturnData.data.results as the json data to use\n        * **data-blapy-template-init-search** (option): ```\"\u003cproperty\u003e==\u003cvalue\u003e[,\u003cproperty\u003e==\u003cvalue\u003e,...]\"``` will get the objects that match the query. Examples:\n          * id==2, will get all objects that have their 'id' property equals to '2'\n          * id==  , will get all objects that have an 'id' property\n          * ==2, will get all objects that have properties equals to '2'\n        * **data-blapy-template-init-processdata** (option): a function name that take a json object and should return a json object. It will be called once the json data is received from the url and before to be processed in its blapy block.\n        * **data-blapy-template-init-purejson** (option): '0' (\"blapy oriented\" json) || '1' (default) (not \"blapy oriented\" json),\n  * **remove**:  if the container-name is found from the external content, then the Blapy block is to be removed.\n  * **custom**:  if the container-name is found from the external content, then we call the custom change 'doCustomChange' if defined\n and send the Blapy_doCustomChange event.\n  * **[an animation plugin function name]**: if the container-name is found from the external content,\n function to call and apply to do the content change.\n The available plugin functions may be found in the Blapy_AnimationPlugins.js file.\n* **data-blapy-update-rule**: ['local'|'external' (default)], if 'local', will use the data-blapy-update rule defined in the current block, else will use the one defined in the external block. Exception to the default value, a \"json\" block is always \"local\".\n* **data-blapy-applyon** (option, default:'all'): By default, the Blapy blocks loaded by a Blapy link will be tried on all Blapy blocks.\nIf defined, the external container will only be applied on the matched Blapy blocks contained in the given application id element.\n* **data-blapy-href** (option): a URL to call on **data-blapy-updateblock-time** (if set) or on **data-blapy-updateblock-ondisplay**\n* **data-blapy-updateblock-time** (option): a time in milliseconds when the URL set in 'data-blapy-href' should be called to update the block.\n* **data-blapy-updateblock-ondisplay** (option): if set to true, the block will be initialized from **data-blapy-href** or from **data-blapy-template-init** (if data-blapy-update is set to \"json\") when the element becomes visible (after a scroll).\n\n\n## Examples\n\n```html\n\t\t\u003cdiv \tdata-blapy-container=\"true\"\n\t\t\t\tdata-blapy-container-name=\"mainContainerApp3\"\n\t\t\t\tdata-blapy-container-content=\"aContent2\"\n\t\t\t\tdata-blapy-applyon=\"myBlapyApp1,myBlapyApp3\"\n\t\t\u003e\n\t\t\t\u003ch3\u003ea Content\u003c/h3\u003e\n\t\t\tThis is content...\n\t\t\u003c/div\u003e\n```\n```html\n\t\t\u003cdiv \tdata-blapy-container=\"true\"\n\t\t\t\tdata-blapy-container-name=\"submainContainerApp1\"\n\t\t\t\tdata-blapy-container-content=\"aSubContent\"\n\t\t\t\tdata-blapy-update=\"remove\"\n\t\t\u003e\n\t\t\u003c/div\u003e\n```\n\n\n# Blapy Links\nA Blapy Link is a url link that should be handled by Blapy.\n\nA Blapy link may be attached to the html \"`\u003ca\u003e`\" or \"`\u003cform\u003e`\" tags by specifying a \"data-blapy-link\" attribute on it.\n\nIt may be attached to other kind of tag, then you will have to specify the \"data-blapy-href\" attribute to explicit the hyperlink.\n\n**Remarks on blapy links on tags that are not \"a\" or \"form\"**\n* In this case, Blapy automatically binds a click event on this element in order to simulate an anchor.\n* The routing mecanism done with Sammy does not apply on them.\n\nTo define a Blapy Link, here are its attributes:\n\n## Attributes\n\n* **data-blapy-link**: tells that the current link has to be handled by Blapy.\n  * set to \"**true**\" (or void), Blapy will \"get\" the content of the link and will process the blapy blocks matching with the current application content\n\n**Remarks:** if data-blapy-link is set to a form, the \"method\" configuration (eg. \"GET\", \"POST\", \"PUT\", \"DELETE\") is used to get the content.\nYou can add this proprety \"method\" to a A dom element to set the method to use when the link is clicked.\n\n* **data-blapy-href**: if not bound to a \"A\" or \"FORM\" tag, it tells the hyperlink to use.\n\n* **data-blapy-params**: a json string to set paramaters to send along to the link to call\n\n* **data-blapy-embedding-blockid**: tells to embed the return source of the link in a blapy block of the given name. Usefull for return sources that are not 'blapy' formatted and that address a specific block...\n* **data-blapy-active-blapyId**: useful in the case the link is embedded in several different blapy objects, it gives the correct blapy object for the link. If not set, the link will be processed by all the blapy objects that contain the link.\n* **data-blapy-noblapydata**: if set to \"1\", no blapy information data are sent to the URL.\n\n## Examples\n\n```html\n\u003cul\u003e\n\t\u003cli\u003e\u003ca href=\"content1.php\" data-blapy-link=\"true\"\u003eContent 1\u003c/a\u003e\u003c/li\u003e\n\t\u003cli data-blapy-href=\"content2.php\" data-blapy-link=\"true\"\u003eContent 2\u003c/a\u003e\u003c/li\u003e\n\t\u003cli\u003e\n    \u003ca href=\"jsoncontent3.php\"     \n        data-blapy-link=\"true\"\n        data-blapy-embedding-blockid=\"mainContainerApp3\"\n        data-blapy-params='{\"id\":\"12\",\"label\":\"test\"}'\n        method=\"POST\"\n    \u003e\n      Content 3\n    \u003c/a\u003e\n  \u003c/li\u003e\n\u003c/ul\u003e\n```\n\n# Triggered events\nBlapy generates the specific events during the Blapy object change processing.\n\nSome events are sent to the DOM element on which you create the jquery **blapy object**, some apply on the **blapy block** where occurs the processing.\n\n## Blapy_PageLoaded\nTriggered when a page is fully and normally loaded and sent to the **blapy object** once when it is initialized.\n\n## Blapy_PageReady\nTriggered when the page is ready after a change in the page, and sent to the **blapy object**.\n\nIt is triggered after a \"loadURL\" or \"postData\" event sent to Blapy (see hereafter).\n\n## Blapy_beforePageLoad\nTriggered before a page loads its new content and sent to the **blapy object**.\n* Parameters: the Blapy json data sent to the URL\n  * [data].aUrl: url to call\n  * [data].params: json of the parameters to send to aUrl\n\n## Blapy_afterPageChange\nTriggered after a page loaded its new content and sent to the **blapy object**.\n* Parameters: the Blapy json data sent to the URL\n  * [data].aUrl: url to call\n  * [data].params: json of the parameters to send to aUrl\n\n\n## Blapy_beforeContentChange\nTriggered before a Blapy block content change and sent to the (jquery) **blapy Block** that will change.\n* Parameters:\n  * the Blapy block\n\n## Blapy_afterContentChange\nTriggered after a Blapy block content has changed and sent to the (jquery) **blapy Block** that has changed..\n* Parameters:\n  * the Blapy block\n\n## Blapy_templateReady\nTriggered after a Blapy block content has its template loaded and ready, sent to the (jquery) **blapy Block**..\n* Parameters:\n  * the Blapy block\n\n\n## Blapy_doCustomChange\nTriggered if data-blapy-update='custom', sent to the object that should change its content\n* Parameters:\n  * newObject : the new Blapy Block\n\n## Blapy_ErrorOnPageChange\nTriggered when an error occured during a page content change.\n* Parameters:\n  * anError: the error message\n\n## Examples\nTo listen to Blapy events, you may use the jQuery 'on' function as in this example:\n\n```javascript\n\t$(\"#myBlapy\").on( \"Blapy_ErrorOnPageChange\", function(event,anError) {\n\t\t  alert( anError );\n\t});\n\t$(\"#myBlapy\").on( \"Blapy_beforePageLoad\", function(event,anError) {\n\t\t  alert( 'call before loading new blocks...' );\n\t});\n\t//assure that the event will be received by the new DOM object #mainContainer if it has been replaced by Blapy\n\t$(document).on( \"Blapy_afterContentChange\",\"#mainContainer\", function(event,aBlock) {\n\t\t\t  alert( 'Blapy_afterContentChange of block '+$(aBlock).attr('id'));//aBlock refer to the #mainContainer dom object\n\t\t\t});\n```\n\n# Sending events to Blapy\n\nYou can activate some features of Blapy by sending events to it with the 'trigger' function of jQuery:\n\n```javascript\n$('#\u003cid of the blapy application tag\u003e').trigger(\u003canEvent\u003e,{\n  aUrl:\u003caURL to call\u003e,\n  params:{\u003csomeParameters\u003e}\n  ...\n  });\n```\n\n## \"loadURL\" event\n\nThis event allows you to call a URL.\n\n```javascript\n$('#\u003cid of the blapy application tag\u003e').trigger('loadUrl',{\n  aUrl:\u003caURL to call\u003e,\n  params:{\n    embeddingBlockId:\u003ca Blapy Block Id\u003e,\n    templateId:\u003ca xmp id of a json template\u003e\n  },\n  noBlapyData:\"\u003c0|1\u003e\"\n});\n```\n\n### params\n\n* **aUrl**: the Url to call\n* **params**:\n  * **embeddingBlockId** (optional): a block container name (data-blapy-container-name)\n  * **templateId** (optional): an id of an xmp object that describes a json template of a json block. Remarks: \"embeddingBlockId\" needs to be defined.\n* **noBlapyData**: if set to \"1\", no blapy information are sent (default: blapy data are sent)\n\n### Example\n\n```javascript\n$('#myBlapy').trigger('loadUrl',{\n  aUrl:\"helloworld_2.php\",\n});\n```\n\n## \"postData\" event\n\n```javascript\n$('#\u003cid of the blapy application tag\u003e').trigger('postData',{\n  aUrl:\"\u003caURL to call\u003e\",\n  params:{\n    embeddingBlockId:\"\u003caContainerName\u003e\",\n    templateId:\u003ca xmp id of a json template\u003e\n  },\n  method:\"\u003chttp method\u003e\",\n  noBlapyData:\"\u003c0|1\u003e\"\n});\n```\n\n### params\n\n* **aUrl**: the Url to call\n* **params**:\n  * **embeddingBlockId** (optional): a block container name (data-blapy-container-name)\n  * **templateId** (optional): an id of an xmp object that describes a json template of a json block. Remarks: \"embeddingBlockId\" needs to be defined.\n  * any property/value to send to the server\n* **method** (option)\n  * 'post' (default)\n  * 'put'\n  * 'delete'\n  * 'get' (same behaviour than \"loadURL\" event in this case)\n* **noBlapyData**: if set to \"1\", no blapy information are sent (default: blapy data are sent)\n\n### Example\n\n```javascript\n$(\"#myBlapy\").trigger('postData',{\n  aUrl:\"testForm.php\",\n  params:{fname:'Emmanuel',lname:'Podvin'}\n});\n```\n\n## \"updateBlock\" event\n\nThis event allows you to call Blapy to directly update a Blapy block.\n\n```javascript\n$('#\u003cid of the blapy application tag\u003e').trigger('updateBlock',{\n  html:\u003ca blapy content\u003e,\n  params:{\n    embeddingBlockId:\u003ca Blapy Block Container Name\u003e,\n    templateId:\u003ca xmp id of a json template\u003e\n  }\n});\n```\n\n### params\n\n* **html**\n  * any blapy content (blapy blocks, json string or objects, ...)\n* **params**:\n  * **embeddingBlockId** (optional): a block container name (data-blapy-container-name)\n  * **templateId** (optional): an id of an xmp object that describes a json template of a json block. Remarks: \"embeddingBlockId\" needs to be defined.\n\n### Example\n\n```javascript\n$('#myBlapy').trigger('updateBlock',{\n    html:\"[{name:\"John Doe\"}]\",\n    params:{embeddingBlockId:'myBlapyBlock'}\n  });\n```\n\n## \"reloadBlock\" event\n\nThis event allows you to reload the Blapy blocks using their init configuration (init url).\n\n```javascript\n$('#\u003cid of the blapy application tag\u003e').trigger('reloadBlock',{\n  params:{\n    embeddingBlockId:\u003ca Blapy Block Container Name\u003e,\n    templateId:\u003ca xmp id of a json template\u003e\n  }\n});\n```\n\n### params\n\n* **params**:\n  * **embeddingBlockId** (optional): a block container name (data-blapy-container-name). If none given, all the json blocks are reloaded.\n  * **templateId** (optional): an id of an xmp object that describes a json template of a json block. Remarks: \"embeddingBlockId\" needs to be defined.\n\n### Example\n\n```javascript\n$('#myBlapy').trigger('reloadBlock',{\n  params:{embeddingBlockId:'myBlapyBlock'}\n});\n```\n\n\n# Blapy parameters sent when calling a URL\nWhen Blapy calls a 'Blapy Link', the following parameters are sent along the other GET/POST/PUT/DELETE parameters:\n\n* **blapycall**=1 - tells that the call is coming from Blapy\n* **blapyaction**=[anAction] -tells the kind of action that will be operated\n  * **update**: blocks will be updated\n\nKnowing these parameters allows 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.\n\nYou can deactivate the sending of these data by configuring the data-blapy-noblapydata parameter.\n\n# JSON template\n\nThe json template are the content definition of a blapy json block type (cf. data-blapy-update) that will be parsed on json data sent to the block.\n\nA json template may use \"[Mustache](https://github.com/janl/mustache.js)\" or \"[json2html](http://json2html.com/)\" tags.\n\nWhen the blapy block has its property \"data-blapy-update\" set to \"json\", the content of the block is considered to be a template.\n\n## Example\n\n```html\n\u003csection id=\"jsonTPLExample\"\n      data-blapy-container=\"true\"\n\t\t\tdata-blapy-container-name=\"jsonTPLExample\"\n\t\t\tdata-blapy-container-content=\"aTPL\"\n\t\t\tdata-blapy-update=\"json\"\n\t\t\tdata-blapy-template-init=\"myJsonData.json\"\n\u003e\n  My name is {{firstname}}!\u003cbr\u003e\n\u003c/section\u003e\n```\n\nif the response of \"myJsonData.json\" is an array of json data, something like that:\n```json\n[\n  {\"firstname\":\"Emmanuel\"},\n  {\"firstname\":\"Maryse\"},\n  {\"firstname\":\"Augustin\"},\n]\n```\n\nThe resulting parse of the blapy block in the browser will be:\n```html\n\u003csection id=\"jsonTPLExample\"\n      data-blapy-container=\"true\"\n\t\t\tdata-blapy-container-name=\"jsonTPLExample\"\n\t\t\tdata-blapy-container-content=\"aTPL\"\n\t\t\tdata-blapy-update=\"json\"\n\t\t\tdata-blapy-template-init=\"myJsonData.json\"\n\u003e\n  My name is Emmanuel!\u003cbr\u003e\n  My name is Maryse!\u003cbr\u003e\n  My name is Augustin!\u003cbr\u003e\n\u003c/section\u003e\n```\n\n## Remarks\n\nIt is possible to have blapy blocks inside your template. They will be parsed once the template is applied on the json data. This way, you can have blapy blocks that are configured with your json data...\n\nIf the received json data is an array (like in the above example), Blapy will automatically add a property \"blapyIndex\" setting the index of the item in the array.\n\nFor the above example, the json data to be parsed on the template will actually be\n```json\n[\n  {\"firstname\":\"Emmanuel\",\"blapyIndex\":\"1\"},\n  {\"firstname\":\"Maryse\",\"blapyIndex\":\"2\"},\n  {\"firstname\":\"Augustin\",\"blapyIndex\":\"3\"},\n]\n```\n\nThis \"blapyIndex\" may be used in your template as any other of properties (${blapyIndex} or {{blapyIndex}})...\n\nIt starts from 1... if json data is not an array, then blapyIndex is set to 0.\n\n## Multiple templates\nAccording to the context, you may need to change the template of your block to display differently your data.\n\nIt is so possible to define several templates for the same block. These templates can be selected through the Blapy API with the messages \"updateBlock\", \"postData\", \"reloadBlock\"...\n\nThe way to describe them needs the use of the XMP tag and the \"data-blapy-container-tpl\" (to be set to true) and \"data-blapy-container-tpl-id\" properties, like in the following example:\n\nThe \"data-blapy-template-default-id\" property may be used to set the default template by default.\n\n```html\n\u003csection id=\"jsonTPLExample\"\n      data-blapy-container=\"true\"\n\t\t\tdata-blapy-container-name=\"jsonTPLExample\"\n\t\t\tdata-blapy-container-content=\"aTPL\"\n\t\t\tdata-blapy-update=\"json\"\n\t\t\tdata-blapy-template-init=\"myJsonData.json\"\n      data-blapy-template-default-id=\"secondTPL\"\n\u003e\n  \u003cxmp style=\"display:none\" data-blapy-container-tpl=\"true\" data-blapy-container-tpl-id=\"firstTPL\"\u003e\n    My name is {{firstname}}!\u003cbr\u003e\n  \u003c/xmp\u003e\n  \u003cxmp style=\"display:none\" data-blapy-container-tpl=\"true\" data-blapy-container-tpl-id=\"secondTPL\"\u003e\n    Is {{firstname}} your firstname?\u003cbr\u003e\n  \u003c/xmp\u003e\n\u003c/section\u003e\n```\n\nYou may call the \"reloadBlock\", \"postData\" or \"updateBlock\" event messages to change the template to use. It will reload the json data from the server and display them with the updated template.\n\neg: this example will use \"secondTPL\" template to display the data in \"results\" block.\n```javascript\n$('#myBlapy').trigger('postData',\n  {\n    \"aUrl\": \"testForm.php\",\n    \"params\":{\n      \"embeddingBlockId\":\"results\",\n      \"templateId\": \"secondTPL\",\n      \"firstname\":$(\"select[name=firstname]\",'#myForm').val(),\n      \"lastname\":$('input[name=lastname]:checked', '#myForm').val()\n    }\n  }\n);\n```\n\n# Blapy animation plugin functions\n\nIt is possible to create its own animation plugin functions on Blapy blocks when they are loaded.\n\nIt is also a way to hook features on the content that will be placed in a Blapy block...\n\nThe prototype of an animation plugin function is :\n\n```javascript\ntheBlapy.prototype.myAnimationFunction = function (oldContainer,newContainer) {}\n```\n\nHave a look in the Blapy_AnimationPlugins.js and add your new functions in it inspired by the existing functions.\n\n# LIBRARY DEPENDENCIES\nTo work properly, you need to include the following javascript libraries:\n\n* jQuery (\u003e= 3.x)\n  * `\u003cscript type=\"text/javascript\" src=\"extlib/jquery-3.3.1.min.js\"\u003e\u003c/script\u003e`\n* [iFSM by intersel](https://github.com/intersel/iFSM/)\n  * this library manages finite state machines and needs these libraries:\n    * **doTimeout** by [\"Cowboy\" Ben Alman](http://benalman.com/projects/jquery-dotimeout-plugin/)\n    * this library brings some very usefull feature on the usual javascript setTimeout function like Debouncing, Delays \u0026 Polling Loops, Hover Intent...\n    * `\u003cscript type=\"text/javascript\" src=\"extlib/jquery.dotimeout.js\"\u003e\u003c/script\u003e`\n  * **attrchange** by [Selvakumar Arumugam](http://meetselva.github.io/attrchange/)\n    * a simple jQuery function to bind a listener function to any HTML element on attribute change\n    * `\u003cscript type=\"text/javascript\" src=\"extlib/jquery.attrchange.js\"\u003e\u003c/script\u003e`\n* [json2html](http://json2html.com/) (optional if blapy block does not use json feature or use \"Mustache\" template engine)\n  * json2html is a javascript HTML templating library used to transform JSON objects into HTML using a template.\n  * used for json parsing and templating\n    * `\u003cscript type=\"text/javascript\" src=\"../../extlib/json2html/json2html.js\"\u003e\u003c/script\u003e`\n* [Mustache](http://mustache.github.io/) (optional if blapy block does not use json feature or use \"json2html\" template engine)\n  * Mustache  is a javascript HTML templating library used to transform JSON objects into HTML using a template.\n  * used for json parsing and templating\n    * `\u003cscript type=\"text/javascript\" src=\"../../extlib/mustache/mustache.js\"\u003e\u003c/script\u003e`\n* [Sammy](http://sammyjs.org/) (optional if you don't need routing management)\n  * Sammy is a small framework to make web application providing simple but efficient 'route' services\n  * `\u003cscript type=\"text/javascript\" src=\"extlib/sammy/lib/sammy.js\"\u003e\u003c/script\u003e`\n* [json5](https://json5.org/) (optional if your json are \"straight\" json)\n  * expands the syntax of JSON in order to be able to process less strict json input (made by humans for example)\n  * `\u003cscript type=\"text/javascript\" src=\"extlib/json5/index.min.js\"\u003e\u003c/script\u003e`\n* [jquery.appear](http://morr.github.io/appear.html) (optional if you don't need to init blocks when they become visible after a scroll)\n  * `\u003cscript type=\"text/javascript\" src=\"extlib/jquery.appear/jquery.appear.js\"\u003e\u003c/script\u003e`\n\n# FAQ\nIf you have questions or unsolved problems, you can have a look on the our [FAQs](https://github.com/intersel/Blapy/wiki)\nor leave a message on the [Issue board](https://github.com/intersel/Blapy/issues).\n\n## When a Blapy link is called, does the server need to send a full HTML page with a body and ...\nNo, you can optimize your code by only sending the useful Blapy blocks.\n\n\n## Is it possible to set Blapy blocks in \"head\" tags?\nYes, but in order to have the Blapy see them, set an id on the html tag and call Blapy on it:\n\n### Example\n\n```html\n\u003chtml id=\"myBlapy\"\u003e\n\u003chead\u003e\n\t\u003ctitle \tdata-blapy-container=\"true\"\n\t\t\tdata-blapy-container-name=\"Title\"\n\t\t\tdata-blapy-container-content=\"myTitle\"\u003eThis is a title page\u003c/title\u003e\n\t\u003cscript\u003e\n\t\t$( document ).ready(function() {\n\t\t\t$('#myBlapy').Blapy();\n\t\t});\n\t\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003c!--  body part --\u003e\n\u003c/body\u003e\n\u003c/html\u003e  \n```  \n\n## How to define template variables in a blapy template for json blocks\n\nThe syntax follows the one defined by [json2html library](http://json2html.com/): ${myVariableName}\nOR the one defined by [Mustache](http://mustache.github.io/): {{myVariableName}}\naccording to the library you have set.\n\n### Examples\n\nWith json2html:\n```\n\t\tFirst name: ${fname}\u003cbr\u003e\n\t\tLast name: ${lname}\u003cbr\u003e\n```\n\nWith Mustache:\n```\n\t\tFirst name: {{fname}}\u003cbr\u003e\n\t\tLast name: {{lname}}\u003cbr\u003e\n```\n\n## How to set a json template driven by Blapy...\nLet's say we would like to create a dynamic table as the following example:\n\n```html\n\u003csection id=\"tableExample\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\u003ctd\u003eJohn\u003c/td\u003e\u003ctd\u003eDoe\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd\u003eBob\u003c/td\u003e\u003ctd\u003eDylan\u003c/td\u003e\u003c/tr\u003e\n    ....\n  \u003c/table\u003e\n\u003c/section\u003e\n```\n\nFirst step is to define the blapy block:\n```html\n\u003csection id=\"tableExample\"\n      data-blapy-container=\"true\"\n\t\t\tdata-blapy-container-name=\"results\"\n\t\t\tdata-blapy-container-content=\"void\"\n\t\t\tdata-blapy-update=\"json\"\n\t\t\tdata-blapy-template-wrap=\"\u003ctable\u003e\"\n\t\t\tdata-blapy-template-init=\"arrayvalues.data.php\"\n\u003e\n  \u003ctr\u003e\u003ctd\u003e${firstname}\u003c/td\u003e\u003ctd\u003e${lastname}\u003c/td\u003e\u003c/tr\u003e\n\u003c/section\u003e\n```\nSome explanations on the defined attributes:\n  - _data-blapy-update=\"json\"_: the blapy block is filled with json data. So the content in the block is the template to apply on the json data. The template may be given by an external file with the property \"data-blapy-template-file\".\n  - _data-blapy-template-wrap=\"```\u003ctable\u003e```\"_: the template is wrapped with a 'table' tag\n  - _data-blapy-template-init=\"arrayvalues.data.php\"_: the values to init our block are to be found in this file\n\nThe returned content of the \"data-blapy-template-init\" file should contain the addressed blapy block definition (\"data-blapy-container-name\") with a json struture with the data to display, and so should be something like the following example:\n\n```html\n\u003csection id=\"tableExample\"\n\tdata-blapy-container=\"true\"\n\tdata-blapy-container-name=\"results\"\n\tdata-blapy-container-content=\"initContent\"\n\u003e\n[\n{firstname: \"John\",lastname: \"Doe\"},\n{firstname: \"Bob\",lastname: \"Dylan\"},\n...\n]\n\u003c/section\u003e\n```\n\nOf course, this content may be dynamically generated by the server side.\n\nOnce you start blapy like with \"('#tableExample').Blapy();\", blapy will automatically read the json content of the \"data-blapy-template-init\" file and will apply its content to the html template.\n\nThe resulting content will be like the example to produced...\n\n\n## How to set conditional output in a json template\n\nInstead of having a HTML template, you can set a javascript that will be interprated to generate the DOM.\n\nThe javascript should be inserted with the specific tag **\"```\u003cblapyScriptJs\u003e```\"**.\n\n### Example\n\nThis example shows how \"```\u003cli\u003e```\" statement will be inserted according to the statut of \"dontdisplay\" variable.\n\n#### Initial blapy definition\n\nLet's define a UL statement that we want be filled with LI statements.\n\nIt will be initialized from the \"data-blapy-template-init\" variable with the content returned by myInitFile.php file. It could have been initialized with a \"loadUrl\" or \"postData\" calls.\n\n```\n\u003cul id=\"MenuExampleWithInitializedWithJSScript\"\n    data-blapy-container=\"true\"\n\tdata-blapy-container-name=\"MenuExampleWithInitializedWithJSScript\"\n\tdata-blapy-container-content=\"MenuExampleVoid\"\n\tdata-blapy-update=\"json\"\n\tdata-blapy-template-init=\"myInitFile.php\"\n\u003e\n     \u003cblapyScriptJS\u003e\n        \tif (!\"${dontdisplay}\")\n            \tjQuery('#MenuExampleWithInitializedWithJSScript').append('\u003cli class=\"${class}\"\u003e\u003ca href=\"${url}\"\u003e${action}\u003c/a\u003e\u003c/li\u003e');\n     \u003c/blapyScriptJS\u003e\n\n\u003c/ul\u003e\n```\n\nPlease note that what myIntFile.php returns as data content should have only data initialization for this block.\n\n#### Example of data that could be sent to Blapy by myInitFile.php\n```\n\u003cul id=\"MenuExampleWithInitializedWithJSScript\"\n\tdata-blapy-container=\"true\"\n\tdata-blapy-container-name=\"MenuExampleWithInitializedWithJSScript\"\n\tdata-blapy-update=\"json\"\n\u003e\n\t[\n\t\t{class: \"\",url: \"#\",action:\"Action\"},\n\t\t{class: \"\",url: \"#\",action:\"Action Not Shown\",dontdisplay:'1'},\n\t\t{class: \"\",url: \"#\",action:\"Another action\",dontdisplay:'1'},\n\t\t{class: \"myClass\",url: \"#\",action:\"Something else here\"},\n\t]\n\u003c/ul\u003e\n```\n\nor the same description but in full json description:\n```\n[\n\t{ \t\"blapy-container-name\":\"MenuExampleWithInitializedWithJSScript\",\n\t\t\"blapy-data\":\n\t\t[\n\t\t{class: \"\",url: \"#\",action:\"Action\"},\n\t\t{class: \"\",url: \"#\",action:\"Action Not Shown\",dontdisplay:'1'},\n\t\t{class: \"\",url: \"#\",action:\"Another action\",dontdisplay:'1'},\n\t\t{class: \"myClass\",url: \"#\",action:\"Something else here\"},\n\t\t]\n\t}\n]\n```\n\n\n#### Example result\n\nThe result will be processed as:\n\n```\n\u003cblapyScriptJS\u003e\n        \tif (!\"\")\n            \tjQuery('#MenuExampleWithInitializedWithJSScript').append('\u003cli class=\"\"\u003e\u003ca href=\"#\"\u003eAction\u003c/a\u003e\u003c/li\u003e');\n\u003c/blapyScriptJS\u003e\n\u003cblapyScriptJS\u003e\n        \tif (!\"1\")\n            \tjQuery('#MenuExampleWithInitializedWithJSScript').append('\u003cli class=\"\"\u003e\u003ca href=\"#\"\u003eAction Not Shown\u003c/a\u003e\u003c/li\u003e');\n\u003c/blapyScriptJS\u003e\n\u003cblapyScriptJS\u003e\n        \tif (!\"1\")\n            \tjQuery('#MenuExampleWithInitializedWithJSScript').append('\u003cli class=\"\"\u003e\u003ca href=\"#\"\u003eAnother action\u003c/a\u003e\u003c/li\u003e');\n\u003c/blapyScriptJS\u003e\n\u003cblapyScriptJS\u003e\n        \tif (!\"\")\n            \tjQuery('#MenuExampleWithInitializedWithJSScript').append('\u003cli class=\"myClass\"\u003e\u003ca href=\"#\"\u003eSomething else here\u003c/a\u003e\u003c/li\u003e');\n\u003c/blapyScriptJS\u003e\n```     \n\nand so, giving the following processed DOM:\n\n```     \n\u003cul id=\"MenuExampleWithInitializedWithJSScript\"\n\tdata-blapy-container=\"true\"\n\tdata-blapy-container-name=\"MenuExampleWithInitializedWithJSScript\"\n\tdata-blapy-update=\"json\"\n\u003e     \n\t\u003cli class=\"\"\u003e\u003ca href=\"#\"\u003eAction\u003c/a\u003e\u003c/li\u003e\n\t\u003cli class=\"myClass\"\u003e\u003ca href=\"#\"\u003eSomething else here\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n```\n\n\n\n## How to send several json objects to a json block\nYou just defined an array the way you would do in javascript with your json objects\n\n```html\n\t\u003cdiv  \n\t\tdata-blapy-container=\"true\"\n\t\tdata-blapy-container-name=\"resultFormJson\"\n\t\tdata-blapy-container-content=\"resultFormJson\"\n\t\tdata-blapy-update=\"json\"\n\t\u003e\n\t[\n\t{fname: \"Emmanuel\",lname: \"Durand\"},\n\t{fname: \"Maryse\",lname: \"Dupond\"}\n\t]\n\t\u003c/div\u003e\n```\n\n## How to send \"pure\" json as response to a query ?\n\nBy default, when there is a blapy call, you define a blapy block and put your json data inside it and send the result back.\n\nIt is possible to return \"pure\" json to be handled by Blapy.\n\nThere are two possible configurations:\n* the json content returned has no information on the Blapy blocks that should be updated\n* the json content is blapy oriented\n\n### Json has no information about blapy blocks\n\nIt applies to content that comes from outside your web application, that are not aware of Blapy ;-)\n\nIn order to tell to Blapy on what blapy block this kind of content should update, you need to configure the Blapy link that calls the json content.\n\nUse the \"data-blapy-embedding-blockid\" parameter and configure it to the name of your Blapy block.\n\nThat's it! When the blapy link will call your json content, all your blapy block with the given name will be updated with the json content.\n\n#### Example\n\n**HTML File**\n\n```html\n\u003ca href=\"myJsonDataFile.json\"\n\tdata-blapy-link=\"true\"\n\tdata-blapy-embedding-blockid=\"aBlapyBlockToUpdate\"\n\t\t\t\u003eClick here to update my \"aBlapyBlockToUpdate\" to update\n\u003c/a\u003e\n\u003cdiv  \n\t\tdata-blapy-container=\"true\"\n\t\tdata-blapy-container-name=\"aBlapyBlockToUpdate\"\n\t\tdata-blapy-update=\"json\"\n\u003e\nThis is ${jsonContent}\u003cbr\u003e\nThe other content is: ${anotherContent}\n\u003c/div\u003e\n```\n\n**myJsonDataFile.json**\n\n```\n{\"jsonContent\":\"a content for myJsonDataFile...\",\"anotherContent\":\"another content for the example\"}\n```\n\n\n**Remark:** You can have a look on the \"demos/verifyEmails\" demo that use this feature.\n\n### The returned Json content is Blapy oriented\n\nIt is possible to configure your json content in order to give all the blapy blocks information and the data to transmit to the blapy blocks.\n\nTo do so, send an array of objects, each one will describe a blapy block. All the blapy attributes may be given to configure your blapy block. The names are those described in this document without the \"data-\" at the beginning of the name. For example, \"data-blapy-container\" will have \"blapy-container\" as attribute object.\n\nThe necessary attributes are:\n* **blapy-container-name**: name of the blapy container\n* **blapy-container-content**: identifier name of the content\n* **blapy-data**: the json data to send to the blapy block\n\nIt is expected that that the answer returns an array of blapy objects.\n\n#### Example of a response to a blapy call\n\nThe following blapy block definitions are the same:\n\n* usual blapy block\n```html\n\u003cdiv\n\tdata-blapy-container-name=\"fnameOptions\"\n\tdata-blapy-container-content=\"fnameOptionsNew\"\n\u003e\n\t\t[\n\t\t\t{\"firstname\": \"John\",\"lastname\": \"Doe\",\"selected\":\"false\"},\n\t\t\t{\"firstname\": \"Bob\",\"lastname\": \"Dylan\",\"selected\":\"false\"},\n\t\t\t{\"firstname\": \"Peter\",\"lastname\": \"Rabbit\",\"selected\":\"false\"},\n\t\t]\n\u003c/div\u003e\n```\n\n* pure json blapy block corresponding to the above example\n\n```javascript\n[\n\t{ \t\"blapy-container-name\":\"fnameOptions\",\n\t\t\"blapy-container-content\":\"fnameOptionsNew\",\n\t\t\"blapy-data\":\n\t\t[\n\t\t\t{\"firstname\": \"John\",\"lastname\": \"Doe\",\"selected\":\"false\"},\n\t\t\t{\"firstname\": \"Bob\",\"lastname\": \"Dylan\",\"selected\":\"false\"},\n\t\t\t{\"firstname\": \"Peter\",\"lastname\": \"Rabbit\",\"selected\":\"false\"},\n\t\t]\n\t}\n]\n```\n\n## How to initialize the blapy blocks after loading the page?\n\nThe idea is to directly call the url that will initialize your page by calling one of the Blapy API functions \"loadURL\" or \"postData\" just after the Blapy initialization.\n\nExample:\n```html\n$( document ).ready(function() {\n    $('#myBlapy').Blapy();\n    $('#myBlapy').trigger('loadUrl',{aUrl:\"init_my_page.php\"})\n});\n```\n\n## How to update a blapy block at a regular period ?\nYou have two attributes for Blapy blocks named \"data-blapy-href \" and \"data-blapy-updateblock-time\" that let you configure the URL to call and the period to call it.\n\nThis example will update the block every second (1000ms) from index.php:\n```html\n        \u003cdiv    data-blapy-container=\"true\"\n                        data-blapy-container-name=\"dateContainer\"\n                        data-blapy-container-content=\"aContent_\u003c?php echo uniqid();?\u003e\"\n                        data-blapy-href = \"index.php\"\n                        data-blapy-updateblock-time = \"1000\"\n                \u003e\n                    \u003cb\u003eTime is:\u003c/b\u003e \u003c?php echo date('d-M-Y H:i:s');?\u003e\n        \u003c/div\u003e\n```\n## How to set a loader when blapy updates a content?\n\nUse the events \"Blapy_beforePageLoad\" and \"Blapy_afterPageChange\" in order to active/deactivate your loader, as in the following example:\n\n```html\n\u003cscript\u003e\n\t$(\"#myBlapy\").on( \"Blapy_beforePageLoad\", function(event) {\n\t\t$('#loader').show();\n\t});\n\t$(\"#myBlapy\").on( \"Blapy_afterPageChange\", function(event) {\n\t\t$('#loader').hide();\n\t});\n\u003c/script\u003e\n```\n\n## What about the id sent in the returned blapy blocks...\nGenerally, the new block will replace the old one, and so, the id will follow... and that's mainly ok...\n\nSometime, if there are several blocks with the same data-blapy-container-name in order to update several blocks with the same info,\nit could be a problem that several new blocks get the same id after processing...\n\nYou can give **no id** on the new sent blocks, this way the system will set the id of the old block to change to the new one...\n\n## How to add new messages to the blapy objects\n\nThe idea is to add behaviour and features to our blapy object when it's ready, in order to do things like:\n```javascript\n$(\"\u003cmyBlypyObject\u003e\").trigger('alertUs',\"Hey there!\");\n```\n\nTo do that in the context of the FSM used in the Blapy object, we will extend it using **fsmExtension** option.\n\nThe safe state to extend is \"PageReady\", set when the blapy block object is ready to accept messages like \"loadUrl\" or \"postData\"...\n\nIn your blapy initialization, add your FSM extension as in this example:\n\n```Javascript\n$('#myBlapy').Blapy({\n  fsmExtension:{\n    'PageReady':{\n      'alertUs': {\n        init_function: function(parameters, event, data){\n          alert('alertUs called in '+this.myUIObject.attr('id')+' says: '+data);\n        }\n      }\n    }\n  }\n});\n```\nremarks:\n  * 'this' refers to the [FSM](https://github.com/intersel/ifsm)\n  * The Blapy object may be accessed with \"this.opts.theBlapy\".\n  * if you add new iFSM states, think to come back to the \"PageReady\" state at the end of your processing.\n\n## How can I preprocess received json Data before they are processed by Mustache ?\n\nThanks to the \"data-blapy-template-init-processdata\" parameter, you can give the name of function to do the preprocessing of your data and change and add any new properties to be processed by Mustache.\n\n### Example\n\n```html\n\n\u003cdiv ....\n  data-blapy-template-init-processdata=\"initMyJsonData\"\n\u003e\ncolor is {{#greenColor}}green{{/greenColor}}{{^greenColor}}... well... I don't know...{{/greenColor}}\n\u003c/div\u003e\n\n//....\n\n\u003cscript\u003e\n// declare a function visible from Blapy\n// aJson is an array of element(s) to process\nwindow.initMyJsonData = function(aJson)\n{\n  //for each elements, do an analysis and add/remove or do whatever you need to be done...\n  aJson = aJson.map(aData =\u003e {\n    if (aData[\"myPropertyColor\"] == \"green\")\n    {\n      aData[\"greenColor\"]=true;//add a new property\n      delete aData.myPropertyColor; //remove a property\n    }\n    return aData;//returns the modified array item\n  });\n  //return our modified json data array\n  return aJson;\n}\n\u003c/script\u003e\n```\n\n\n## How to have nested json templates ?\n\nThe problem addressed here is to be able to have json blocks initialized according to an upper block configuration.\n\nFor example, if you have a request that gives you a list of people with their id like ```[{\"id\":0,\"name\":\"Paul\"}, ...]```, you perhaps would like get their details from another request that would need the id of the person to get the information.\n\nTo do that, you would need to nest your blapy blocks: the first level will get the list of your people, the second level will get for each one their details...\n\nUsing Mustache, You will need to accomplish this:\n* the data-blapy-template-mustache-delimiterStart and data-blapy-template-mustache-delimiterEnd modifiers\n  * they will allow to distinguish between the first template (using the default Mustache delimiters \"{{\" and \"}}\") and the second one using an other set of tags like \"{%\" \"%}\"\n* to define data-blapy-container-name according to upper identifier tags. you can use the \"blapyIndex\" tag to get different names for your second level block.\n\n### Examples\n\n  ```\n  \u003cdiv data-blapy-container=\"true\"...blapy block 1st level definition...\u003e\n  The id is {{id}}.\u003cbr\u003e\n  The details are:\u003cbr\u003e\n    \u003cdiv  data-blapy-container=\"true\"\n          data-blapy-container-name=\"details_{{blapyIndex}}\"\n          data-blapy-template-mustache-delimiterStart=\"{%\"\n          data-blapy-template-mustache-delimiterEnd=\"%}\"\n          data-blapy-template-init=\"/people/getDetails/?id={{id}}\"\n          ...Blapy block 2nd level definition...\u003e\n    age of {{name}} is {%age%}\u003cbr\u003e...\n    \u003c/div\u003e\n  \u003c/div\u003e\n  ```\n\nIn a first pass, Blapy will get you the first level block parsed for every people using the \"{{ delimiters }}\", configuring your \"data-blapy-template-init\" URL with the id sent in the url.\nIn a second pass, all the sub blocks will be parsed by Blapy, getting all the details for each sub blocks and parsed the results with the new \"{% delimiters %}\"...\n\n### Escaping sub XMP\n\nAs recommanded, you can use ```\u003cXMP\u003e``` html tag to escape your json templates when needed... But there is a drawback as you can not nest this tag...\n```\n\u003cXMP\u003e\n  Hello,\n  \u003cXMP\u003e\n    I'm nested\n  \u003c/XMP\u003e\n  xmp...\n\u003c/XMP\u003e\n```\n Won't work as expected... and the text after the first closing XMP tag will close the whole xmp blocks...\n\nThe solution proposed by Blapy is to escape your sub XMP blocks. This is done by adding as many '|' as there is sub XMP level as in this example:\n\n ```\n //I'm a json template\n \u003cXMP\u003e\n   Hello,\n   ....\n   //I'm a sub json template\n   \u003c|XMP\u003e\n     I'm nested\n     ....\n     //I'm a sub sub json template\n     \u003c||XMP\u003e\n       and subnested...\n     \u003c||/XMP\u003e\n   \u003c|/XMP\u003e\n   xmp...\n \u003c/XMP\u003e\n ```\n\nBlapy will remove the \"|\" according to the level of parsing... and this way to nest as many json templates you like...\n\n### Demo\n\nHave a look to the full demonstration in [demos/demo_json_nested_blocks/index.html](https://www.intersel.fr/assets_intersel_a/gitdemos/Blapy/demos/demo_json_nested_blocks/)\n\n# Problem resolutions\n## My blapy block does not update from my external content...\n\n* Did you verify that your external block has a different **data-blapy-container-content** content than the current one? If not, the content is not updated as it is considered to be the same... The content of **data-blapy-container-content** may be any name. You can use the current time or a unique id to set the name as in this example:\n\n```html\n\u003cdiv    data-blapy-container=\"true\"\n                        data-blapy-container-name=\"dateContainer\"\n                        data-blapy-container-content=\"aContent_\u003c?php echo uniqid();?\u003e\"\n                \u003e\n                    \u003cb\u003eTime is:\u003c/b\u003e \u003c?php echo date('d-M-Y H:i:s');?\u003e\n        \u003c/div\u003e\n```\n\n* Maybe, the code of your external block is not a valid HTML code. For instance, if you use tbody as a blapy block, don't set it alone, but embed it within a table tag.\n\n## Clicking to a blapy link generates several ajax calls though it should generate only a unique call...\n* Verify your html return of the first ajax call. For instance, ```\u003cimg src=\"\" alt=\"\"\u003e``` will generate a second ajax call to index.html...\n\n## When routing is activated with Sammy, My URL does not work any more...\n* It's generally a problem linked to base URL. YOu can fix it by setting a ```\u003cbase\u003e```  html tag in your html head part:\n\n```html\n\t\u003cbase href=\"/demos/todomvc/\" target=\"_blank\"\u003e\n```\n## How to automate that every A / Form tags are \"blapy-link\"?\nBlapy expects that you define the A and Form tags as blapy links if you want them to be handled by blapy.\n\nHereafter, you can add this little script to automate that every A / Form tags become \"blapy-link=true\":\n\n```javascript\n// every new page load, will assure that every new links will have the \"blapy-link\" attribute\n$(document).on( \"Blapy_PageReady\",\"body\", function(event,anError) {\n\t\t$('#[[+BlapyApplicationId]]').find('a,form').attr('data-blapy-link','true');\n\t\tvar myBlapy = $('#\u003cYou Blapy DOM Object\u003e').getFSM();//get the FSM working behind the scene for blapy\n\t\tmyBlapy[0].opts.theBlapy.setBlapyUrl(); // call the function that will make blapy handle the url links\n\n});\n```\n\nOnce in place, every url links will be considered as Blapy Links...\n\n## When my template contains \"img\" tag with the name file defined by a placeholder, I've got a 404 error\nAs the file is parsed as HTML, img tag will try to load the image that does not exist as the image name is not the placeholder name.\n\nTo fix this, simply wrap your html template with the tag \"xmp\" which will neutralize html analysis.\n\n## My Blapy block does not appear when I change its style from \"display:off\" to \"display:block\" when \"data-blapy-updateblock-ondisplay\" is set\n\nThe jquery.appear object is not aware of a change in the display...\n\nIn order to alert it, you can simulate a scroll on the window just after changing the display status of your block with :\n```Javascript\n$(window).scroll();\n```\n\n# Contact\nIf you have any ideas, feedback, requests or bug reports, you can reach me at github@intersel.org,\nor via my website: http://www.intersel.fr\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersel%2Fblapy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintersel%2Fblapy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersel%2Fblapy/lists"}