AsyncDocs plugin documentation
Author: Vladimir Vershinin
Copyright: 2013, Vladimir Vershinin
License: http://www.gnu.org/licenses/gpl-2.0.html GNU General Public License
============================================================================
The plugin to ajaxify MODx site.
Loads pages asynchronously.
###Current version: 1.1.2
INSTALLATION
-
Extract plugin archive or clone repository to the directory "MODxRoot/assets/plugins/asyncdocs"
-
Create a new plugin in the manager called "AsyncDocs" and copy/paste the contents of assets/plugins/AsyncDocs/plugin.txt into the code field.
-
Check "OnWebPageInit" and "OnCacheUpdate" events at the System Events tab.
-
Optional:
If you use some plugins for custom urls, then check "OnPageNotFound" event and set AsyncDocs the first in execution order for this event
If you want always minify page html check "OnWebPagePrerender" event
-
Copy/paste to the config field on the Config tab
&Configuration:=AsyncDocs;; &contentSelector=XPath to the content DOM element;string; &fields=Document fields;textarea;pagetitle||longtitle||description &chunks=List of additional chunks separated by "||";textarea; &excludeChunks=Exclude chunks list separated by "||";textarea; &setHTTPCode=Set HTTP response codes;list;false,true;true &urlScheme=Document URL scheme;list;,full; &contentOnly=Return only content field of document;list;false,true;false &cache=Use cache;list;false,true;true &minify=Minify output;list;false,true;true
-
Set needed plugin options
USAGE
Some preparations before use:
- Move the immutable part of a template in chunks (e. g: header and footer) and list these chunks in &excludeChunks option.
or
- Set the XPath to the content DOM element in &contentSelector option. This element will be extracted from document output.
or if you want load clear content
- Set &contentOnly option to true
Plugin options:
- &contentSelector - XPath to the content DOM element
- &fields - Document fields (list of doc fields to add to the response separated by "||")
- &chunks - Additional chunk (list of chunks to add to the response separated by "||"). Record format: chunkName:prop1~val1:prop2~val2||chunkName2:prop1~val1. Chunk output cached by default, to disable caching - add as as property: cache~false or 0, i.e. chunkName:prop1~val1:prop2~val2:cache~false
- &excludeChunks - Exclude chunks (list of chunks to exclude from document content separated by "||")
- &setHTTPCode - Set HTTP response codes
- &urlScheme - url scheme, passed to DocumentParser::makeUrl method. Default value: empty string - relative url
- &contentOnly - Return only content field of document without template process. Default: false. May be overridden per request by passing in request: asyncdocs_contentonly = true or false or 1 or 0
- &cache - Load and save document cache or not. Default: true. May be overridden per request by passing in request: asyncdocs_contentonly = true or false or 0 or 1
- &minify - Minify output html of documents, chunks and snippets. If you check AsyncDocs fire on OnWebPagePrerender Event - it will minify page html
To get page via ajax make an ajax request to url of the page that you need. To execute plugin you must add asyncdocs: 1 to request fields or set
request header: X-AsyncDocs: AsyncDocs.
In response plugin set the HTTP Status code: 200 - OK, 301 - Moved for references, 401 - Unauthorized, 404 - Not found, so be careful to handle all this cases in you ajax callbacks.
jQuery example request with field:
$.ajax({
url: pageUrl,
dataType: 'json',
data: {
asyncdocs: 1
[, asyncdocs_contentonly: true || false ] // Process template or not for current document (optional, override global option)
[, asyncdocs_cache: true || false ] // Use cache or not for current document (optional, override global option)
},
success: function(response) {
// process response, change page content
},
error: function(xhr) {
// process errors
// check xhr.status
},
// or use
statusCode: {
301: function() {
},
401: function() {
},
404: function() {
}
}
});
jQuery example request with header:
$.ajax({
url: pageUrl,
dataType: 'json',
headers: {
'X-AsyncDocs': 'AsyncDocs'
},
success: function(response) {
// process response, change page content
},
error: function(xhr) {
// process errors
// check xhr.status
},
// or use
statusCode: {
301: function() {
},
401: function() {
},
404: function() {
}
}
});
The plugin returns a json object:
{
chunks: [], // array of rendered additional chunks
content: string, // document output
dir: string, // document tree direction, "up"(up the documents tree) or "down"(down the document tree)
fields: {}, // additional document fields
fromCache: boolean, // cache or generated output
id: int, // document id
idx: int, // document menuindex
lvl: int, // depth level of the document
prevId: int, // previous document id
prevIdx: int, // previous document menuindex
prevLvl: int, // previous document depth level
status: int, // HTTP status code of response; 200 - OK, 404 - not found, 301 - moved for references
treePath: [] // array of ids from root as '0' to current document id
}
Plugins that invoked on "OnPageUnauthorized" and "OnPageNotFound" events must set to event output id of document to load forward. In this events use $asyncDocs->isAjax() to determine that this is ajax page request.
Example:
// some code here that determine id of the landing document and setting $_REQUEST vars
// landingDocId is defined and this is ajax request than return
// to AsyncDocs plugin id of landing document to load
if ($landingDocId && $asyncDocs instanceof AsyncDocs && $asyncDocs->isAjax()) {
$modx->event->output($landingDocId);
$modx->event->stopPropagation();
}
// landingDocId is defined, not ajax
elseif ($landingDocId) {
$modx->sendForward($landingDocId);
}