Play! Documentation

play.js

The play/resource/play.js javascript file provides some handy, easy-to-use functionality in two forms: special classes that automatically trigger javascript when detected, and a handful of very useful functions for using ajax to load content.

The Play Library's javascript features require jQuery. JQuery is a free, javascript library that can be included directly from google's site and operates behind the scenes without your intervention. The default web content includes jQuery in this way.

Play Library javascript is intended strictly to enhance the operation of PHP features. There is no PHP feature that will fail to operate in the absense of javascript. There are also many javascript features that serve to enhance user experience and reduce server load, but if implemented properly the absence of javascript will not be noticeably visible.

Classes

This section lists HTML Classes that automatically trigger useful javascript features when jQuery and the play.js script are included in the HTML head section:

• xShowIfJS

  This class should be paired with style="display:none;" to make sure that the tag's contents are only visible if javascript is enabled. This is useful for showing buttons and other content that implement pure javascript functionality as an enhancement.

• xHideIfJS

  Automatically hide this tag's contents if javascript is present. This is useful for hiding content that should not be seen initially in browsers that have javascript enabled.

• xFocus

  Automatically give focus to the first form field found containing this class.

• xSelectAll

  Automatically select all text in any text field found containing this class. Usually most practically used with xFocus to make it convenient for users to simply begin typing when the web page loads, rather than having to click in the text field and select all text before typing.

• xToggle

  Sets the specified node so that when clicked, the next sibling will toggle between visible and invisible. It's a good idea to pair this class action with xShowIfJS and style="display:none;" so that this control will not be visible unless JavaScript is available to make it work.

  The xHideIfJS class is a convenient way to hide the next sibling only if it should start out hidden. That way, it's content is not lost if javascript is not available to enable the control that would toggle it.

Functions

This section lists javascript functions implemented in the play.js file.

• ajax
  play.ajax(target, parameters)

  Replaces the content of the HTML node identified by the "target" argument with the response content of an ajax call. If target is a form, the form method and action are used to determine defaults for the ajax call. If form is specified in the parameters array, that form's method and action are used. If url and/or method are specified in parameters, those take precedent.

  If a template or plugin key is specified in the parameters array, the special play paramater __template or __plugin is prepended to the request, indicating that the named template or plugin should be used to handle the request.

• src
  play.src(target, parameters)

  Replaces the src attribute of the "target" HTML node with a url determined by a variety of parameter combinations.

  1. If a url key is specified in parameters, that will be the default script pathname for the src url. Otherwise, the current window.location.pathname is assumed. NOTE: url must NOT include a '?' character. Any query string must be specified in other parameters.
  2. If a query key is specified, that will be the default "search" query string in the generated url. Do Not prefix your query string with a '?' character.
  3. If a plugin key is specified in the parameters array, the special play paramater __plugin is prepended to the request query, indicating that the named plugin should be used to handle the request.