├── .gitignore
├── LICENSE
├── README.md
├── demo
├── index.html
├── jquery-2.1.1.min.js
├── main.js
└── style.css
├── dev_modules
├── expiration-service.js
├── group-service.js
├── helper.js
├── history-service.js
├── page-store.js
├── promise-service.js
├── smartjax.js
└── store-service.js
├── factory
├── Gruntfile.js
├── fixed_modules
│ ├── footer.js
│ └── header.js
├── package.json
└── tasks
│ ├── concat.js
│ ├── uglify.js
│ └── watch.js
├── package.json
├── smartjax.js
└── smartjax.min.js
/.gitignore:
--------------------------------------------------------------------------------
1 | *.DS_Store
2 | */node_modules/*
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2014 Paul Shan
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
23 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Smartjax : make your ajax calls smarter
2 |
3 | ## Demo
4 | [Working demo](http://www.voidcanvas.com/demo/1339smartjax-demo/)
5 |
6 | ## Description
7 | Smartjax stores your API responses and does not ping the server for the same ajax call for the second time (options are available for force call too).
8 |
9 | **Example**
10 |
11 | You display your logged in user's summary in the top-right corner of your site. But to display that in every page you either need to make an ajax call, or have to make a server side processing. But using smartjax, you will get rid of all those processing.
12 |
13 | Display it by making an ajax call using Smartjax. It will make the first call to get the user info and will store it internally. You can store the information for page level, tab's lifetime level or for forever. You can clear the entire store or the response for a particular one anytime you want.
14 |
15 | ## Why useful?
16 |
17 | * Reducing http calls will give your site a performance boost.
18 | * It will also reduce your server side processing, as the client side itself returns the result.
19 | * You can store responses for the lifetime of a page, a tab, or forever.
20 | * The plugin is very light weight.
21 | * You don't have to learn a lot. Instead of $.ajax(), use Smartjax.ajax() and it will start caching. There are some extra flags and methods you need to know to manage and clear your stored response.
22 |
23 |
24 | ## How to use:
25 | This is very very simple to use the smartjax. Below is a comparison.
26 |
27 | **In jQuery:**
28 |
29 | ```javascript
30 | $.ajax({
31 | url:'http://httpbin.org/post',
32 | type: 'POST',
33 | data:{
34 | a:1,b:2
35 | }
36 | });
37 | ```
38 |
39 | **In Smartjax:**
40 |
41 | ```javascript
42 | Smartjax.ajax({
43 | url:'http://httpbin.org/post',
44 | type: 'POST',
45 | data:{
46 | a:1,b:2
47 | }
48 | });
49 | ```
50 |
51 | Smartjax caches the result in the client side, and response with the same if you make the call again.
52 |
53 | ## Different level of caching
54 |
55 | Using the property *store* you can decide whether the response should be stored till the page gets refreshed, or until the tab is closed or should be stored forever.
56 |
57 | **Page level**
58 |
59 | ```javascript
60 | Smartjax.ajax({
61 | url:'http://httpbin.org/post',
62 | type: 'POST',
63 | data:{
64 | a:1,b:2
65 | },
66 | store:"page"
67 | });
68 | ```
69 |
70 | This will clear the response once you reload the page or navigate to another page.
71 |
72 | **Tab level**
73 |
74 | ```javascript
75 | Smartjax.ajax({
76 | url:'http://httpbin.org/post',
77 | type: 'POST',
78 | data:{
79 | a:1,b:2
80 | },
81 | store:"tab"
82 | });
83 | ```
84 |
85 | This will keep the response till the user closes the tab. Even if the page is refresehed or user navigates to another page, the response will be cached in smartjax and will be returned from client side cache, if same call is made again. This is default store type in smartjax.
86 |
87 | **Forever**
88 |
89 | ```javascript
90 | Smartjax.ajax({
91 | url:'http://httpbin.org/post',
92 | type: 'POST',
93 | data:{
94 | a:1,b:2
95 | },
96 | store:"forever"
97 | });
98 | ```
99 |
100 | If you don't want too remove the response of a particular call, use *forever* as the value of *store*. However, smartjax provide you methods to clean your entire store or a particular call response. So you can clear them explicitly, any time you want.
101 |
102 | **do not store**
103 |
104 | If *store* property is set to false in the call, the response will not be saved. If you do not want to store by default, you can change the store property in defaults. In the next point you will find how to set defaults.
105 |
106 | ```javascript
107 | Smartjax.ajax({
108 | url:'http://httpbin.org/post',
109 | type: 'POST',
110 | data:{
111 | a:1,b:2
112 | },
113 | store:false
114 | });
115 | ```
116 |
117 |
118 | ## How to control data flow:
119 |
120 | With some extra parameter in the Smartjax.ajax() call you can control the behavior of storing. Some of them also helps to clear the saved data.
121 |
122 | **force**
123 |
124 | If *force* property is true in a call, no matter even if the response is saved, but smartjax will make and fresh call and store the new result.
125 |
126 | ```javascript
127 | Smartjax.ajax({
128 | url:'http://httpbin.org/post',
129 | type: 'POST',
130 | data:{
131 | a:1,b:2
132 | },
133 | force:true
134 | });
135 | ```
136 | Default value for *force* option is false.
137 |
138 | **id**
139 |
140 | You can provide separate *id* to each call. So that you can individually identify a call. You can clear the saved response of the call by using the specified *id*.
141 |
142 | ```javascript
143 | Smartjax.ajax({
144 | url:'http://httpbin.org/post',
145 | type: 'POST',
146 | data:{
147 | a:1,b:2
148 | },
149 | id:"i1"
150 | });
151 | ```
152 |
153 | **group**
154 |
155 | You can group the calls using the *group* parameter. For the time being, the group is useful at the time of cleaning the store.
156 |
157 | ```javascript
158 | Smartjax.ajax({
159 | url:'http://httpbin.org/post',
160 | type: 'POST',
161 | data:{
162 | a:1,b:2
163 | },
164 | group:"group1"
165 | });
166 | ```
167 |
168 | **cleanStore(param)**
169 |
170 | This function is used to clean the store. You can provide list of groups or ids or both to be cleaned.
171 |
172 | ```javascript
173 | Smartjax.cleanStore({groups:["g1"], ids:["i1"]});
174 | ```
175 |
176 |
177 | **cleanAll()**
178 |
179 | This function is parameter-less and cleans all the saved records.
180 |
181 | ```javascript
182 | Smartjax.cleanAll();
183 | ```
184 |
185 | The function takes an object as a parameter. where you can mention the properties given above. By default, the default call method is 'get' (GET verb), but you can change it for all calls. Same in case of *force* and *store* options.
186 |
187 | ## Time based auto expiration
188 | If you want the cached API calls to be cleared after a certain period of time; you can run `.setExpirationWindow()` with parameters. See example in `demo/main.js`. The expiration is a periodic task which runs in every your given timeframe.
189 |
190 | ```javascript
191 | Smartjax.setExpirationWindow({
192 | seconds: 0,
193 | minutes: 1,
194 | hours: 0,
195 | days: 0,
196 | cleanAll: false, //default is false
197 | groupBasedClean: false //default is false
198 | });
199 | ```
200 | You can provide the time parameters in seconds, minutes etc. If you don't provide one, that will be considered as 0 (zero). If `cleanAll: true` option is used, it will clean all cached records, once the oldest cache record is crossed the given time limit. You can set `groupBasedClean:true` if you want to clean all calls of a group once the oldest one of that group is crossed the time limit.
201 |
202 | **Exception calls**
203 |
204 | If your time based expiration is on, but you want certain calls to keep its cache alive, you can set `noAutoClean:true` to that particular call. Below is an example.
205 |
206 | ```javascript
207 | Smartjax.ajax({
208 | url:'http://httpbin.org/get',
209 | type: 'GET',
210 | noAutoClean: true
211 | });
212 | ```
213 |
214 |
215 | #URL manipulation
216 |
217 | Smartjax has in-built support for URL manipulations. You can change your browser URL without reloading the entire page, using the following:
218 |
219 | **changeUrl()**
220 |
221 | ```javascript
222 | Smartjax.changeUrl({
223 | url:'/my-relative-url',
224 | params:{
225 | query1:'query text',
226 | myQuery:'my own query'
227 | }
228 | });
229 | ```
230 |
231 | The property 'url' is optional. If you don't provide, it will execute with current URL. The second property 'params' is to take a JSON object with query string params and values. If any param is already present in the url it will replace previous value with the new one.
232 |
233 |
--------------------------------------------------------------------------------
/demo/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 | Smartjax demo by voidcanvas.com
4 |
5 |
6 |
7 |