mediawiki.Title: Fix typo "add" in documentation

[lhc/web/wiklou.git] / resources / src / mediawiki / mediawiki.Title.js

diff --git a/resources/src/mediawiki/mediawiki.Title.js b/resources/src/mediawiki/mediawiki.Title.js
index 47250ee..ffb3041 100644 (file)
--- a/resources/src/mediawiki/mediawiki.Title.js
+++ b/resources/src/mediawiki/mediawiki.Title.js
@@ -7,13 +7,30 @@
        /*jshint latedef:false */
 
        /**
-        * @class mw.Title
-        *
         * Parse titles into an object structure. Note that when using the constructor
         * directly, passing invalid titles will result in an exception. Use #newFromText to use the
         * logic directly and get null for invalid titles which is easier to work with.
         *
-        * @constructor
+        * @class mw.Title
+        */
+       /**
+        * Note that in the constructor and #newFromText method, `namespace` is the **default** namespace
+        * only, and can be overridden by a namespace prefix in `title`. If you do not want this behavior,
+        * use #makeTitle. Compare:
+        *
+        *     new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText();                  // => 'Template:Foo'
+        *     mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText();          // => 'Template:Foo'
+        *     mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText();            // => 'Template:Foo'
+        *
+        *     new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText();         // => 'Category:Foo'
+        *     mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo'
+        *     mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText();   // => 'Template:Category:Foo'
+        *
+        *     new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText();         // => 'Template:Foo'
+        *     mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
+        *     mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText();   // => 'Template:Template:Foo'
+        *
+        * @method constructor
         * @param {string} title Title of the page. If no second argument given,
         *  this will be searched for a namespace
         * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title
@@ -116,6 +133,18 @@
                return id;
        },
 
+       /**
+        * @private
+        * @method getNamespacePrefix_
+        * @param {number} namespace
+        * @return {string}
+        */
+       getNamespacePrefix = function ( namespace ) {
+               return namespace === NS_MAIN ?
+                       '' :
+                       ( mw.config.get( 'wgFormattedNamespaces' )[ namespace ].replace( / /g, '_' ) + ':' );
+       },
+
        rUnderscoreTrim = /^_+|_+$/g,
 
        rSplit = /^(.+?)_*:_*(.*)$/,
@@ -212,7 +241,7 @@
        ],
 
        /**
-        * Internal helper for #constructor and #newFromtext.
+        * Internal helper for #constructor and #newFromText.
         *
         * Based on Title.php#secureAndSplit
         *
@@ -452,6 +481,10 @@
        /**
         * Constructor for Title objects with a null return instead of an exception for invalid titles.
         *
+        * Note that `namespace` is the **default** namespace only, and can be overridden by a namespace
+        * prefix in `title`. If you do not want this behavior, use #makeTitle. See #constructor for
+        * details.
+        *
         * @static
         * @param {string} title
         * @param {number} [namespace=NS_MAIN] Default namespace
@@ -472,6 +505,24 @@
                return t;
        };
 
+       /**
+        * Constructor for Title objects with predefined namespace.
+        *
+        * Unlike #newFromText or #constructor, this function doesn't allow the given `namespace` to be
+        * overridden by a namespace prefix in `title`. See #constructor for details about this behavior.
+        *
+        * The single exception to this is when `namespace` is 0, indicating the main namespace. The
+        * function behaves like #newFromText in that case.
+        *
+        * @static
+        * @param {number} namespace Namespace to use for the title
+        * @param {string} title
+        * @return {mw.Title|null} A valid Title object or null if the title is invalid
+        */
+       Title.makeTitle = function ( namespace, title ) {
+               return mw.Title.newFromText( getNamespacePrefix( namespace ) + title );
+       };
+
        /**
         * Constructor for Title objects from user input altering that input to
         * produce a title that MediaWiki will accept as legal
@@ -761,9 +812,7 @@
                 * @return {string}
                 */
                getNamespacePrefix: function () {
-                       return this.namespace === NS_MAIN ?
-                               '' :
-                               ( mw.config.get( 'wgFormattedNamespaces' )[ this.namespace ].replace( / /g, '_' ) + ':' );
+                       return getNamespacePrefix( this.namespace );
                },
 
                /**
@@ -906,7 +955,12 @@
                 * @return {string}
                 */
                getUrl: function ( params ) {
-                       return mw.util.getUrl( this.toString(), params );
+                       var fragment = this.getFragment();
+                       if ( fragment ) {
+                               return mw.util.getUrl( this.toString() + '#' + this.getFragment(), params );
+                       } else {
+                               return mw.util.getUrl( this.toString(), params );
+                       }
                },
 
                /**