jQuery for CMSimple

A little CMSimple-System-Plugin which includes jQuery and jQueryUI to a CMSimple installation and make the libraries available to use with other CMSimple-Plugins.

Version 1.3.1 - 2011-09-30
© 2011 Holger Irmler, http://CMSimple.HolgerIrmler.de.

1. Installation
2. Developers View
   1. How to use:
   2. Using other jQuery-based plugins / extensions
   3. Complete code-example:
   4. Where and how to put your own code?
   5. Other things to know...
3. Desingers View
4. Advanced Usage
5. Licenses
6. Need help?

Installation

1. Always make a backup of your installation before adding a new plugin.
2. Unzip the archive and upload the files and folders into your plugins-folder.

   It should look like this:

   • [Root]
     • [2lang]
     • [cmsimple]
     • ...
     • [plugins]
       • ...
       • [pluginloader]
       • [jquery]
         • [config]
         • [lib]
         • admin.php
         • index.php
         • jquery.inc.php
       • index.php
     • [...]
     • index.php

The file plugins/jquery/config/config.php needs to be set writeable.

3. You're done!
   There is no need to activate something somewhere, since the plugin is normally only used and activated
   by other plugins or by itself. So if your intended use is just running another plugin which need jQuery for CMSimple, don't bother with reading the rest of this document.

Note: if you're really familiar with jQuery / jQuery UI and you want to use it without other CMSimple-Plugins too, have a look at the "Advanced Usage" chapter.

Developers View

If you develop a CMSimple plugin, which makes use of jQuery or jQuery UI, you have to be sure to have the libraries proper loaded before you run your own script code. A common way in the past was to include the library core by the plugin function itself.
But that caused a lot of problems with other plugins, like other library-versions, loaded at the same page.
In some cases all js-code on a page was dropped by js-errors.

You're advised to use only this plugin together with all your jQuery based plugins for CMSimple from now!

How to use:

The plugin provides a few basic functions, contained in an include-file. Have a look at the basic code example below:

As you can see, there are just a few necessary steps to include jQuery & jQuery UI to your own plugin:

1. perform a little error-check and drop your plugin if jQuery for CMSimple is not available (Line 06 - 16)
2. include the jquery.inc.php (Line 20)
   You must use "include_once" for inclusion, otherwise the script will break with a fatal-error, if another plugin has included the file already
3. activate jQuery by calling the function include_jQuery() (Line 23)
4. activate jQuery UI by calling the function include_jQueryUI() (Line 26)

Everything else is done and controlled by jQuery for CMSimple.

You may put your error-message inside a container with the class-selector "cmsimplecore_warning", to get the output formatted like other warnings in CMSimple_XH. If you'll be perfect, add your error-message to your plugins $tx-array and provide localized texts for the users.

Beside this, you should mention the dependency of your plugin to jQuery for CMSimple somewhere in your documentation and on your download-page. But do not include the jQuery for CMSimple - Plugin to your own download archive.

Using other jQuery-based plugins / extensions

There are a lot of ready to run jQuery-based plugins available on the web. A good starting-point for an overview can be found at http://plugins.jquery.com/.
Using those plugins in your own code may conflict with other CMSimple-Plugins, loading the same extension.
For this purposes, a third function comes with jQuery for CMSimple:
where $name is the name of the jQuery-plugin and $path ist the full path and filename of the js-file to load.
The jQuery for CMSimple - Plugin does not provide single jQuery-plugins in the download (beside jQuery UI). If you want to use an additional extension, put it to your own download.
So as an example, let's say your script needs the jQuery-plugins easing and mousewheel.
You need to include two additional lines to your plugin-code:
Note: to be as much compatible as possible with other CMSimple-plugins, use only the real-name of the jQuery-plugin for the $name-parameter when calling the include_jQueryPlugin() - function:
use "easing" and not "easing-1.3" etc. for $name.
jQuery for CMSimple will remember the given name ($name) of every included plugin. If the extension of your choice is already available, it will not include it again.

If you want to have a look at runtime, the names are stored in the $jQueryPlugins - Array.

Complete code-example:

Where and how to put your own code?

To include your own code, use the common CMSimple-way:

If your script goes to the <head> - section, use $hjs:
If you need to put your code inside the content, do it the same way but use $o variable:

With jQuery4CMSimple, jQuery will always the first loaded JS-Library.
That makes it easy to use other Frameworks, using the $ shorthand, together with jQuery.
To write your code as much compatible as possible

• don't use '$' - use jQuery() or (function($) { /* your code in here might use $() */ })(jQuery))
• don't use jQuerys noConflict() in your plugins
• use the " .= " operator to append non-jQuery-libraries on right side of $hjs
• include other frameworks in the template always after the line "<?php echo head();?>"

For more informations refer to the "Including jQuery before Other Libraries" chapter at the
jQuery-Documentation or have a look at the discussion at the Forum.

Other things to know...

The plugin comes with a few more features which are maybe useful for developers:

To check the compatibility of your own code
with different jQuery or jQueryUI versions, you can call the include - functions with the path to the libraries:
You can use a local or an external path like in the example. Do it for jQueryUI the same way. But use this feature only in your development environment. Do not deliver your plugin with a path to a special library-version. Your releases must always come without a parameter in the function-call.


How to find out which version of jQuery / jQueryUI is installed:
We will keep the plugin up to date and provide from time to time a new download with new stable versions of the libraries.

You see the available jQuery versions in the CMS Configuration in a selectbox, there you can choose the version of your choice.

Desingers View

With jQuery for CMSimple another framework become available: jQuery UI.
jQuery UI consists of a number of predefined effects, UI widgets and a powerful css-based theme framework.
This plugin includes jQuery UI with a default, light grey styled theme (the smoothness theme).
As a designer you have the chance to provide a complete own theme , adapted to your template-styles, or a stylesheet-file with single class-selectors to overwrite settings from the default theme.
Check the jQuery UI - Themeroller to create your own design from scratch or select a theme from the gallery and customize it.

To "activate" your theme-settings, just create a subfolder named "jquery_ui" inside your template-folder.
To provide a full ui-theme, put a file namened "jquery_ui.css" inside this folder (but remember: this way, you have to provide a full ui-theme - maybe with an images-subfolder. The default theme will not be available!).

If you only want to overwrite single class-definitions, create a file named "stylesheet.css" in the "jquery_ui" - folder. Here, the default theme will be available and the definitions in your stylesheet.css will overwrite the contents of the default theme. 

Advanced Usage

If you're familiar with jQuery / jQuery UI and want to use it with the WYSIWYG - Editor, you can include jQuery and jQuery UI by default to your page - <head>, without a installation of another plugin or changing your template. Just set the configuration option "autoload" to "1" and the libraries will be available.

Licenses

• jQuery:
  Copyright 2011, John Resig
  dual licensed under the MIT or GPL Version 2 licenses
  see http://jquery.org/license
• jQueryUI:
  Copyright 2011, AUTHORS.txt (http://jqueryui.com/about)
  dual licensed under the MIT or GPL Version 2 licenses
  see http://jquery.org/license & http://docs.jquery.com/UI
  
• jQuery for CMSimple:
  Copyright 2011, Holger Irmler
  licensed under the GPL Version 2 or later of your choice

Need help?

... visit cmsimpleforum.com.

 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED 
 IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
 THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.