From 55dac1f933f7c78d3fbcac4c3ba59cb62ab59b01 Mon Sep 17 00:00:00 2001 From: Trevor Parscal Date: Mon, 30 Jul 2012 14:43:58 -0700 Subject: [PATCH] Added placeholder-msg support and more documentation to jquery.localize * Added examples of all options (prefix, keys and params) * Added example of raw attribute being used to bypass escaping * Added documentation to code where it seemed clarification was needed * Reduce duplication and simplified some unnecessarily complex statements * Added test for new placeholder-msg attribute support * Made adding more attributes in the future easier * Moved message wrapper function out of the localize function so we aren't defining it each time localize is used Change-Id: I77593acf4c1b3974d502a1a8382cca9267af2d41 --- RELEASE-NOTES-1.20 | 1 + resources/jquery/jquery.localize.js | 187 ++++++++++++------ .../resources/jquery/jquery.localize.test.js | 22 ++- 3 files changed, 142 insertions(+), 68 deletions(-) diff --git a/RELEASE-NOTES-1.20 b/RELEASE-NOTES-1.20 index f2a75c23fc..9383bf270f 100644 --- a/RELEASE-NOTES-1.20 +++ b/RELEASE-NOTES-1.20 @@ -104,6 +104,7 @@ upgrade PHP if you have not done so prior to upgrading MediaWiki. * (bug 14237) Allow PAGESINCATEGORY to distinguish between 'all', 'pages', 'files' and 'subcats' * (bug 38362) Make Special:Listuser includeable on wiki pages. +* Added support in jquery.localize for placeholder attributes. === Bug fixes in 1.20 === * (bug 30245) Use the correct way to construct a log page title. diff --git a/resources/jquery/jquery.localize.js b/resources/jquery/jquery.localize.js index 27cae292bf..866778f879 100644 --- a/resources/jquery/jquery.localize.js +++ b/resources/jquery/jquery.localize.js @@ -1,84 +1,151 @@ /** * Simple Placeholder-based Localization * - * Call on a selection of HTML which contains elements or elements with - * title-msg="message-key" or alt-msg="message-key" attributes. elements will be replaced - * with localized text, elements with title-msg and alt-msg attributes will receive localized title - * and alt attributes. - * * + * Call on a selection of HTML which contains elements or elements + * with title-msg="message-key", alt-msg="message-key" or placeholder-msg="message-key" attributes. + * elements will be replaced with localized text, *-msg attributes will be replaced + * with attributes that do not have the "-msg" suffix and contain a localized message. + * + * Example: + * // Messages: { 'title': 'Awesome', 'desc': 'Cat doing backflip' 'search' contains 'Search' } + * var html = '\ + *

\ + * \ + * \ + * \ + *

'; + * $( 'body' ).append( $( html ).localize() ); + * + * Appends something like this to the body... + *

+ * Awesome + * Cat doing backflip + * + *

+ * + * Arguments can be passed into uses of a message using the params property of the options object + * given to .localize(). Multiple messages can be given parameters, because the params property is + * an object keyed by the message key to apply the parameters to, each containing an array of + * parameters to use. The limitation is that you can not use different parameters to individual uses + * of a message in the same selection being localized - they will all recieve the same parameters. + * + * Example: + * // Messages: { 'easy-as': 'Easy as $1 $2 $3.' } + * var html = '

'; + * $( 'body' ).append( $( html ).localize( { 'params': { 'easy-as': ['a', 'b', 'c'] } } ) ); + * + * Appends something like this to the body... + *

Easy as a, b, c

+ * + * Raw HTML content can be used, instead of it being escaped as text. To do this, just use the raw + * attribute on a msg element. + * + * Example: + * // Messages: { 'hello': 'Hello $1!' } + * var html = '\ + *

\ + * \ + * \ + *

'; + * $( 'body' ).append( $( html ).localize( { 'params': { 'hello': ['world'] } } ) ); + * + * Appends something like this to the body... + *

+ * <b><i>Hello</i> world!</b> + * Hello world! + *

+ * + * Message keys can also be remapped, allowing the same generic template to be used with a variety + * of messages. This is important for improving re-usability of templates. + * * Example: - *

- * - * - *

- * - * Localizes to... - *

- * My Message - * My Alt Message - *

+ * // Messages: { 'good-afternoon': 'Good afternoon' } + * var html = '

'; + * $( 'body' ).append( $( html ).localize( { 'keys': { 'greeting': 'good-afternoon' } } ) ); + * + * Appends something like this to the body... + *

Good afternoon

+ * + * Message keys can also be prefixed globally, which is handy when writing extensions, where by + * convention all messages are prefixed with the extension's name. + * + * Example: + * // Messages: { 'teleportation-warning': 'You may not get there all in one piece.' } + * var html = '

'; + * $( 'body' ).append( $( html ).localize( { 'prefix': 'teleportation-' } ) ); + * + * Appends something like this to the body... + *

You may not get there all in one piece.

+ * */ ( function ( $, mw ) { + +/** + * Gets a localized message, using parameters from options if present. + * + * @function + * @param {String} key Message key to get localized message for + * @returns {String} Localized message + */ +function msg( options, key ) { + var args = options.params[key] || []; + // Format: mw.msg( key [, p1, p2, ...] ) + args.unshift( options.prefix + ( options.keys[key] || key ) ); + return mw.msg.apply( mw, args ); +} + /** * Localizes a DOM selection by replacing elements with localized text and adding * localized title and alt attributes to elements with title-msg and alt-msg attributes * respectively. * - * @param Object: options Map of options - * * prefix: Message prefix to use when localizing elements and attributes + * @method + * @param {Object} options Map of options to be used while localizing + * @param {String} options.prefix String to prepend to all message keys + * @param {Object} options.keys Message key aliases, used for remapping keys to a template + * @param {Object} options.params Lists of parameters to use with certain message keys + * @returns {jQuery} This selection */ - $.fn.localize = function ( options ) { + var $target = this, + attributes = ['title', 'alt', 'placeholder']; + + // Extend options options = $.extend( { prefix: '', keys: {}, params: {} }, options ); - function msg( key ) { - var args = key in options.params ? options.params[key] : []; - // Format: mw.msg( key [, p1, p2, ...] ) - args.unshift( options.prefix + ( key in options.keys ? options.keys[key] : key ) ); - return mw.msg.apply( mw, args ); - } + // Elements + // Ok, so here's the story on this selector. In IE 6/7, searching for 'msg' turns up the + // 'html:msg', but searching for 'html:msg' doesn't. In later IE and other browsers, searching + // for 'html:msg' turns up the 'html:msg', but searching for 'msg' doesn't. So searching for + // both 'msg' and 'html:msg' seems to get the job done. This feels pretty icky, though. + $target.find( 'msg,html\\:msg' ).each( function () { + var $el = $(this); + // Escape by default + if ( $el.attr( 'raw' ) ) { + $el.html( msg( options, $el.attr( 'key' ) ) ); + } else { + $el.text( msg( options, $el.attr( 'key' ) ) ); + } + // Remove wrapper + $el.replaceWith( $el.html() ); + } ); - return $(this) - // Ok, so here's the story on this selector. - // In IE 6/7, searching for 'msg' turns up the 'html:msg', but searching for 'html:msg' does not. - // In later IE and other browsers, searching for 'html:msg' turns up the 'html:msg', but searching for 'msg' does not. - // So searching for both 'msg' and 'html:msg' seems to get the job done. - // This feels pretty icky, though. - .find( 'msg,html\\:msg' ) - .each( function () { - var $el = $(this); - var msgText = msg( $el.attr( 'key' ) ); + // Attributes + // Note: there's no way to prevent escaping of values being injected into attributes, this is + // on purpose, not a design flaw. + $.each( attributes, function ( i, attr ) { + var msgAttr = attr + '-msg'; + $target.find( '[' + msgAttr + ']' ).each( function () { + var $el = $(this); + $el.attr( attr, msg( options, $el.attr( msgAttr ) ) ).removeAttr( msgAttr ); + } ); + } ); - if ( $el.attr( 'raw' ) ) { - $el.html(msgText); - } else { - $el.text(msgText); - } - - $el - .replaceWith( $el.html() ); - } ) - .end() - .find( '[title-msg]' ) - .each( function () { - var $el = $(this); - $el - .attr( 'title', msg( $el.attr( 'title-msg' ) ) ) - .removeAttr( 'title-msg' ); - } ) - .end() - .find( '[alt-msg]' ) - .each( function () { - var $el = $(this); - $el - .attr( 'alt', msg( $el.attr( 'alt-msg' ) ) ) - .removeAttr( 'alt-msg' ); - } ) - .end(); + return $target; }; // Let IE know about the msg tag before it's used... diff --git a/tests/qunit/suites/resources/jquery/jquery.localize.test.js b/tests/qunit/suites/resources/jquery/jquery.localize.test.js index 1b38010fe1..dab5b59555 100644 --- a/tests/qunit/suites/resources/jquery/jquery.localize.test.js +++ b/tests/qunit/suites/resources/jquery/jquery.localize.test.js @@ -11,16 +11,22 @@ QUnit.test( 'Handle basic replacements', 3, function ( assert ) { assert.strictEqual( $lc.text(), 'Basic stuff', 'Tag: html:msg' ); // Attribute: title-msg - html = '
'; + html = '
'; $lc = $( html ).localize().find( 'span' ); assert.strictEqual( $lc.attr( 'title' ), 'Basic stuff', 'Attribute: title-msg' ); // Attribute: alt-msg - html = '
'; + html = '
'; $lc = $( html ).localize().find( 'span' ); assert.strictEqual( $lc.attr( 'alt' ), 'Basic stuff', 'Attribute: alt-msg' ); + + // Attribute: placeholder-msg + html = '
'; + $lc = $( html ).localize().find( 'input' ); + + assert.strictEqual( $lc.attr( 'placeholder' ), 'Basic stuff', 'Attribute: placeholder-msg' ); } ); QUnit.test( 'Proper escaping', 2, function ( assert ) { @@ -31,13 +37,13 @@ QUnit.test( 'Proper escaping', 2, function ( assert ) { // making sure it is actually using text() and attr() (or something with the same effect) // Text escaping - html = '
'; + html = '
'; $lc = $( html ).localize().find( 'span' ); assert.strictEqual( $lc.text(), mw.msg( 'properfoo' ), 'Content is inserted as text, not as html.' ); // Attribute escaping - html = '
'; + html = '
'; $lc = $( html ).localize().find( 'span' ); assert.strictEqual( $lc.attr( 'title' ), mw.msg( 'properfoo' ), 'Attributes are not inserted raw.' ); @@ -56,7 +62,7 @@ QUnit.test( 'Options', 7, function ( assert ) { var html, $lc, attrs, x, sitename = 'Wikipedia'; // Message key prefix - html = '
'; + html = '
'; $lc = $( html ).localize( { prefix: 'foo-' } ).find( 'span' ); @@ -66,7 +72,7 @@ QUnit.test( 'Options', 7, function ( assert ) { // Variable keys mapping x = 'bar'; - html = '
'; + html = '
'; $lc = $( html ).localize( { keys: { 'title': 'foo-' + x + '-title', @@ -78,7 +84,7 @@ QUnit.test( 'Options', 7, function ( assert ) { assert.strictEqual( $lc.text(), 'The Bars', 'Variable keys mapping - text' ); // Passing parameteters to mw.msg - html = '
'; + html = '
'; $lc = $( html ).localize( { params: { 'foo-welcome': [sitename, 'yesterday'] @@ -89,7 +95,7 @@ QUnit.test( 'Options', 7, function ( assert ) { // Combination of options prefix, params and keys x = 'bazz'; - html = '
'; + html = '
'; $lc = $( html ).localize( { prefix: 'foo-', keys: { -- 2.20.1