diff options
Diffstat (limited to 'core/misc/drupal.js')
| -rw-r--r-- | core/misc/drupal.js | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/core/misc/drupal.js b/core/misc/drupal.js new file mode 100644 index 00000000000..7ae737c639b --- /dev/null +++ b/core/misc/drupal.js @@ -0,0 +1,412 @@ + +var Drupal = Drupal || { 'settings': {}, 'behaviors': {}, 'locale': {} }; + +// Allow other JavaScript libraries to use $. +jQuery.noConflict(); + +(function ($) { + +/** + * Attach all registered behaviors to a page element. + * + * Behaviors are event-triggered actions that attach to page elements, enhancing + * default non-JavaScript UIs. Behaviors are registered in the Drupal.behaviors + * object using the method 'attach' and optionally also 'detach' as follows: + * @code + * Drupal.behaviors.behaviorName = { + * attach: function (context, settings) { + * ... + * }, + * detach: function (context, settings, trigger) { + * ... + * } + * }; + * @endcode + * + * Drupal.attachBehaviors is added below to the jQuery ready event and so + * runs on initial page load. Developers implementing AHAH/Ajax in their + * solutions should also call this function after new page content has been + * loaded, feeding in an element to be processed, in order to attach all + * behaviors to the new content. + * + * Behaviors should use + * @code + * $(selector).once('behavior-name', function () { + * ... + * }); + * @endcode + * to ensure the behavior is attached only once to a given element. (Doing so + * enables the reprocessing of given elements, which may be needed on occasion + * despite the ability to limit behavior attachment to a particular element.) + * + * @param context + * An element to attach behaviors to. If none is given, the document element + * is used. + * @param settings + * An object containing settings for the current context. If none given, the + * global Drupal.settings object is used. + */ +Drupal.attachBehaviors = function (context, settings) { + context = context || document; + settings = settings || Drupal.settings; + // Execute all of them. + $.each(Drupal.behaviors, function () { + if ($.isFunction(this.attach)) { + this.attach(context, settings); + } + }); +}; + +/** + * Detach registered behaviors from a page element. + * + * Developers implementing AHAH/Ajax in their solutions should call this + * function before page content is about to be removed, feeding in an element + * to be processed, in order to allow special behaviors to detach from the + * content. + * + * Such implementations should look for the class name that was added in their + * corresponding Drupal.behaviors.behaviorName.attach implementation, i.e. + * behaviorName-processed, to ensure the behavior is detached only from + * previously processed elements. + * + * @param context + * An element to detach behaviors from. If none is given, the document element + * is used. + * @param settings + * An object containing settings for the current context. If none given, the + * global Drupal.settings object is used. + * @param trigger + * A string containing what's causing the behaviors to be detached. The + * possible triggers are: + * - unload: (default) The context element is being removed from the DOM. + * - move: The element is about to be moved within the DOM (for example, + * during a tabledrag row swap). After the move is completed, + * Drupal.attachBehaviors() is called, so that the behavior can undo + * whatever it did in response to the move. Many behaviors won't need to + * do anything simply in response to the element being moved, but because + * IFRAME elements reload their "src" when being moved within the DOM, + * behaviors bound to IFRAME elements (like WYSIWYG editors) may need to + * take some action. + * - serialize: When an Ajax form is submitted, this is called with the + * form as the context. This provides every behavior within the form an + * opportunity to ensure that the field elements have correct content + * in them before the form is serialized. The canonical use-case is so + * that WYSIWYG editors can update the hidden textarea to which they are + * bound. + * + * @see Drupal.attachBehaviors + */ +Drupal.detachBehaviors = function (context, settings, trigger) { + context = context || document; + settings = settings || Drupal.settings; + trigger = trigger || 'unload'; + // Execute all of them. + $.each(Drupal.behaviors, function () { + if ($.isFunction(this.detach)) { + this.detach(context, settings, trigger); + } + }); +}; + +/** + * Encode special characters in a plain-text string for display as HTML. + * + * @ingroup sanitization + */ +Drupal.checkPlain = function (str) { + var character, regex, + replace = { '&': '&', '"': '"', '<': '<', '>': '>' }; + str = String(str); + for (character in replace) { + if (replace.hasOwnProperty(character)) { + regex = new RegExp(character, 'g'); + str = str.replace(regex, replace[character]); + } + } + return str; +}; + +/** + * Replace placeholders with sanitized values in a string. + * + * @param str + * A string with placeholders. + * @param args + * An object of replacements pairs to make. Incidences of any key in this + * array are replaced with the corresponding value. Based on the first + * character of the key, the value is escaped and/or themed: + * - !variable: inserted as is + * - @variable: escape plain text to HTML (Drupal.checkPlain) + * - %variable: escape text and theme as a placeholder for user-submitted + * content (checkPlain + Drupal.theme('placeholder')) + * + * @see Drupal.t() + * @ingroup sanitization + */ +Drupal.formatString = function(str, args) { + // Transform arguments before inserting them. + for (var key in args) { + switch (key.charAt(0)) { + // Escaped only. + case '@': + args[key] = Drupal.checkPlain(args[key]); + break; + // Pass-through. + case '!': + break; + // Escaped and placeholder. + case '%': + default: + args[key] = Drupal.theme('placeholder', args[key]); + break; + } + str = str.replace(key, args[key]); + } + return str; +} + +/** + * Translate strings to the page language or a given language. + * + * See the documentation of the server-side t() function for further details. + * + * @param str + * A string containing the English string to translate. + * @param args + * An object of replacements pairs to make after translation. Incidences + * of any key in this array are replaced with the corresponding value. + * See Drupal.formatString(). + * + * @param options + * - 'context' (defaults to the empty context): The context the source string + * belongs to. + * + * @return + * The translated string. + */ +Drupal.t = function (str, args, options) { + options = options || {}; + options.context = options.context || ''; + + // Fetch the localized version of the string. + if (Drupal.locale.strings && Drupal.locale.strings[options.context] && Drupal.locale.strings[options.context][str]) { + str = Drupal.locale.strings[options.context][str]; + } + + if (args) { + str = Drupal.formatString(str, args); + } + return str; +}; + +/** + * Format a string containing a count of items. + * + * This function ensures that the string is pluralized correctly. Since Drupal.t() is + * called by this function, make sure not to pass already-localized strings to it. + * + * See the documentation of the server-side format_plural() function for further details. + * + * @param count + * The item count to display. + * @param singular + * The string for the singular case. Please make sure it is clear this is + * singular, to ease translation (e.g. use "1 new comment" instead of "1 new"). + * Do not use @count in the singular string. + * @param plural + * The string for the plural case. Please make sure it is clear this is plural, + * to ease translation. Use @count in place of the item count, as in "@count + * new comments". + * @param args + * An object of replacements pairs to make after translation. Incidences + * of any key in this array are replaced with the corresponding value. + * See Drupal.formatString(). + * Note that you do not need to include @count in this array. + * This replacement is done automatically for the plural case. + * @param options + * The options to pass to the Drupal.t() function. + * @return + * A translated string. + */ +Drupal.formatPlural = function (count, singular, plural, args, options) { + var args = args || {}; + args['@count'] = count; + // Determine the index of the plural form. + var index = Drupal.locale.pluralFormula ? Drupal.locale.pluralFormula(args['@count']) : ((args['@count'] == 1) ? 0 : 1); + + if (index == 0) { + return Drupal.t(singular, args, options); + } + else if (index == 1) { + return Drupal.t(plural, args, options); + } + else { + args['@count[' + index + ']'] = args['@count']; + delete args['@count']; + return Drupal.t(plural.replace('@count', '@count[' + index + ']'), args, options); + } +}; + +/** + * Generate the themed representation of a Drupal object. + * + * All requests for themed output must go through this function. It examines + * the request and routes it to the appropriate theme function. If the current + * theme does not provide an override function, the generic theme function is + * called. + * + * For example, to retrieve the HTML for text that should be emphasized and + * displayed as a placeholder inside a sentence, call + * Drupal.theme('placeholder', text). + * + * @param func + * The name of the theme function to call. + * @param ... + * Additional arguments to pass along to the theme function. + * @return + * Any data the theme function returns. This could be a plain HTML string, + * but also a complex object. + */ +Drupal.theme = function (func) { + var args = Array.prototype.slice.apply(arguments, [1]); + + return (Drupal.theme[func] || Drupal.theme.prototype[func]).apply(this, args); +}; + +/** + * Freeze the current body height (as minimum height). Used to prevent + * unnecessary upwards scrolling when doing DOM manipulations. + */ +Drupal.freezeHeight = function () { + Drupal.unfreezeHeight(); + $('<div id="freeze-height"></div>').css({ + position: 'absolute', + top: '0px', + left: '0px', + width: '1px', + height: $('body').css('height') + }).appendTo('body'); +}; + +/** + * Unfreeze the body height. + */ +Drupal.unfreezeHeight = function () { + $('#freeze-height').remove(); +}; + +/** + * Encodes a Drupal path for use in a URL. + * + * For aesthetic reasons slashes are not escaped. + */ +Drupal.encodePath = function (item, uri) { + uri = uri || location.href; + return encodeURIComponent(item).replace(/%2F/g, '/'); +}; + +/** + * Get the text selection in a textarea. + */ +Drupal.getSelection = function (element) { + if (typeof element.selectionStart != 'number' && document.selection) { + // The current selection. + var range1 = document.selection.createRange(); + var range2 = range1.duplicate(); + // Select all text. + range2.moveToElementText(element); + // Now move 'dummy' end point to end point of original range. + range2.setEndPoint('EndToEnd', range1); + // Now we can calculate start and end points. + var start = range2.text.length - range1.text.length; + var end = start + range1.text.length; + return { 'start': start, 'end': end }; + } + return { 'start': element.selectionStart, 'end': element.selectionEnd }; +}; + +/** + * Build an error message from an Ajax response. + */ +Drupal.ajaxError = function (xmlhttp, uri) { + var statusCode, statusText, pathText, responseText, readyStateText, message; + if (xmlhttp.status) { + statusCode = "\n" + Drupal.t("An AJAX HTTP error occurred.") + "\n" + Drupal.t("HTTP Result Code: !status", {'!status': xmlhttp.status}); + } + else { + statusCode = "\n" + Drupal.t("An AJAX HTTP request terminated abnormally."); + } + statusCode += "\n" + Drupal.t("Debugging information follows."); + pathText = "\n" + Drupal.t("Path: !uri", {'!uri': uri} ); + statusText = ''; + // In some cases, when statusCode == 0, xmlhttp.statusText may not be defined. + // Unfortunately, testing for it with typeof, etc, doesn't seem to catch that + // and the test causes an exception. So we need to catch the exception here. + try { + statusText = "\n" + Drupal.t("StatusText: !statusText", {'!statusText': $.trim(xmlhttp.statusText)}); + } + catch (e) {} + + responseText = ''; + // Again, we don't have a way to know for sure whether accessing + // xmlhttp.responseText is going to throw an exception. So we'll catch it. + try { + responseText = "\n" + Drupal.t("ResponseText: !responseText", {'!responseText': $.trim(xmlhttp.responseText) } ); + } catch (e) {} + + // Make the responseText more readable by stripping HTML tags and newlines. + responseText = responseText.replace(/<("[^"]*"|'[^']*'|[^'">])*>/gi,""); + responseText = responseText.replace(/[\n]+\s+/g,"\n"); + + // We don't need readyState except for status == 0. + readyStateText = xmlhttp.status == 0 ? ("\n" + Drupal.t("ReadyState: !readyState", {'!readyState': xmlhttp.readyState})) : ""; + + message = statusCode + pathText + statusText + responseText + readyStateText; + return message; +}; + +// Class indicating that JS is enabled; used for styling purpose. +$('html').addClass('js'); + +// 'js enabled' cookie. +document.cookie = 'has_js=1; path=/'; + +/** + * Additions to jQuery.support. + */ +$(function () { + /** + * Boolean indicating whether or not position:fixed is supported. + */ + if (jQuery.support.positionFixed === undefined) { + var el = $('<div style="position:fixed; top:10px" />').appendTo(document.body); + jQuery.support.positionFixed = el[0].offsetTop === 10; + el.remove(); + } +}); + +//Attach all behaviors. +$(function () { + Drupal.attachBehaviors(document, Drupal.settings); +}); + +/** + * The default themes. + */ +Drupal.theme.prototype = { + + /** + * Formats text for emphasized display in a placeholder inside a sentence. + * + * @param str + * The text to format (plain-text). + * @return + * The formatted text (html). + */ + placeholder: function (str) { + return '<em class="placeholder">' + Drupal.checkPlain(str) + '</em>'; + } +}; + +})(jQuery); |