docs/title.txt

   1 title.txt
   2
   3 The MediaWiki software's "Title" class represents article
   4 titles, which are used for many purposes: as the human-readable
   5 text title of the article, in the URL used to access the article,
   6 the wikitext link to the article, the key into the article
   7 database, and so on. The class in instantiated from one of
   8 these forms and can be queried for the others, and for other
   9 attributes of the title. This is intended to be an
  10 immutable "value" class, so there are no mutator functions.
  11
  12 To get a new instance, call one of the static factory
  13 methods Title::newFromURL(), Title::newFromDBKey(),
  14 or Title::newFromText(). Once instantiated, the
  15 other non-static accessor methods can be used, such as
  16 getText(), getDBKey(), getNamespace(), etc.
  17
  18 The prefix rules: a title consists of an optional interwiki
  19 prefix (such as "m:" for meta or "de:" for German), followed
  20 by an optional namespace, followed by the remainder of the
  21 title. Both interwiki prefixes and namespace prefixes have
  22 the same rules: they contain only letters, digits, space, and
  23 underscore, must start with a letter, are case insensitive,
  24 and spaces and underscores are interchangeable.  Prefixes end
  25 with a ":". A prefix is only recognized if it is one of those
  26 specifically allowed by the software. For example, "de:name"
  27 is a link to the article "name" in the German Wikipedia, because
  28 "de" is recognized as one of the allowable interwikis. The
  29 title "talk:name" is a link to the article "name" in the "talk"
  30 namespace of the current wiki, because "talk" is a recognized
  31 namespace. Both may be present, and if so, the interwiki must
  32 come first, for example, "m:talk:name". If a title begins with
  33 a colon as its first character, no prefixes are scanned for,
  34 and the colon is just removed. Note that because of these
  35 rules, it is possible to have articles with colons in their
  36 names. "E. Coli 0157:H7" is a valid title, as is "2001: A Space
  37 Odyssey", because "E. Coli 0157" and "2001" are not valid
  38 interwikis or namespaces.
  39
  40 It is not possible to have an article whose bare name includes
  41 a namespace or interwiki prefix.
  42
  43 An initial colon in a title listed in wiki text may however
  44 suppress special handling for interlanguage links, image links,
  45 and category links.
  46
  47 Character mapping rules: Once prefixes have been stripped, the
  48 rest of the title processed this way: spaces and underscores are
  49 treated as equivalent and each is converted to the other in the
  50 appropriate context (underscore in URL and database keys, spaces
  51 in plain text). "Extended" characters in the 0x80..0xFF range
  52 are allowed in all places, and are valid characters. They are
  53 encoded in URLs.  Other characters may be ASCII letters, digits,
  54 hyphen, comma, period, apostrophe, parentheses, and colon. No
  55 other ASCII characters are allowed, and will be deleted if found
  56 (they will probably cause a browser to misinterpret the URL).
  57 Extended characters are _not_ urlencoded when used as text or
  58 database keys.
  59
  60 Character encoding rules: TODO
  61
  62 Canonical forms: the canonical form of a title will always be
  63 returned by the object. In this form, the first (and only the
  64 first) character of the namespace and title will be uppercased;
  65 the rest of the namespace will be lowercased, while the title
  66 will be left as is. The text form will use spaces, the URL and
  67 DBkey forms will use underscores. Interwiki prefixes are all
  68 lowercase. The namespace will use underscores when returned
  69 alone; it will use spaces only when attached to the text title.
  70
  71 getArticleID() needs some explanation: for "internal" articles,
  72 it should return the "page_id" field if the article exists, else
  73 it returns 0. For all external articles it returns 0. All of
  74 the IDs for all instances of Title created during a request are
  75 cached, so they can be looked up quickly while rendering wiki
  76 text with lots of internal links.