What does this do?

This provides Ajax functionality to the frontend.
(Similar to xajax_tools but without any framework)


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() and ajax_tools.loadURL() that may process all your ajax requests.


Plugin parameters:

    (boolean) init (optional)
        Set to true if this is the initial call. (recommended in the <head> section of your template)

    Parameters if init=true...
        (csv) actions (optional)
            A comma separated list of allowed actions. (module, plugin, udt, ... more to come ... )
            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.


    (string) lazy_load (optional)
        This is still experimental so don't expect it to be a killer feature ;)
        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 add an onclick event to the body.
        Every link that is clicked will now get an additional parameter in its href attribute (js=1).
        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 parameter js=1 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 followed a link with the parameter js=1.
        In this case the plugin shows a link to the same page again but without the parameter js=1 and trys to do a redirect with a <meta> refresh tag.

    (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) 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.


Usage of the javascript function ajax_tools.load():

ajax_tools.load(action, callBack, responseType, 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 an 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)'
        }


    (function) callBack (optional)
        A javascript callback function

    (string) responseType (optional)
        set to xml to get an xml response

    (boolean) debug (optional)
        If set to true this will print out some informations 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.
        This function expects the params to be an array that contains at least one index 'module' that contains the name of the module to process:

        {
        	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.
        This action expects the params to be an array that contains at least one index 'plugin' that contains the name of the plugin to process:

        {
        	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:

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


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

        {
        	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',
        		...
        	}
        }



Usage of the javascript function ajax_tools.loadURL():

ajax_tools.loadURL(url, callBack, responseType, 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 ...


Example usage:

<head>
	...
	{ajax_tools init=true}
</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>
	...
	{ajax_tools lazy_load="module" module="News" queue="left_items"}
	...
</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, 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.