<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>jQuery for CMSimple :: Help</title>


  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

  <style>
html, body {
margin: 0;
padding: 0;
}
body {
font-family: verdana, arial, sans-serif;
background-color: #e2e2e2;
text-align: center;
font-size: 0.9em;
line-height: 1.3;
}
.additional{
font-size: 90%;
color: #666;
line-height: 1.1;
}
p.code {font-family: Courier New; border: 1px solid #999; background: #eed; padding: 8px 12px;}
  </style>
  <script type="text/javascript" src="sh/scripts/shCore.js"></script>
  <script type="text/javascript" src="sh/scripts/shBrushPhp.js"></script>
  <link type="text/css" rel="stylesheet" href="sh/styles/shCore.css">

  <link type="text/css" rel="stylesheet" href="sh/styles/shThemeDefault.css">

  <script type="text/javascript">
SyntaxHighlighter.config.clipboardSwf = 'sh/scripts/clipboard.swf';
SyntaxHighlighter.all();
  </script>
</head>


<body>

<div style="border: 1px solid rgb(187, 187, 187); margin: 0px auto auto; padding: 0pt 3em; text-align: left; width: 780px; background-color: rgb(255, 255, 255);">
<a target="_blank" href="http://jquery.com/"><img style="border: 0px solid ; width: 420px; height: 104px; float: right;" alt="" src="jQuery_logo_color_onwhite.png" vspace="20"></a><a target="_blank" href="http://jqueryui.com/"><img style="border: 0px solid ; width: 448px; height: 108px; float: right;" alt="" src="jQuery__UI_logo_color_onwhite.png" vspace="10"></a>
<h1><a class="mozTocH1" name="mozTocId902206"></a>jQuery
for CMSimple<br>

</h1>

<p>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. </p>

<p class="additional">Version 1.3.1 - 2011-09-30<br>

<span class="additional">
&copy; 2011 Holger Irmler, </span><a class="additional" target="_blank" href="http://cmsimple.holgerirmler.de">http://CMSimple.HolgerIrmler.de</a><span class="additional">.<br>

</span></p>

<br>

<br>

<ol id="mozToc">
<!--mozToc h2 1 h3 2 h4 3--><li><a href="#mozTocId43365">Installation</a></li>
  <li><a href="#mozTocId153175">Developers
View</a>
    <ol>
      <li><a href="#mozTocId683226">How
to use:</a></li>
      <li><a href="#mozTocId206541">Using
other jQuery-based plugins / extensions</a></li>
      <li><a href="#mozTocId686597">Complete
code-example:
        </a></li>
      <li><a href="#mozTocId335378">
Where and how to put your own code?</a></li>
      <li><a href="#mozTocId191578">Other
things to know...</a></li>
    </ol>
  </li>
  <li><a href="#mozTocId602111">Desingers
View</a></li>
  <li><a href="#mozTocId830415">Advanced Usage</a></li>
  <li><a href="#mozTocId160751">Licenses</a></li>
  <li><a href="#mozTocId753693">Need
help?</a></li>
</ol>

<br>

<h2><a class="mozTocH2" name="mozTocId43365"></a>Installation</h2>

<ol>

  <li> <b>Always make a backup of your installation</b>
before adding a new plugin. </li>

  <li>Unzip the archive and upload the files and folders into
your
plugins-folder. <span class="additional">
    <p>It should look like this: </p>

    <ul>

      <li>[Root]
        <ul>

          <li>[2lang]</li>

          <li>[cmsimple]</li>

          <li>...</li>

          <li>[plugins]
            <ul>

              <li>...</li>

              <li>[pluginloader]</li>

              <li><b>[jquery]</b>
                <ul>

                  <li><b>[config]</b></li>

                  <li><span class="additional"><b>[lib]</b></span></li>

                  <li>admin.php</li>

                  <li>index.php</li>

                  <li>jquery.inc.php</li>

                </ul>

              </li>

              <li>index.php</li>

            </ul>

          </li>

          <li>[...]</li>

          <li>index.php</li>

        </ul>

      </li>

    </ul>

    </span> </li>

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

  <li><span style="font-weight: bold;">You're done! </span><br>

There is no need to activate something&nbsp;somewhere, since the
plugin is normally only used and activated <br>

by other plugins or by itself.&nbsp;So if&nbsp;your intended
use is just running another plugin which need
jQuery for CMSimple, don't bother with reading the rest of this
document.</li>

</ol>

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 "<a href="#Advanced_Usage">Advanced Usage</a>"
chapter.<br>

<div style="text-align: right;"><a href="#mozToc">Back
to toc</a><br>

</div>

<h2><a class="mozTocH2" name="mozTocId153175"></a>Developers
View</h2>

If you develop a CMSimple plugin, which makes use of jQuery&nbsp;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. <br>

But that caused a lot of problems with other plugins, like other
library-versions, loaded at the same page.<br>

In some cases all js-code on a page was dropped by&nbsp;js-errors.<br>

<br>

<span style="font-weight: bold;">You're advised <span style="text-decoration: underline;">to use only this plugin</span>
together with all your jQuery based plugins
for CMSimple from now!</span><br>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<h3><a class="mozTocH3" name="mozTocId683226"></a>How
to use:</h3>

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

</ol>


<script type="syntaxhighlighter" class="brush: php"><![CDATA[
<?php

function myplugin(){
	global $pth, $cf; //be sure CMSimple variables are accessible in your function

	$jqerror = '';
	if(!file_exists($pth['folder']['plugins'].'jquery/jquery.inc.php')){
		$jqerror = '<div class="cmsimplecore_warning">'.
				   '<b>Ups!</b>'.tag('br').
				   'Plugin '.ucfirst(basename(dirname(__FILE__))).
				   ' requires jQuery4CMSimple - Plugin!'.tag('br').
				   'Please download and install jQuery4CMSimple'.tag('br').
				   'from <a href='.
				   '"http://cmsimple-xh.com/wiki/doku.php/plugins:jquery4cmsimple">'.
				   ' www.cmsimple-xh.com/wiki</a>.'.
				   '</div>';
		//drop the rest of the plugin-code
		return($jqerror);
	} else {
	//load include-file from jQuery-plugin
	//always use "include_once"!
	include_once($pth['folder']['plugins'].'jquery/jquery.inc.php'); 

	//include jQuery to the <head>
	include_jQuery();

	//include jQuery UI to the <head>, if you use it in your plugin
	include_jQueryUI();

	//....
	//your other code ...
	//....
	
	}
}

?>
]]></script>
<br>

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

<ol>

  <li>perform a little error-check and drop your plugin if jQuery
for CMSimple is not available (Line 06 - 16)</li>

  <li>include the jquery.inc.php (Line 20)<br>

    <span class="additional">You must use "include_<span style="font-weight: bold;">once</span>"
for inclusion, otherwise the script will break with a fatal-error, if
another plugin has included the file already</span></li>

  <li>activate jQuery by calling the function include_jQuery() (Line 23)</li>

  <li>activate jQuery UI by calling the function include_jQueryUI() (Line 26)</li>

</ol>

Everything else is done and controlled by jQuery for CMSimple.<br>

<br>

You may put your error-message inside a container with
the&nbsp;class-selector "<span style="font-style: italic;">cmsimplecore_warning</span>",
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.<br>

<br>

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.<br>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<h3><a class="mozTocH3" name="mozTocId206541"></a>Using
other jQuery-based plugins / extensions</h3>

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 <a href="http://plugins.jquery.com/" target="_blank">http://plugins.jquery.com/</a>.<br>

Using those plugins in your own code may conflict with other
CMSimple-Plugins, loading the same extension.<br>

For this purposes, a third function comes with jQuery for CMSimple:<br>

<script type="syntaxhighlighter" class="brush: php"><![CDATA[
include_jQueryPlugin($name, $path)
]]></script>


where $name is the name of the jQuery-plugin and $path ist the full
path and filename of the js-file to load.<br>

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.<br>

So as an example, let's say your script needs&nbsp;the
jQuery-plugins <span style="font-style: italic;">easing</span>
and&nbsp;<span style="font-style: italic;">mousewheel</span>.<br>

You need to include two additional lines to your plugin-code:<br>

<script type="syntaxhighlighter" class="brush: php"><![CDATA[
<?php

include_jQueryPlugin('easing',
	$pth['folder']['plugins'].'myplugin/jquery.easing-1.3.pack.js');

include_jQueryPlugin('mousewheel',
	$pth['folder']['plugins'].'myplugin/jquery.mousewheel-3.0.4.pack.js');

?>
]]></script>

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:<br>
use "<span style="font-style: italic; font-weight: bold;">easing</span>"
<span style="text-decoration: underline;">and not</span><span style="font-weight: bold;"> </span>"<span style="font-style: italic; font-weight: bold;">easing-1.3</span>"
etc. for $name.<br>

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.<br>

<br>

If you want to have a look at runtime, the names are stored in
the <span style="font-style: italic;">$jQueryPlugins</span>
- Array.<br>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<h3><a class="mozTocH3" name="mozTocId686597"></a>Complete
code-example:<br>

</h3>

<script type="syntaxhighlighter" class="brush: php"><![CDATA[
<?php

function myplugin(){
	global $pth, $cf; //be sure CMSimple variables are accessible in your function

	$jqerror ='';
	if(!file_exists($pth['folder']['plugins'].'jquery/jquery.inc.php')){
		$jqerror = '<div class="cmsimplecore_warning">'.
				   '<b>Ups!</b>'.tag('br').
				   'Plugin '.ucfirst(basename(dirname(__FILE__))).
				   ' requires jQuery4CMSimple - Plugin!'.tag('br').
				   'Please download and install jQuery4CMSimple'.tag('br').
				   'from <a href='.
				   '"http://cmsimple-xh.com/wiki/doku.php/plugins:jquery4cmsimple">'.
				   ' www.cmsimple-xh.com/wiki</a>.'.
				   '</div>';
		//drop the rest of the plugin-code
		return($jqerror);
	} else {
	//load inculde-file from jQuery-plugin
	//always use "include_once"!
	include_once($pth['folder']['plugins'].'jquery/jquery.inc.php'); 

	//include jQuery to the <head>
	include_jQuery();

	//include jQuery UI to the <head>, if you use it in your plugin
	include_jQueryUI();
	
	//include other jQuery plugins
	include_jQueryPlugin('easing',
		$pth['folder']['plugins'].'myplugin/jquery.easing-1.3.pack.js');
	include_jQueryPlugin('mousewheel',
		$pth['folder']['plugins'].'myplugin/jquery.mousewheel-3.0.4.pack.js');

	//....
	//your other code ...
	//....
	
	}
}

?>
]]></script>


<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<h3><a class="mozTocH3" name="mozTocId335378"></a>
Where and how to put your own code?</h3>

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

<br>

If your script goes to the &lt;head&gt; - section, use <span style="font-weight: bold;">$hjs</span>:<br>
<script type="syntaxhighlighter" class="brush: php"><![CDATA[
$hjs .= '<script type="text/javascript">
	        jQuery(document).ready(function(){...});
         &lt;/script>';
]]></script>

If you need to put your code inside the content, do it the same way but
use <span style="font-weight: bold;">$o</span>
variable:<br>
<script type="syntaxhighlighter" class="brush: php"><![CDATA[
$o .= '<script type="text/javascript">
	      jQuery("p.neat").addClass("ohmy").show("slow");
	   &lt;/script>';
]]></script>
<br>

<p>
With jQuery4CMSimple, jQuery will always the first loaded JS-Library.<br>
That makes it easy to use other Frameworks, using the $ shorthand, together with jQuery.<br>
To write your code as much compatible as possible
<ul>
<li>don't use '$' - use jQuery() or (function($) { /* your code in here might use $() */ })(jQuery))</li>
<li>don't use jQuerys noConflict() in your plugins</li>
<li>use the " .= " operator to append non-jQuery-libraries on right side of $hjs</li>
<li>include other frameworks <u>in the template</u> always <u>after</u> the line "&lt;?php echo head();?&gt;"</li>
</ul>
For more informations refer to the  "Including jQuery before Other Libraries" chapter at the<br> 
<a target="_blank" href="http://docs.jquery.com/Using_jQuery_with_Other_Libraries#Including_jQuery_before_Other_Libraries">jQuery-Documentation</a> 
or have a look at the discussion at the <a target="_blank" href="http://www.cmsimpleforum.com/viewtopic.php?f=29&t=3209&st=0&sk=t&sd=a&start=20#p18077">Forum</a>.
</p>

<h3><a class="mozTocH3" name="mozTocId191578"></a>Other
things to know...</h3>

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

<br style="font-weight: bold;">

<span style="font-weight: bold;">To check the
compatibility of your own code</span> <br>

with different jQuery or jQueryUI versions, you can call the include -
functions with the path to the libraries:<br>

<script type="syntaxhighlighter" class="brush: php"><![CDATA[
include_jQuery('http://code.jquery.com/jquery-latest.min.js');
]]></script>

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. <span style="text-decoration: underline;">Do
not deliver your plugin with a path to a special library-version</span>.
Your releases must always come without a parameter in the function-call.<br>

<br>

<br>

<span style="font-weight: bold;">How to find out which
version of jQuery / jQueryUI is installed:</span><br>

We will keep the plugin up to date and provide from time to time a new
download with&nbsp;new stable versions of the libraries.<br>

Anyway, jQuery for CMSimple defines two constants:<br>

<p class="code">define('JQUERY',
$cf['jquery']['version_core']);</p>

<p class="code">define('JQUERY_UI',
$cf['jquery']['version_ui']);</p>

The constants are holding the version of the libraries in a format like
<span style="font-style: italic;">1.6.1</span> for
example. Note that the values come from the $cf - array which
holds the entries&nbsp;in string-format.<br>

You may include some code to make a version-check on your own, if you
really need that.<br>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<h2><a class="mozTocH2" name="mozTocId602111"></a>Desingers
View</h2>

With jQuery for CMSimple another framework become available: <a href="http://jqueryui.com/home" target="_blank">jQuery
UI</a>.<br>

jQuery UI consists of a number of predefined effects, UI widgets and a
powerful css-based theme framework. <br>

This plugin includes jQuery UI with a default, light grey styled theme
(the smoothness theme). <br>

As a designer you have the chance to provide a complete own
theme&nbsp;, adapted to your template-styles, or a stylesheet-file
with single class-selectors to overwrite settings from the default
theme. <br>

Check the jQuery UI - <a href="http://jqueryui.com/themeroller/" target="_blank">Themeroller</a> to create your own
design from scratch or select a theme from the gallery and customize it.<img style="border: 1px solid ; width: 300px; height: 126px; float: right;" alt="" src="ui_cssfolder.PNG" hspace="5" vspace="5"><br>

<br>

To "activate" your theme-settings, just create a subfolder named
"jquery_ui"
inside your template-folder. <br>

To provide a full ui-theme, put a file namened "<span style="font-weight: bold; font-style: italic;">jquery_ui.css</span>"
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!). <br>

<br>

If you only want to overwrite single class-definitions, create a file
named
"<span style="font-weight: bold; font-style: italic;">stylesheet.css</span>"
in the "jquery_ui" - folder. Here, the default theme will be available
and the definitions in your stylesheet.css&nbsp;will overwrite the
contents of the default
theme.&nbsp;<br>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<h2><a class="mozTocH2" name="mozTocId830415"></a><a name="Advanced_Usage"></a>Advanced Usage</h2>

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 -&nbsp;&lt;head&gt;, without a installation of
another plugin
or changing your template. Just set the configuration option "<span style="font-weight: bold;">autoload</span>" to "<span style="font-weight: bold;">1</span>" and the libraries
will be available.<br>

<br>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a><br>

</div>

<ol>

</ol>

<h2><a class="mozTocH2" name="mozTocId160751"></a>Licenses</h2>

<ul>

  <li><span style="font-weight: bold;">jQuery:</span><br>

Copyright 2011, John Resig<br>

dual licensed under the MIT or GPL Version 2 licenses<br>

see http://jquery.org/license</li>

  <li><span style="font-weight: bold;">jQueryUI:</span><br>

Copyright 2011, AUTHORS.txt (http://jqueryui.com/about)<br>

dual licensed under the MIT or GPL Version 2 licenses<br>

see http://jquery.org/license
&amp;&nbsp;http://docs.jquery.com/UI<br>

  </li>

  <li><span style="font-weight: bold;">jQuery for
CMSimple:</span><br>

Copyright 2011, Holger Irmler<br>

licensed under the GPL Version 2 or later of your choice</li>

</ul>

<div style="text-align: right;"><a href="help.htm#mozToc">Back to toc</a>
</div>

<ol>

</ol>

<h2><a class="mozTocH2" name="mozTocId753693"></a>Need
help?</h2>

<p>... visit <a target="_blank" href="http://www.cmsimpleforum.com">cmsimpleforum.com</a>.</p>

<span style="font-weight: bold;">
<br>

</span>
<pre style="font-weight: bold; line-height: 1.2em; font-size: 90%; color: rgb(102, 102, 102);"> THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED <br> IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,<br> EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS<br> FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD<br> THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.<br> </pre>

</div>

</body>
</html>
