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
This commit is contained in:
Trevor Parscal
parent
e11e9d871b
commit
55dac1f933
3 changed files with 142 additions and 68 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,84 +1,151 @@
|
|||
/**
|
||||
* Simple Placeholder-based Localization
|
||||
*
|
||||
* Call on a selection of HTML which contains <html:msg key="message-key" /> elements or elements with
|
||||
* title-msg="message-key" or alt-msg="message-key" attributes. <html:msg /> elements will be replaced
|
||||
* with localized text, elements with title-msg and alt-msg attributes will receive localized title
|
||||
* and alt attributes.
|
||||
* *
|
||||
* Example:
|
||||
* <p class="somethingCool">
|
||||
* <html:msg key="my-message" />
|
||||
* <img src="something.jpg" title-msg="my-title-message" alt-msg="my-alt-message" />
|
||||
* </p>
|
||||
* Call on a selection of HTML which contains <html:msg key="message-key" /> elements or elements
|
||||
* with title-msg="message-key", alt-msg="message-key" or placeholder-msg="message-key" attributes.
|
||||
* <html:msg /> 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 = '\
|
||||
* <p>\
|
||||
* <html:msg key="title" />\
|
||||
* <img src="something.jpg" title-msg="title" alt-msg="desc" />\
|
||||
* <input type="text" placeholder-msg="search" />\
|
||||
* </p>';
|
||||
* $( 'body' ).append( $( html ).localize() );
|
||||
*
|
||||
* Appends something like this to the body...
|
||||
* <p>
|
||||
* Awesome
|
||||
* <img src="something.jpg" title="Awesome" alt="Cat doing backflip" />
|
||||
* <input type="text" placeholder="Search" />
|
||||
* </p>
|
||||
*
|
||||
* 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 = '<p><html:msg key="easy-as" /></p>';
|
||||
* $( 'body' ).append( $( html ).localize( { 'params': { 'easy-as': ['a', 'b', 'c'] } } ) );
|
||||
*
|
||||
* Appends something like this to the body...
|
||||
* <p>Easy as a, b, c</p>
|
||||
*
|
||||
* 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': '<b><i>Hello</i> $1!</b>' }
|
||||
* var html = '\
|
||||
* <p>\
|
||||
* <!-- escaped: --><html:msg key="hello" />\
|
||||
* <!-- raw: --><html:msg key="hello" raw />\
|
||||
* </p>';
|
||||
* $( 'body' ).append( $( html ).localize( { 'params': { 'hello': ['world'] } } ) );
|
||||
*
|
||||
* Appends something like this to the body...
|
||||
* <p>
|
||||
* <!-- escaped: --><b><i>Hello</i> world!</b>
|
||||
* <!-- raw: --><b><i>Hello</i> world!</b>
|
||||
* </p>
|
||||
*
|
||||
* 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:
|
||||
* // Messages: { 'good-afternoon': 'Good afternoon' }
|
||||
* var html = '<p><html:msg key="greeting" /></p>';
|
||||
* $( 'body' ).append( $( html ).localize( { 'keys': { 'greeting': 'good-afternoon' } } ) );
|
||||
*
|
||||
* Appends something like this to the body...
|
||||
* <p>Good afternoon</p>
|
||||
*
|
||||
* 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 = '<p><html:msg key="warning" /></p>';
|
||||
* $( 'body' ).append( $( html ).localize( { 'prefix': 'teleportation-' } ) );
|
||||
*
|
||||
* Appends something like this to the body...
|
||||
* <p>You may not get there all in one piece.</p>
|
||||
*
|
||||
* Localizes to...
|
||||
* <p class="somethingCool">
|
||||
* My Message
|
||||
* <img src="something.jpg" title="My Title Message" alt="My Alt Message" />
|
||||
* </p>
|
||||
*/
|
||||
( 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 <html:msg /> 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...
|
||||
|
|
|
|||
|
|
@ -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 = '<div><span title-msg="basic" /></span></div>';
|
||||
html = '<div><span title-msg="basic"></span></div>';
|
||||
$lc = $( html ).localize().find( 'span' );
|
||||
|
||||
assert.strictEqual( $lc.attr( 'title' ), 'Basic stuff', 'Attribute: title-msg' );
|
||||
|
||||
// Attribute: alt-msg
|
||||
html = '<div><span alt-msg="basic" /></span></div>';
|
||||
html = '<div><span alt-msg="basic"></span></div>';
|
||||
$lc = $( html ).localize().find( 'span' );
|
||||
|
||||
assert.strictEqual( $lc.attr( 'alt' ), 'Basic stuff', 'Attribute: alt-msg' );
|
||||
|
||||
// Attribute: placeholder-msg
|
||||
html = '<div><input placeholder-msg="basic" /></div>';
|
||||
$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 = '<div><span><html:msg key="properfoo" /></span></div>';
|
||||
html = '<div><span><html:msg key="properfoo"></span></div>';
|
||||
$lc = $( html ).localize().find( 'span' );
|
||||
|
||||
assert.strictEqual( $lc.text(), mw.msg( 'properfoo' ), 'Content is inserted as text, not as html.' );
|
||||
|
||||
// Attribute escaping
|
||||
html = '<div><span title-msg="properfoo" /></span></div>';
|
||||
html = '<div><span title-msg="properfoo"></span></div>';
|
||||
$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 = '<div><span title-msg="lorem"><html:msg key="ipsum" /></span></div>';
|
||||
html = '<div><span title-msg="lorem"><html:msg key="ipsum"></span></div>';
|
||||
$lc = $( html ).localize( {
|
||||
prefix: 'foo-'
|
||||
} ).find( 'span' );
|
||||
|
|
@ -66,7 +72,7 @@ QUnit.test( 'Options', 7, function ( assert ) {
|
|||
|
||||
// Variable keys mapping
|
||||
x = 'bar';
|
||||
html = '<div><span title-msg="title"><html:msg key="label" /></span></div>';
|
||||
html = '<div><span title-msg="title"><html:msg key="label"></span></div>';
|
||||
$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 = '<div><span><html:msg key="foo-welcome" /></span></div>';
|
||||
html = '<div><span><html:msg key="foo-welcome"></span></div>';
|
||||
$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 = '<div><span title-msg="title"><html:msg key="label" /></span></div>';
|
||||
html = '<div><span title-msg="title"><html:msg key="label"></span></div>';
|
||||
$lc = $( html ).localize( {
|
||||
prefix: 'foo-',
|
||||
keys: {
|
||||
|
|
|
|||
Loading…
Reference in a new issue