2 * @author Neil Kandalgaonkar, 2010
3 * @author Timo Tijhof, 2011-2013
11 * Parse titles into an object struture. Note that when using the constructor
12 * directly, passing invalid titles will result in an exception. Use #newFromText to use the
13 * logic directly and get null for invalid titles which is easier to work with.
16 * @param {string} title Title of the page. If no second argument given,
17 * this will be searched for a namespace
18 * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title
19 * @throws {Error} When the title is invalid
21 function Title( title, namespace ) {
22 var parsed = parse( title, namespace );
24 throw new Error( 'Unable to parse title' );
27 this.namespace = parsed.namespace;
28 this.title = parsed.title;
29 this.ext = parsed.ext;
30 this.fragment = parsed.fragment;
56 * @property NS_SPECIAL
61 * Get the namespace id from a namespace name (either from the localized, canonical or alias
64 * Example: On a German wiki this would return 6 for any of 'File', 'Datei', 'Image' or
69 * @method getNsIdByName
70 * @param {string} ns Namespace name (case insensitive, leading/trailing space ignored)
71 * @return {number|boolean} Namespace id or boolean false
73 getNsIdByName = function ( ns ) {
76 // Don't cast non-strings to strings, because null or undefined should not result in
77 // returning the id of a potential namespace called "Null:" (e.g. on null.example.org/wiki)
78 // Also, toLowerCase throws exception on null/undefined, because it is a String method.
79 if ( typeof ns !== 'string' ) {
82 ns = ns.toLowerCase();
83 id = mw.config.get( 'wgNamespaceIds' )[ns];
84 if ( id === undefined ) {
90 rUnderscoreTrim = /^_+|_+$/g,
92 rSplit = /^(.+?)_*:_*(.*)$/,
94 // See Title.php#getTitleInvalidRegex
95 rInvalid = new RegExp(
96 '[^' + mw.config.get( 'wgLegalTitleChars' ) + ']' +
97 // URL percent encoding sequences interfere with the ability
98 // to round-trip titles -- you can't link to them consistently.
100 // XML/HTML character references produce similar issues.
101 '|&[A-Za-z0-9\u0080-\uFFFF]+;' +
107 * Internal helper for #constructor and #newFromtext.
109 * Based on Title.php#secureAndSplit
114 * @param {string} title
115 * @param {number} [defaultNamespace=NS_MAIN]
116 * @return {Object|boolean}
118 parse = function ( title, defaultNamespace ) {
119 var namespace, m, id, i, fragment, ext;
121 namespace = defaultNamespace === undefined ? NS_MAIN : defaultNamespace;
124 // Normalise whitespace to underscores and remove duplicates
125 .replace( /[ _\s]+/g, '_' )
127 .replace( rUnderscoreTrim, '' );
129 if ( title === '' ) {
133 // Process initial colon
134 if ( title.charAt( 0 ) === ':' ) {
135 // Initial colon means main namespace instead of specified default
141 .replace( rUnderscoreTrim, '' );
144 // Process namespace prefix (if any)
145 m = title.match( rSplit );
147 id = getNsIdByName( m[1] );
148 if ( id !== false ) {
149 // Ordinary namespace
153 // For Talk:X pages, make sure X has no "namespace" prefix
154 if ( namespace === NS_TALK && ( m = title.match( rSplit ) ) ) {
155 // Disallow titles like Talk:File:x (subject should roundtrip: talk:file:x -> file:x -> file_talk:x)
156 if ( getNsIdByName( m[1] ) !== false ) {
164 i = title.indexOf( '#' );
169 // Get segment starting after the hash
172 // NB: Must not be trimmed ("Example#_foo" is not the same as "Example#foo")
173 .replace( /_/g, ' ' );
178 // Trim underscores, again (strips "_" from "bar" in "Foo_bar_#quux")
179 .replace( rUnderscoreTrim, '' );
183 // Reject illegal characters
184 if ( title.match( rInvalid ) ) {
188 // Disallow titles that browsers or servers might resolve as directory navigation
190 title.indexOf( '.' ) !== -1 && (
191 title === '.' || title === '..' ||
192 title.indexOf( './' ) === 0 ||
193 title.indexOf( '../' ) === 0 ||
194 title.indexOf( '/./' ) !== -1 ||
195 title.indexOf( '/../' ) !== -1 ||
196 title.substr( title.length - 2 ) === '/.' ||
197 title.substr( title.length - 3 ) === '/..'
203 // Disallow magic tilde sequence
204 if ( title.indexOf( '~~~' ) !== -1 ) {
208 // Disallow titles exceeding the 255 byte size limit (size of underlying database field)
209 // Except for special pages, e.g. [[Special:Block/Long name]]
210 // Note: The PHP implementation also asserts that even in NS_SPECIAL, the title should
211 // be less than 512 bytes.
212 if ( namespace !== NS_SPECIAL && $.byteLength( title ) > 255 ) {
216 // Can't make a link to a namespace alone.
217 if ( title === '' && namespace !== NS_MAIN ) {
221 // Any remaining initial :s are illegal.
222 if ( title.charAt( 0 ) === ':' ) {
226 // For backwards-compatibility with old mw.Title, we separate the extension from the
227 // rest of the title.
228 i = title.lastIndexOf( '.' );
229 if ( i === -1 || title.length <= i + 1 ) {
230 // Extensions are the non-empty segment after the last dot
233 ext = title.substr( i + 1 );
234 title = title.substr( 0, i );
238 namespace: namespace,
246 * Convert db-key to readable text.
254 text = function ( s ) {
255 if ( s !== null && s !== undefined ) {
256 return s.replace( /_/g, ' ' );
262 // Polyfill for ES5 Object.create
263 createObject = Object.create || ( function () {
264 return function ( o ) {
266 if ( o !== Object( o ) ) {
267 throw new Error( 'Cannot inherit from a non-object' );
278 * Constructor for Title objects with a null return instead of an exception for invalid titles.
282 * @param {string} title
283 * @param {number} [namespace=NS_MAIN] Default namespace
284 * @return {mw.Title|null} A valid Title object or null if the title is invalid
286 Title.newFromText = function ( title, namespace ) {
287 var t, parsed = parse( title, namespace );
292 t = createObject( Title.prototype );
293 t.namespace = parsed.namespace;
294 t.title = parsed.title;
296 t.fragment = parsed.fragment;
302 * Get the file title from an image element
304 * var title = mw.Title.newFromImg( $( 'img:first' ) );
307 * @param {HTMLElement|jQuery} img The image to use as a base
308 * @return {mw.Title|null} The file title or null if unsuccessful
310 Title.newFromImg = function ( img ) {
311 var matches, i, regex, src, decodedSrc,
313 // thumb.php-generated thumbnails
314 thumbPhpRegex = /thumb\.php/,
317 /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s\/]+)\/[^\s\/]+-(?:\1|thumbnail)[^\s\/]*$/,
319 // Thumbnails in non-hashed upload directories
320 /\/([^\s\/]+)\/[^\s\/]+-(?:\1|thumbnail)[^\s\/]*$/,
323 /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s\/]+)$/,
325 // Full-size images in non-hashed upload directories
329 recount = regexes.length;
331 src = img.jquery ? img[0].src : img.src;
333 matches = src.match( thumbPhpRegex );
336 return mw.Title.newFromText( 'File:' + mw.util.getParamValue( 'f', src ) );
339 decodedSrc = decodeURIComponent( src );
341 for ( i = 0; i < recount; i++ ) {
343 matches = decodedSrc.match( regex );
345 if ( matches && matches[1] ) {
346 return mw.Title.newFromText( 'File:' + matches[1] );
354 * Whether this title exists on the wiki.
357 * @param {string|mw.Title} title prefixed db-key name (string) or instance of Title
358 * @return {boolean|null} Boolean if the information is available, otherwise null
360 Title.exists = function ( title ) {
362 type = $.type( title ),
363 obj = Title.exist.pages;
365 if ( type === 'string' ) {
367 } else if ( type === 'object' && title instanceof Title ) {
368 match = obj[title.toString()];
370 throw new Error( 'mw.Title.exists: title must be a string or an instance of Title' );
373 if ( typeof match === 'boolean' ) {
382 * Boolean true value indicates page does exist.
385 * @property {Object} exist.pages Keyed by PrefixedDb title.
390 * Example to declare existing titles:
391 * Title.exist.set(['User:John_Doe', ...]);
392 * Eample to declare titles nonexistent:
393 * Title.exist.set(['File:Foo_bar.jpg', ...], false);
396 * @property exist.set
397 * @param {string|Array} titles Title(s) in strict prefixedDb title form
398 * @param {boolean} [state=true] State of the given titles
401 set: function ( titles, state ) {
402 titles = $.isArray( titles ) ? titles : [titles];
403 state = state === undefined ? true : !!state;
404 var pages = this.pages, i, len = titles.length;
405 for ( i = 0; i < len; i++ ) {
406 pages[ titles[i] ] = state;
418 * Get the namespace number
420 * Example: 6 for "File:Example_image.svg".
424 getNamespaceId: function () {
425 return this.namespace;
429 * Get the namespace prefix (in the content language)
431 * Example: "File:" for "File:Example_image.svg".
432 * In #NS_MAIN this is '', otherwise namespace name plus ':'
436 getNamespacePrefix: function () {
437 return this.namespace === NS_MAIN ?
439 ( mw.config.get( 'wgFormattedNamespaces' )[ this.namespace ].replace( / /g, '_' ) + ':' );
443 * Get the page name without extension or namespace prefix
445 * Example: "Example_image" for "File:Example_image.svg".
447 * For the page title (full page name without namespace prefix), see #getMain.
451 getName: function () {
452 if ( $.inArray( this.namespace, mw.config.get( 'wgCaseSensitiveNamespaces' ) ) !== -1 ) {
455 return $.ucFirst( this.title );
460 * Get the page name (transformed by #text)
462 * Example: "Example image" for "File:Example_image.svg".
464 * For the page title (full page name without namespace prefix), see #getMainText.
468 getNameText: function () {
469 return text( this.getName() );
473 * Get the extension of the page name (if any)
475 * @return {string|null} Name extension or null if there is none
477 getExtension: function () {
482 * Shortcut for appendable string to form the main page name.
484 * Returns a string like ".json", or "" if no extension.
488 getDotExtension: function () {
489 return this.ext === null ? '' : '.' + this.ext;
493 * Get the main page name (transformed by #text)
495 * Example: "Example_image.svg" for "File:Example_image.svg".
499 getMain: function () {
500 return this.getName() + this.getDotExtension();
504 * Get the main page name (transformed by #text)
506 * Example: "Example image.svg" for "File:Example_image.svg".
510 getMainText: function () {
511 return text( this.getMain() );
515 * Get the full page name
517 * Eaxample: "File:Example_image.svg".
518 * Most useful for API calls, anything that must identify the "title".
522 getPrefixedDb: function () {
523 return this.getNamespacePrefix() + this.getMain();
527 * Get the full page name (transformed by #text)
529 * Example: "File:Example image.svg" for "File:Example_image.svg".
533 getPrefixedText: function () {
534 return text( this.getPrefixedDb() );
538 * Get the fragment (if any).
540 * Note that this method (by design) does not include the hash character and
541 * the value is not url encoded.
543 * @return {string|null}
545 getFragment: function () {
546 return this.fragment;
550 * Get the URL to this title
552 * @see mw.util#getUrl
553 * @param {Object} [params] A mapping of query parameter names to values,
554 * e.g. `{ action: 'edit' }`.
557 getUrl: function ( params ) {
558 return mw.util.getUrl( this.toString(), params );
562 * Whether this title exists on the wiki.
564 * @see #static-method-exists
565 * @return {boolean|null} Boolean if the information is available, otherwise null
567 exists: function () {
568 return Title.exists( this );
573 * @alias #getPrefixedDb
576 Title.prototype.toString = Title.prototype.getPrefixedDb;
580 * @alias #getPrefixedText
583 Title.prototype.toText = Title.prototype.getPrefixedText;
588 }( mediaWiki, jQuery ) );