| Index: trunk/extensions/SemanticTitle/README |
| — | — | @@ -1,39 +1,86 @@ |
| 2 | 2 | <!-- README --> |
| 3 | 3 | |
| 4 | | -== Purpose == |
| | 4 | +== What? == |
| 5 | 5 | |
| 6 | | -The `SemanticTitle' extension allows set link text and page title to a value of a semantic property. |
| | 6 | +The SemanticTitle extension sets visible page title to a value of semantic property. |
| 7 | 7 | |
| 8 | | -The extension is useful for pages, which names are automatically generated by a formula |
| 9 | | -(e. g. auto-incremented numbers or ids), but human-readable title is still desirable. |
| | 8 | +For example, if page `Bug:32758' has semantic property `Title' with value `SMW handles timezones |
| | 9 | +incorrectly', and SemanticTitle is properly installed and configured, visible page title will be |
| | 10 | +`SMW handles timezones incorrectly', with subtitle `Bug:32758'. |
| 10 | 11 | |
| 11 | | -== Usage == |
| | 12 | +Similarly, link to the page will be `SMW handles timezones incorrectly' with tooltip `Bug:32758'. |
| 12 | 13 | |
| 13 | | -Add to your `LocalSettings.php': |
| | 14 | +{{ #semantic-title: Bug:32758 }} returns `SMW handles timezones incorrectly' as plain text (not a |
| | 15 | +link). |
| 14 | 16 | |
| 15 | | - require_once( 'SemanticTitle.php' ); |
| 16 | | - $egSemanticTitle[ NS ] = 'Property name'; |
| 17 | | - ... |
| | 17 | +== Why? == |
| 18 | 18 | |
| | 19 | +Let us assume we are creating a bug tracking system based on MediaWiki. Semantic MediaWiki converts |
| | 20 | +wiki into a database. Pages become objects or entities (e. g. bugs) with properties (e. g. title, |
| | 21 | +submitter, severity, component, etc). We want every bug is identified by its number, assigned |
| | 22 | +automatically. Semantic Forms allows it: |
| | 23 | + |
| | 24 | + {{{info|page name=Bug:<unique number>}}} |
| | 25 | + {{{for template|Bug|...}}} |
| | 26 | + ... |
| | 27 | + |
| | 28 | +so every new bug receives unique identifier. Everything works, but bug page title will be |
| | 29 | +`Bug:32758', links to this bug will also be `Bug:32758', while we want to see bug titles (set by |
| | 30 | +user, not an id assigned by system) in page titles and links. This is the job for SemanticTitle |
| | 31 | +extension. |
| | 32 | + |
| | 33 | +== Installation == |
| | 34 | + |
| | 35 | +To install this extension, add the following to LocalSettings.php: |
| | 36 | + |
| | 37 | + require_once( "$IP/extensions/SemanticTitle/SemanticTitle.php" ); |
| | 38 | + |
| | 39 | +Semantic MediaWiki should also be installed. Order of inclusion does not matter. |
| | 40 | + |
| | 41 | +If SemanticTitle is used with HidePrefix extension, SemanticTitle should be included before |
| | 42 | +HidePrefix (SemanticTitle does not touch title if it was set to non-default value, e. g. processed |
| | 43 | +by HidePrefix extension). |
| | 44 | + |
| | 45 | +== Configuration == |
| | 46 | + |
| | 47 | +In LocalSettings.php after including `SemanticTitle.php': |
| | 48 | + |
| | 49 | +$egSemanticTitle = array( |
| | 50 | + NS1 => 'Property name1', |
| | 51 | + NS2 => 'Property name2', |
| | 52 | + ... |
| | 53 | +); |
| | 54 | + |
| 19 | 55 | where: |
| 20 | 56 | |
| 21 | | -* ''NS'' is a namespace index (not namespace name!), for example, `NS_MAIN' or `NS_USER'. |
| 22 | | -* ''Property name'' — a name of semantic property to be used as page title. |
| | 57 | + * NS# — Namespace index (not a namespace name!) (usually constant, like NS_USER). Only pages |
| | 58 | + in specified namespaces are affected. |
| | 59 | + * Property name# — Name of property to be used as title in the specified namespace. |
| 23 | 60 | |
| 24 | | -If a page in the specified namespace has the specified property (which should be of type `String'), |
| 25 | | -the visible title of the page is changed to the value of the property. |
| | 61 | +== Usage == |
| 26 | 62 | |
| 27 | | -The actual name of page is added to the beginning of page subtitle. |
| | 63 | +Being installed and configured, SemanticTitle handles page titles and links with no user |
| | 64 | +intervention. |
| 28 | 65 | |
| 29 | | -'''Note:''' The extension changes only ''visible'' name, it does ot change real name of the page. |
| | 66 | +However, category listings may look ugly, because listings show semantic titles while pages are |
| | 67 | +sorted in order of their actual titles. Use {{ DEFAULTSORT }} magic word to fix it, e. g.: |
| 30 | 68 | |
| | 69 | + [[Title::title]] |
| | 70 | + {{ DEFAULTSORT: title }} |
| | 71 | + |
| | 72 | +If you need semantic title of a page as plan text (not a link), use #semantic-title parser function: |
| | 73 | + |
| | 74 | + {{ #semantic-title: Bug:32758 }} |
| | 75 | + |
| | 76 | +Other extensions can call `SemanticTitle::getText( Title $title )' static function to get a semantic |
| | 77 | +title by given title. |
| | 78 | + |
| | 79 | + |
| 31 | 80 | == Caveats == |
| 32 | 81 | |
| 33 | | -`SematicTitle' overrides page title set by SemanticForms (specified by `edit title' parameter of |
| 34 | | -`{{{info ...}}}' construct). |
| | 82 | + * SematicTitle overrides edit page title set by Semantic Forms (specified by |
| | 83 | + `{{{info ...|edit title=...}}}' construct). |
| 35 | 84 | |
| 36 | | -* `Special:AllPages' shows unsorted list of pages (they are sorted in order of they real titles). |
| 37 | | - |
| 38 | 85 | == License == |
| 39 | 86 | |
| 40 | 87 | GNU Affero General Public License, version 3 or any later version. See `AGPL-3.0.txt' file for the |