resources/src/jquery/jquery.localize.js

   1 /**
   2  * @class jQuery.plugin.localize
   3  */
   4 ( function ( $, mw ) {
   5
   6         /**
   7          * Gets a localized message, using parameters from options if present.
   8          *
   9          * @ignore
  10          * @param {Object} options
  11          * @param {string} key
  12          * @return {string} Localized message
  13          */
  14         function msg( options, key ) {
  15                 var args = options.params[ key ] || [];
  16                 // Format: mw.msg( key [, p1, p2, ...] )
  17                 args.unshift( options.prefix + ( options.keys[ key ] || key ) );
  18                 return mw.msg.apply( mw, args );
  19         }
  20
  21         /**
  22          * Localizes a DOM selection by replacing <html:msg /> elements with localized text and adding
  23          * localized title and alt attributes to elements with title-msg and alt-msg attributes
  24          * respectively.
  25          *
  26          * Call on a selection of HTML which contains `<html:msg key="message-key" />` elements or elements
  27          * with title-msg="message-key", alt-msg="message-key" or placeholder-msg="message-key" attributes.
  28          * `<html:msg />` elements will be replaced with localized text, *-msg attributes will be replaced
  29          * with attributes that do not have the "-msg" suffix and contain a localized message.
  30          *
  31          * Example:
  32          *     // Messages: { 'title': 'Awesome', 'desc': 'Cat doing backflip' 'search' contains 'Search' }
  33          *     var html = '\
  34          *         <p>\
  35          *             <html:msg key="title" />\
  36          *             <img src="something.jpg" title-msg="title" alt-msg="desc" />\
  37          *             <input type="text" placeholder-msg="search" />\
  38          *         </p>';
  39          *     $( 'body' ).append( $( html ).localize() );
  40          *
  41          * Appends something like this to the body...
  42          *     <p>
  43          *         Awesome
  44          *         <img src="something.jpg" title="Awesome" alt="Cat doing backflip" />
  45          *         <input type="text" placeholder="Search" />
  46          *     </p>
  47          *
  48          * Arguments can be passed into uses of a message using the params property of the options object
  49          * given to .localize(). Multiple messages can be given parameters, because the params property is
  50          * an object keyed by the message key to apply the parameters to, each containing an array of
  51          * parameters to use. The limitation is that you can not use different parameters to individual uses
  52          * of a message in the same selection being localized - they will all recieve the same parameters.
  53          *
  54          * Example:
  55          *     // Messages: { 'easy-as': 'Easy as $1 $2 $3.' }
  56          *     var html = '<p><html:msg key="easy-as" /></p>';
  57          *     $( 'body' ).append( $( html ).localize( { 'params': { 'easy-as': ['a', 'b', 'c'] } } ) );
  58          *
  59          * Appends something like this to the body...
  60          *     <p>Easy as a, b, c</p>
  61          *
  62          * Raw HTML content can be used, instead of it being escaped as text. To do this, just use the raw
  63          * attribute on a msg element.
  64          *
  65          * Example:
  66          *     // Messages: { 'hello': '<b><i>Hello</i> $1!</b>' }
  67          *     var html = '\
  68          *         <p>\
  69          *             <!-- escaped: --><html:msg key="hello" />\
  70          *             <!-- raw: --><html:msg key="hello" raw />\
  71          *         </p>';
  72          *     $( 'body' ).append( $( html ).localize( { 'params': { 'hello': ['world'] } } ) );
  73          *
  74          * Appends something like this to the body...
  75          *     <p>
  76          *         <!-- escaped: -->&lt;b&gt;&lt;i&gt;Hello&lt;/i&gt; world!&lt;/b&gt;
  77          *         <!-- raw: --><b><i>Hello</i> world!</b>
  78          *     </p>
  79          *
  80          * Message keys can also be remapped, allowing the same generic template to be used with a variety
  81          * of messages. This is important for improving re-usability of templates.
  82          *
  83          * Example:
  84          *     // Messages: { 'good-afternoon': 'Good afternoon' }
  85          *     var html = '<p><html:msg key="greeting" /></p>';
  86          *     $( 'body' ).append( $( html ).localize( { 'keys': { 'greeting': 'good-afternoon' } } ) );
  87          *
  88          * Appends something like this to the body...
  89          *     <p>Good afternoon</p>
  90          *
  91          * Message keys can also be prefixed globally, which is handy when writing extensions, where by
  92          * convention all messages are prefixed with the extension's name.
  93          *
  94          * Example:
  95          *     // Messages: { 'teleportation-warning': 'You may not get there all in one piece.' }
  96          *     var html = '<p><html:msg key="warning" /></p>';
  97          *     $( 'body' ).append( $( html ).localize( { 'prefix': 'teleportation-' } ) );
  98          *
  99          * Appends something like this to the body...
 100          *     <p>You may not get there all in one piece.</p>
 101          *
 102          * @param {Object} options Map of options to be used while localizing
 103          * @param {string} options.prefix String to prepend to all message keys
 104          * @param {Object} options.keys Message key aliases, used for remapping keys to a template
 105          * @param {Object} options.params Lists of parameters to use with certain message keys
 106          * @return {jQuery}
 107          * @chainable
 108          */
 109         $.fn.localize = function ( options ) {
 110                 var $target = this,
 111                         attributes = [ 'title', 'alt', 'placeholder' ];
 112
 113                 // Extend options
 114                 options = $.extend( {
 115                         prefix: '',
 116                         keys: {},
 117                         params: {}
 118                 }, options );
 119
 120                 // Elements
 121                 // Ok, so here's the story on this selector. In IE 6/7, searching for 'msg' turns up the
 122                 // 'html:msg', but searching for 'html:msg' doesn't. In later IE and other browsers, searching
 123                 // for 'html:msg' turns up the 'html:msg', but searching for 'msg' doesn't. So searching for
 124                 // both 'msg' and 'html:msg' seems to get the job done. This feels pretty icky, though.
 125                 $target.find( 'msg,html\\:msg' ).each( function () {
 126                         var $el = $( this );
 127                         // Escape by default
 128                         if ( $el.attr( 'raw' ) ) {
 129                                 $el.html( msg( options, $el.attr( 'key' ) ) );
 130                         } else {
 131                                 $el.text( msg( options, $el.attr( 'key' ) ) );
 132                         }
 133                         // Remove wrapper
 134                         $el.replaceWith( $el.html() );
 135                 } );
 136
 137                 // Attributes
 138                 // Note: there's no way to prevent escaping of values being injected into attributes, this is
 139                 // on purpose, not a design flaw.
 140                 $.each( attributes, function ( i, attr ) {
 141                         var msgAttr = attr + '-msg';
 142                         $target.find( '[' + msgAttr + ']' ).each( function () {
 143                                 var $el = $( this );
 144                                 $el.attr( attr, msg( options, $el.attr( msgAttr ) ) ).removeAttr( msgAttr );
 145                         } );
 146                 } );
 147
 148                 // HTML, Text for elements which cannot have children e.g. OPTION
 149                 $target.find( '[data-msg-text]' ).each( function () {
 150                         var $el = $( this );
 151                         $el.text( msg( options, $el.attr( 'data-msg-text' ) ) );
 152                 } );
 153
 154                 $target.find( '[data-msg-html]' ).each( function () {
 155                         var $el = $( this );
 156                         $el.html( msg( options, $el.attr( 'data-msg-html' ) ) );
 157                 } );
 158
 159                 return $target;
 160         };
 161
 162         // Let IE know about the msg tag before it's used...
 163         document.createElement( 'msg' );
 164
 165         /**
 166          * @class jQuery
 167          * @mixins jQuery.plugin.localize
 168          */
 169
 170 }( jQuery, mediaWiki ) );