Coppermine Photo Gallery v1.6.x: Documentation and Manual

Javascript in Coppermine

A lot of pages in coppermine uses javascript for client side enhancements and validations. This guide will help developers to understand how javascript is organized in coppermine.

Target audience

This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is.

Javascript files location and organization

• JavaScript in cpg1.5.x is using the jQuery library. For details, please refer to the corresponding credits section of the docs that explains the freeware code used in Coppermine
• All javascript core files reside in your_coppermine_folder/js folder
• your_coppermine_folder/js/scripts.js is the site wide javascript file containg code which is common to most of the pages
• All page specific javascript code goes in your_coppermine_folder/js/pagename.js (Where pagename.php is the page in question).
• Starting from cpg1.5, javascript will be unobtrusive i.e. all javascript will reside in respective .js file and there will be no inline javascript code

TODO

There is still lot of javascript inline with html (from cpg1.4). This javascript needs to be separated into their own files

How to include javascript files

Javascript files can be included from within php code by calling js_include() function.

// This line of code will include displayimage.js file
js_include('js/displayimage.js');

However there is a catch in using this function. This function should be called before the pageheader() function is called. The actual inclusion of javascript files is done in pageheader() function and that is the reason all js inclusion should be done before that.

How to include JavaScript files in plugins

If you need to add a JavaScript file for a plugin, the 'page_start' plugin action might be used.

$thisplugin->add_action('page_start','custom_function_to_include_js');

function custom_function_to_include_js() {
	global $JS; // Don't forget to make that variable global when using from inside functions
	$JS['includes'][] = 'plugins/your_plugin/your_javascript_file.js';
}

Technically, inline JavaScript is possible as well, but not recommended.

How to pass PHP variables to included javascript

If you need to pass dynamic data from PHP code (e.g. a language string that resides in a PHP variable) to the JavaScript code that resides in an external file included with the method explained above, you can use the function set_js_var() that get's defined in include/functions.inc.php.

<?php
$foo = 'bar';
set_js_var('php_foo', $foo);
?>

Keep in i18n in mind, especially for the strings passed from language files: be particularly mindfull on properly escaping single quotes (apostrophes) that may reside in other languages than the one you're testing with.

Autostart JavaScript

In "traditional" JavaScript, there are several methods to make JavaScript code execute when the page is being loaded, using the pageLoad event. This used to cause issues and incompatibilities. With cpg1.5.x using the jQuery library, it has become very straightforward to come up with JavaScript autostarts: every piece of JavaScript code that you want to see executed on page load should use the "document ready" construct: wrap all autostart code into

$(document).ready(function(){

});

The advantage of this method is that jquery will take care of triggering the autostart functions - there can be several of those "document ready" constructs, even in different .js files.