What does this do?

This provides Ajax functionality to the frontend.


How is it used?

Copy the file function.ajax_tools.php to your /plugins/ directory.
Make sure you have access to the file directly from the browser.
Example .htaccess file for your plugins directory:

# To deny PHPs
<Files ~ "\.(php|php3|php4|php5|phtml|pl|cgi)$">
	order deny,allow
	deny from all
</Files>

# To allow ajax_tools
<Files "function.ajax_tools.php"> 
	order allow,deny
	allow from all
</Files>

Simply insert {ajax_tools [params]} anywhere in your page template.
This prints out some javascript. The javascript provides an object named ajax_tools with various functions that may help you to do an ajax request.
Most important functions are ajax_tools.load(), ajax_tools.loadURL() and ajax_tools.submitForm() that may process all your ajax requests.


Plugin parameters:

	(boolean) init (deprecated)

		use param plugin_action instead

	(string) plugin_action (optional)

		This is the action the plugin will perform. Set to init or skip this param if this is the initial call. (recommended in the <head> section of your template)
		Possible values are init, module, plugin, udt.
		The actions module, plugin and udt will do exactly the same like the standard module, plugin or udt calls but with the ability to cache the results in a static file.
		(see param cache for more details)
		Note: this will not work with the param lazy_load!

	Parameters if plugin_action='init' ...

			(csv) actions (optional)

				A comma separated list of allowed actions. (module, plugin, udt, event, clear_ajax_tools_cache)
				If empty all available plugin actions may be called.

			(csv) modules (optional)

				A comma separated list of allowed modules.
				If empty all available modules with frontend actions may be processed.

			(csv) plugins (optional)

				A comma separated list of allowed plugins.
				If empty all available plugins may be processed.
				Make sure you only allow/create plugins that are as secure as possible to be used in frontend!

			(csv) udts (optional)

				A comma separated list of allowed udts.
				Due to security this plugin will not process all available udts but only those where the name of the udt starts with a certain prefix.
				The prefix can be set with the param udt_prefix.
				You must not specify the prefix in the udt list.
				So if empty all available udts with a certain prefix may be processed.
				Make sure you only allow/create udts that are as secure as possible to be used in frontend!

			(string) udt_prefix (optional)

				A prefix for the name of all udts that may be processed via ajax requests in frontend.
				Default is 'ajax_tools_'

			(csv) events (optional)

				A comma separated list of allowed events.
				If empty all available events may be processed.
				Make sure you only allow events that are as secure as possible to be used in frontend!

			(csv) originators (optional)

				A comma separated list of allowed originators that may trigger an event.
				If empty all available originators may be used.
				Make sure you only allow originatos you want to allow to trigger events in frontend!

			(boolean) debug (optional)

				Set to true for debugging

			(boolean) no_js (optional)

				Set to true to supress the javascript output.
				Useful when using other js libaries such as jQuery etc.

			(csv) db_tables (optional)

				A comma separated list of allowed modules table names that may be queried via ajax requests. (no db prefix and no module_ prefix required)
				default is content, content_props, htmlblobs
				Note: this will only work with the default table names and module tables. You cannot query any other cms table.
				Make sure to grant access only to tables without sensitive data!


	Parameters ...

	(string) lazy_load (optional)

		This param will perform a 'lazy loading' of an ajax_tools plugin action.
		Enter the name of the action here and ajax_tools will load the action as soon as the window.onload event is triggered.
		Example: {ajax_tools lazy_load="module" module="News" number=3 ... any further valid module param here}
		Obviously this will only work if the client has javascript enabled.
		To check if js is available the plugin will set a cookie.
		So the plugin can determine if it will perform a lazy loading or not.
		If not it will display the module/plugin/udt etc. instantly as if you would have called it in your template directly.
		This means if a visitor loads your page the very first time he won't benefit from any lazy loading since the cookie is missing.
		To force lazy loading you can use the parameter force_lazy_load=true.
		If no javascript is enabled a message will be shown within a <noscript> tag.
		If force_lazy_load is not used or set to false the only possible way the user got here is because he has turned off javascript after his first visit so the cookie to check for js exists and will trigger the lazy loading.
		In this case the plugin shows a link to the same page again but with the parameter noscript=1 (and simultanously trys to do a redirect with a <meta> refresh tag to that url).
		The cookie will now be destroyed and the user is able to browse the page without javascript.
		Note: this will always override the param plugin_action!

	(string) noscript_message (optional)

		This is the message that will be displayed in case of lazy loading but with no javascript enabled.
		(can be any kind of text/html)

	(string) nosession_message (optional)

		This is the message that will be displayed in case of the session has expired.
		(can be any kind of text/html)

	(string) wrapper_id (optional)

		This is the css id of the wrapper where the lazy loaded result will be displayed.
		Default is "ajax_tools_lazyload_" followed by an auto increased number.

	(string) wrapper_class (optional)

		This is an additional css class of the wrapper where the lazy loaded result will be displayed.
		Default is "ajax_tools_lazyload_wrapper".

	(boolean) force_lazy_load (optional)

		Set to true to force lazy loading no matter if we now if js is available or not.
		(Will constantly fail if no js is available)

	(string) queue (optional)

		Enter an ID here to combine multiple lazy loading actions into one single request.
		Otherwise each lazy loading action will perform an individual request.

	(int) cache (optional)

		cache lifetime in seconds to cache the result in a static file.
		can also be used if plugin_action=init to set this as a global value for all {ajax_tools} plugin calls.

	(int) cache_relation (optional)

		where to start to count the cache lifetime? by default it will compare the given lifetime to the file creation date of the static file.
		since you never know when the file will be created you cannot update the cached file in a certain cycle.
		this is where you need some kind of relation the cache lifetime belongs to.
		Possible values are:
		day (wich will start counting from the beginning of the current day),
		hour ( ... starts from the current hour),
		min ( ... current minute),
		month ( ... month),
		year ( ... got it?)

	(boolean) log_requests (optional)

		use this to log each ajax request in a log file.
		location will be /uploads/ajax_tools_logs/[date].
		logfile contains information about incomming data and cache usage

	(string) assign (optional)

		use this to assign the result to smarty instead of printing it out.


Usage of the javascript function ajax_tools.load():

ajax_tools.load(action, callBack, responseType, method, debug)

	(mixed) action (required)

		This is the serverside plugin action you want to process.
		This can be an object or an array with multiple objects.

		Example:

		ajax_tools.load(['module','plugin', ... ], further arguments)
		ajax_tools.load({action: 'module', params: {...} }, further arguments)
		ajax_tools.load([{action: 'module', params: {...} },{action: 'plugin', params: {...} }, ... ], further arguments)

		If you pass a js object as argument it will be handled like an associative array.
		The action object consists of the following options:

		{
			action:		'The name of the action (string - required)',
			params:		'The action params (string, array, object - optional but may be required for certain actions)',
			result_id:	 'The id of that action to identify it (only useful if an xml response is requested)',
			cache:		 see plugin params,
			cacheRelation: see plugin params
		}


	(function) callBack (optional)

		A javascript callback function

	(string) responseType (optional)

		set to xml to get an xml response

	(string) method (optional)

		The request methods. Possible values are get/post (default is get)

	(boolean) debug (optional)

		If set to true this will print out some information in javascript error console (if exists)
		Default depends on your serverside CMSms config settings


Available actions:

	module

		This action performs any kind of action of a CMSms module.
		It expects the params to be an array that contains at least one index 'module' that contains the name of the module to process:

		params : {
			module: 'Name of the module (required)',
			params: {
				action: 'Action of the module (optional - default is the default module action)',
				any_valid_module_param: 'any valid value',
				...
			}
		}


	plugin

		This action processes any plugin that is allowed to be processed.
		It expects the params to be an array that contains at least one index 'plugin' that contains the name of the plugin to process:

		params: {
			plugin: 'Name of the plugin (required)',
			params: {
				any_valid_plugin_param: 'any valid value',
				...
			}
		}


	udt

		This action processes any allowed udt that is prefixed with a certain value.
		You must not specify the prefix when calling the ajax_tools javascript function in frontend!
		It is recommended to hide the prefix from the public!
		This action expects the params to be an array that contains at least one index 'udt' that contains the name of the udt to process:

		params: {
			plugin: 'Name of the udt (required - no udt prefix here!)',
			params: {
				any_valid_udt_param: 'any valid value',
				...
			}
		}


	event

		This action triggers any allowed CMSms event.
		This is still experimental so use with caution!
		This action expects the params to be an array:

		params: {
			event: 'Name of the event (optional - default is the pseudo event ajax_tools_event)',
			originator: 'The name of the instance that shall trigger the event (optional - default is the pseudo instance ajax_tools)'
			params: {
				any_valid_param: 'any valid value',
				...
			}
		}


	clear_ajax_tools_cache

		This action clears the static cache of ajax_tools.
		You can clear the whole cache or only the cache of one or more certain action(s)!
		This action expects the params to be a string or an array of strings.
		The string is a path relative to the ajax_tools cache dir
		If empty the whole ajax_tools cache is cleared.
		The path consists of one action name and the corresponding module, plugin name or whatever the action is able to process.
		Example (to clear the cache of the News module):

		params: 'module/News'

		Example (to clear the cache of the plugin {global_content}):

		params: 'plugin/global_content'

		Example (to clear the cache of all modules):

		params: 'module'

		Example (to clear the cache of the News module and all udts):

		params: ['module/News','udt']


	clear_cms_cache

		This action clears the whole cache of the cms.


	get_data

		This action is still experimental and should be used with caution.
		This action gets some data of the database.
		You can only query those db tables that are defined with the param db_tables on the plugin initialization.
		That means you can only get content of pages, global content blocks and modules.
		The action will return xml-like data that looks like this:

		<entry>
			<column name> value </column name>
		</entry>

		It is recommended to use this only in conjunction with response type set to xml.
		This action expects the params to be an array:

		params: {
			get_data: 'Name of the table (required - no db prefix nor the 'module_' prefix here)',
			fields: [
				an array of column names to get the data from (optional - if empty all columns will be returned)
				this is corresponding to the SELECT clause of the db query
			],
			keys: [
				an array of data where a column should match to
				this is corresponding to the WHERE clause of the db query
				a key is an object that consists of four properties: the column name, the value, the operator and the type. 
				Type means 'or' or 'and' to specify if an entry should match all or any of the given keys.
				The operator can be 'eq' (=), 'neq'(!=), 'gt' (>), 'lt' (<), in (IN), nin (NOT IN)
				Default is =
				For more complex db operations you should write a plugin and call the plugin via ajax_tools
				Example objects:
				{name:'title', value:'Foo', type:'or'},
				{name:'title', value:'Bar', type:'or'},
				{name:'id', value:'10', type:'AND', operator:'gt'}
				which would result in a sql statement like this ... WHERE `id` > '10' AND (`title` = 'Foo' OR `title` = 'Bar')
			],
			limit: integer value of how many entrys should be returned (optional) - this is the LIMIT clause of the db query,
			order_by: the column name to sort the results (optional) - this is the ORDER BY clause of the db query
		}



Usage of the javascript function ajax_tools.loadURL():

ajax_tools.loadURL(url, callBack, cache, cacheRelation, responseType, resultId, method, debug)

	(string) url (required)

		The url to be loaded.
		Note: this only works with module URLs such as index.php?mact=News,cntnt01,default,1 ...



Usage of the javascript function ajax_tools.submitForm():

ajax_tools.submitForm(form, callBack, cache, cacheRelation, responseType, resultId, method, debug)

	(string|object) form (required)
		The form id or the html form element itself that will be submitted.



Usage of the javascript function ajax_tools.extend():

ajax_tools.extend(name, value)

	(string) name (required)
		The name of the variable you want to add to the ajax_tools object.

	(mixed) value (required)
		The value of the variable you want to add to the ajax_tools object.
		Can be even objects or functions.



Example usage:

<head>
	...
	{ajax_tools actions='module' modules='News,CGCalendar,CGBlog,Gallery'}
</head>
<body>
	...
	<label for="toggle_news">Toggle the News Module: </label>
	<input id="toggle_news" name="toggle_news" type="checkbox" value="1" onchange="if(this.checked){ ajax_tools.load({action:'module', params: {module: 'News', params:{articleid:-1,action:'detail'}}}, function(result){document.getElementById('news_container').innerHTML = result}) } else { document.getElementById('news_container').innerHTML = 'This is where the news will be loaded into';}" />
	<div id="news_container">This is where the news will be loaded into</div>
	...
	<div id="left">
		{ajax_tools lazy_load="module" module="News" queue="left_items"}
		{ajax_tools lazy_load="module" module="CGCalendar" queue="left_items"}
	</div>
	<div id="right">
		{ajax_tools lazy_load="module" module="CGBlog" queue="right_items" cache=3600}
		{ajax_tools lazy_load="module" module="Gallery" queue="right_items" cache=86400}
	</div>
	...
</body>


Support

This plugin does not include commercial support. However, there are a number of resources available to help you with it:

	The projects homepage is http://dev.cmsmadesimple.org/projects/ajax_tools/
	Additional discussion of this plugin may also be found in the CMS Made Simple Forums:
	http://forum.cmsmadesimple.de
	http://forum.cmsmadesimple.org


Please report any kind of feedback.


Copyright and License

As per the GPL, this software is provided as-is.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Or read it online: http://www.gnu.org/licenses/licenses.html#GPL
Please read the text of the license for the full disclaimer.

Copyright (c) 2011-2012, Georg Busch (NaN). All Rights Are Reserved.

This plugin has been released under the GNU Public License. You must agree to this license before using the plugin.