Файл: doc/index.html
Строк: 429
<?php
<!Doctype html>
<html>
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="bootstrap/css/bootstrap.min.css" />
<style>
td {
padding: 10px;
}
pre.code {color:blue; display:inline-block;}
</style>
</head>
<body>
<div class="container">
<div class="jumbotron">
<h1><img src="domAjax.png" /> domAjax</h1>
<p>domAjax is a small HTML5 javascript library that allows any DOM element to make ajax requests</p>
</div>
<div class="row">
<div class="col-xs-12 col-md-10">
<h2>Introduction</h2>
<p>
I've worked on a few JavaScript projects and I'm not really a fan of writing ajax queries in jQuery. The whole process seems cumbersome and detached. Especially the part where you have to manipulate the DOM. You easily end up with messy code.</p>
<p>I've been wondering what it would be like if DOM elements could make ajax requests on their own and parse any JSON data returned through a micro templating engine and I wrote this small javascript library to test this concept. I have thoroughly enjoyed writing domAjax and I hope you enjoy using it as well.</p>
<p>The micro templating engine performs simple binding between JSON objects returned through an ajax call and the DOM node that made the ajax call. JSON properties are bound to template attributes and automatically parsed when the ajax call returns.
You can also easily write your own callback method to process any returned JSON and ovverride the default template engine behaviour.
</p>
<h2>How to Install</h2>
<p>You simply need to include the domAjax.js file just before the closing body tag. Note, if you include the script at the top of your HTML document, e.g. in the <head> tag, it won't be able to parse your document since the DOM would not have loaded.
<code><script src="domAjax.js"></script></code>
</p>
<h2>How to use domAjax</h2>
<p>
There a two ways to initialize domAjax to make ajax calls. Through data-* attributes and by calling the domAjax() global method and passing an array of JSON objects. <br />
<strong>Please note that you are required to set id values on every DOM node you want to activate domAjax on</strong>
<h4>data-* attributes</h4>
<p>
You can add specific data-* attribute properties to any DOM node to configure it to make ajax calls. There are two ways to specify your data attributes, either individually or through a single 'data-ajax-config' DOM property. <br />
The table below details all the possible data-* attributes you can use.
<table>
<tr><td><h4>data-* Attribute</h4></td> <td><h4>Detail</h4></td>
<td><h4>Example</h4></td></tr>
<tr>
<td>data-ajax-url</td>
<td>Required. Specifies the url that the ajax call would be made to.</td>
<td><code>data-ajax-url="/user/comments.json"</code></td>
</tr>
<tr>
<td>data-ajax-method</td>
<td>Optional. POST/GET/PUT/DELETE/HEAD or any other request method that should be passed to the ajax object.</td>
<td><code>data-ajax-method="post"</code></td>
</tr>
<tr>
<td>data-ajax-event</td>
<td>Optional. If you want this ajax call to be made on a specific event such as a mouse click you can specify it here. By default, the event listener is bound to this DOM node. Optionally, you can specify the 'id' of a different DOM node to bind the listener to together with the event using a dot notation. Look at the example for details</td>
<td>
<code>data-ajax-event="click"</code> <br />
<code>data-ajax-event="buttonID.click"</code> <br />
<code>data-ajax-event="custom_event"</code>
</td>
</tr>
<tr>
<td>data-ajax-callback</td>
<td>Optional. You can specify the name of a callback function which would be passed any returned JSON data and the id of the DOM node that made the ajax request. This property also supports the dot notation to reference a method which is a property of an object. You can only specify methods upto 3 levels deep into an object.
<br />E.g. obj.subobj.subobj.method <br />
obj.subobj.subobj.subobj.method would not be fetched and the default micro templating callback method would be used.
<p>
<kbd>handleAjax(json, event, domID)</kbd> <br />
'event' would be false if current ajax request wasn't triggered by an event.
</p>
</td>
<td>
<code>data-ajax-callback="handleAjax"</code> name of a global function <br />
<code>data-ajax-callback="user.processComments"</code> method in an object
<br />
<code>data-ajax-callback="user.posts.handleSave"</code> method 2 levels deep
<br />
<code>data-ajax-callback="user.settings.profile.handleSave"</code> 3 levels deep
</td>
</tr>
<tr>
<td>data-ajax-params</td>
<td>Optional. This property can be used to pass JSON data to the server as part of the request. If the request is a POST request, domAjax would store a stringified json data in a 'data' field before making with request with a content-type of 'application/x-www-form-urlencoded'. <br />
To retrieve the JSON data on the backend with php for example, you'll write
<br /><code><?php $json = json_decode($_POST['data']); ?></code><br />
Note, this property must contain valid json data for the data to be sent with the request.
</td>
<td>
<code>data-ajax-params=' { "email":"john@example.com", "token":"x54n"} '
</code></td>
</tr>
<tr>
<td>data-ajax-interval</td>
<td>Optional. Specified in miliseconds. e.g. 5000 = 5 seconds. If you would rather have the DOM node make periodic ajax calls instead of on a specific event, you can specify this interval property. <br />
The property also supports the dot notation to specify the maximum number of times the ajax call should be made. ie. interval.max_requests</td>
<td><code>data-ajax-interval="10000"</code> 10 seconds <br />
<code>data-ajax-interval="10000.20"</code>Stop making ajax calls after the the 20th request.</td>
</tr>
<tr>
<td>data-ajax-repeat</td>
<td>Optional. data-ajax-repeat is to be set on sub nodes of a domAjax node. This property performs the same thing as the ng-repeat directive of angular. It loops through an array of objects and for each object, it clones the template node parsing any {{template attributes}} on that object.
<br /><br />
If this property is set on a domAjax node (a node with property 'data-ajax-url' or 'data-ajax-config'), the data-ajax-repeat directive is not processed.
</td>
<td>
<pre class="code">
<div id="posts" data-ajax-url="/posts/">
<div class="single-post" data-ajax-repeat="posts">
<span><kbd>{{author.image}}</kbd></span>
<div>
<span>Written by <kbd>{{author.name}}</kbd></span>
<span>Submitted <kbd>{{dateCreated}}</kbd></span>
</div>
<div id="writeup">
<kbd>{{content}}</kbd>
</div>
<div class="comments">
<kbd>{{comments}}</kbd>
</div>
</div>
</div>
</pre>
</td>
</tr>
<tr><td colspan="3"><div class="text-center lead">domAjax-redirect</div></td></tr>
<tr>
<td>domAjax-redirect</td>
<td><p>When you make ajax calls, you may want to redirect the browser based on some condition on the server side, however, using the 300 redirect header would only redirect the ajax call not the browser.</p>
<p>You can set 'domAjax-redirect' as a root property of any json object returned to a domAjax ajax call and the domAjax library would automatically redirect the page.</p></td>
<td>
<pre class="code">
<?php
$json = array();
$json["why"] = "Invalid session";
$json["domAjax-redirect"] = "/user/login";
header("Content-type: application/json");
echo json_encode($json);
?>
</pre>
</td>
</tr>
<tr><td colspan="3"><div class="text-center lead">domAjax-html</div></td></tr>
<tr>
<td>domAjax-html</td>
<td><p>You may need to dynamically generate some HTML code on the backend and inject that into the page when an API call is made. The domAjax-html property makes this possible. You simply need to set a json property that has the text 'domAjax-html' as part of the name of the property. E.g. face-domAjax-html-body is a valid json property for this purpose.</p>
<p>On the front-end, you'll set your template variable as {{face-domAjax-html-body}}. Any HTML code you assign to this property would be injected into the page at the specified template variable</p></td>
<td>
<pre class="code">
<?php
$json = array();
$htm = "<button> Click me </button>";
$json["face-domAjax-html-body"] = $htm;
header("Content-type: application/json");
echo json_encode($json);
?>
<div> {{face-domAjax-html-body}} </div>
</pre>
</td>
</tr>
<tr><td colspan="3"><div class="text-center lead">Initialize through data-ajax-config</div></td></tr>
<tr>
<td>data-ajax-config</td>
<td>Required. The data-ajax-config property allows you to easily set all the above properties without having to repeatedly type "data-ajax".
<br /> This property must contain valid json. And the json must have the required url property.</td>
<td><code>data-ajax-config=' {"url":"user.php", "method":"get", <br />
"event":"getuser", "callback":"user.setProfile", <br />"params":{ "email":"john@example.com", "token":"x54b", "limit":50 } } '</code></td>
</tr>
<tr><td colspan="3"><div class="text-center lead">domAjax Precedence</div>
<div>
This is the order in which the domAjax library processes data-ajax properties.
Event takes precedence over interval. So if you specify data-ajax-event and data-ajax-interval on the same node, the data-ajax-interval would be ignored and that DOM node would make an ajax request on the specified event.
However, if no event or interval is specified, only a url, the ajax request is made instantly and the result processed through your supplied callback or the default micro templating callback.
</div>
</td></tr>
</table>
</p>
<h4>domAjax global method</h4>
<p>
If you don't want to add data attributes to your dom nodes, you can simple initialize domAjax via javascript.
<pre>domAjax(
[ {
id:"required",
url:"required",
method:"", // defaults to 'get'
event:"", // optional
interval:"", // optional
callback:"", // optional
params:{} // optional
}, {id:"", ...},
{id:"", ...}
]);</pre>
</p>
<h4>micro templating</h4>
<p>
The micro templating engine is the default callback method that processes any returned json if you don't provide your own callback method. It allows you to easily bind json properties to {{corresponding_template_attributes}}. These are written in {{double curly braces}}. <br />
The templating engine also supports the use of dot notation to access sub objects/properties but just like the data-ajax-callback property, it can only go 3 levels into an object. "Obj.obj.obj.prop". Unlike angular though, this library does not support repeating templates ie. ng-repeat. <br />
Below is an example putting everything together <br />
Method = get, and it'll use the default micro templating engine. So no callback.
<pre class="code">
<div id="post" data-ajax-url="/posts/5">
<span class="profile_image"><kbd>{{post.author.image}}</kbd></span>
<div>
<span class="pull_left">Written by <kbd>{{post.author.name}}</kbd></span>
<span class="pull_right">Submitted <kbd>{{post.dateCreated}}</kbd></span>
</div>
<div id="writeup">
<kbd>{{post.content}}</kbd>
</div>
<div class="comments">
<kbd>{{post.comments}}</kbd>
</div>
</div>
</pre>
</p>
</p>
<h2>Limitations</h2>
<p>
domAjax is intended for use in small projects that make simple ajax calls. For more complex web projects, a more robust library should be used such as Angular which can handle many more use cases than domAjax. <br /><br />
I've also written the library to work with json data. Please feel free to modify the code as you please based on your project demands. For example, you may want to process blobs returned from an ajax call. You'll need to process the 'status' property of the ajax object not the 'statusText' prop. I'm currently processing the statusText prop.
</p>
<h2>This project is supported. Feel free to get in touch through the CodeCanyon site on any issues.</h2>
</div>
</div>
</div>
</body>
</html>
?>