WPRDC Wiki

Difference between revisions of "Template:Extension/doc"

Template:Extension/doc (view source)

Revision as of 01:51, 17 November 2018

827 bytes added ,  01:51, 17 November 2018
migrate
>Shirayuki
(update)
>Shirayuki
(migrate)
Line 6: Line 6:
== Usage ==  
== Usage ==  


{| width="100%"
<table width="100%">
|-
<tr>
! width=40% |
<th width=40%></th>
! width=60% |
<th width=60%></th>
|- valign="top"
</tr>
| align="left" |
<tr valign="top">
<td align="left">
<span id="CutAndPaste">Copy and paste:</span>
<span id="CutAndPaste">Copy and paste:</span>
<pre>{{Extension |templatemode =
<pre>{{Extension |templatemode =
Line 54: Line 55:


For help with parameter values, see [[#Content parameters|below]].
For help with parameter values, see [[#Content parameters|below]].
 
</td>
| align="right"|{{Extension |templatemode=nocats
<td align="right">{{Extension |templatemode=nocats
|name            = {{{name}}}
|name            = {{{name}}}
|status          = {{{status}}}
|status          = {{{status}}}
Line 94: Line 95:
|pagedrive1      = true
|pagedrive1      = true
|demo            = true
|demo            = true
}}
}}</td>
|}
</tr>
</table>
<br style="clear:both"/>
<br style="clear:both"/>


Line 107: Line 109:
     If you change an id, please update the code in Template:Extension accordingly.
     If you change an id, please update the code in Template:Extension accordingly.
-->   
-->   
{| class="wikitable"
<table class="wikitable">
|+ '''Content parameters'''
<caption>'''Content parameters'''</caption>
|-
<tr>
! Parameter
<th>Parameter</th>
! Description
<th>Description</th>
|-
</tr>
|<span id="name">'''name'''</span> || '''name of the extension'''
<tr>
|-
<td><span id="name">'''name'''</span></td><td>'''name of the extension'''</td>
|<span id="status">'''status'''</span> || '''current release status'''
</tr>
<tr>
<td><span id="status">'''status'''</span></td><td>'''current release status'''
One of:  
One of:  
* ''[[:Category:Unstable extensions{{translation}}|unstable]]'' (broken - do not use this extension)
* ''[[:Category:Unstable extensions{{translation}}|unstable]]'' (broken - do not use this extension)
Line 125: Line 129:
* ''[[:Category:Extensions with unknown status{{translation}}|unknown]]'' (default)
* ''[[:Category:Extensions with unknown status{{translation}}|unknown]]'' (default)
If the status is anything other than the above, it will be ignored and the default value of 'Unknown' will be displayed in the template instead. In cases where the value is omitted, it will be categorized as [[:category:extensions with unknown status|unknown]]. In cases where the value is invalid, it will be placed in a [[:category:extensions with invalid status|special category]] so that the error can be caught and fixed.
If the status is anything other than the above, it will be ignored and the default value of 'Unknown' will be displayed in the template instead. In cases where the value is omitted, it will be categorized as [[:category:extensions with unknown status|unknown]]. In cases where the value is invalid, it will be placed in a [[:category:extensions with invalid status|special category]] so that the error can be caught and fixed.
* [[Extension status|release status colour scheme]]
* [[Extension status|release status colour scheme]]</td>
|-
</tr>
| '''type1'''<br/>''type2''<br/>''type3''<br/>''type4''<br/>''type5''<br/>''type6''<br/> || <span id="type">'''implementation type'''</span><!-- id here so at top of documentation -->
<tr>
<td>'''type1'''<br/>''type2''<br/>''type3''<br/>''type4''<br/>''type5''<br/>''type6''<br/></td><td><span id="type">'''implementation type'''</span><!-- id here so at top of documentation -->


The  implementation strategy(s) employed in building this extension. This parameter is used to create categories that help programmers find examples of various MediaWiki specific implementation strategies or patterns. Although the values of this parameter sometimes coincide with the use case or purpose of an extension, that is not reason for this parameter. If the values you have chosen for this parameter do not adequately identify the [[w:Requirements|purpose]] or possible [[w:Use case|use case]]s, we recommend you add additional [[Help:Categories|category links]] as needed.
The  implementation strategy(s) employed in building this extension. This parameter is used to create categories that help programmers find examples of various MediaWiki specific implementation strategies or patterns. Although the values of this parameter sometimes coincide with the use case or purpose of an extension, that is not reason for this parameter. If the values you have chosen for this parameter do not adequately identify the [[w:Requirements|purpose]] or possible [[w:Use case|use case]]s, we recommend you add additional [[Help:Categories|category links]] as needed.


Legal values for the '''type1''', '''type2''', ... parameters are:
Legal values for the '''type1''', '''type2''', ... parameters are:
Line 164: Line 168:
Any other value for 'type' is invalid, and will cause the extension to be placed in [[:Category:Extensions with invalid or missing type{{translation}}]].
Any other value for 'type' is invalid, and will cause the extension to be placed in [[:Category:Extensions with invalid or missing type{{translation}}]].


Note: Many extensions have more than one type, if this applies to yours, replace <code><nowiki>|type=</nowiki></code> with <code><nowiki>|type1=|type2=|type3=...</nowiki></code>. You may define up to six types for an extension.
Note: Many extensions have more than one type, if this applies to yours, replace <code><nowiki>|type=</nowiki></code> with <code><nowiki>|type1=|type2=|type3=...</nowiki></code>. You may define up to six types for an extension.</td>
|-
</tr>
| <span id="hook">'''hook1'''</span><br/>''hook2''<br/>''hook3''<br/>''hook4''<br/>...<br/>''hook30''
<tr>
|valign="top"| '''name of each hook used by the extension'''
<td><span id="hook">'''hook1'''</span><br/>''hook2''<br/>''hook3''<br/>''hook4''<br/>...<br/>''hook30''</td>
<td valign="top">'''name of each hook used by the extension'''


Entering values in this field is a good way to get exposure for your extension and help other developers. Each documented hook will automatically add the extension to a category listing extensions that use that hook. This category is autolinked to each hook article so that programmers can easily find examples of extensions that use a particular hook.
Entering values in this field is a good way to get exposure for your extension and help other developers. Each documented hook will automatically add the extension to a category listing extensions that use that hook. This category is autolinked to each hook article so that programmers can easily find examples of extensions that use a particular hook.
Line 177: Line 182:
* use ''extensionName''/''hookName''. For a partial list of custom hooks, see [[Extension hook registry]].   
* use ''extensionName''/''hookName''. For a partial list of custom hooks, see [[Extension hook registry]].   


For multiple hooks, assign the first hook to '''hook1''', the second to '''hook2''' and so on.
For multiple hooks, assign the first hook to '''hook1''', the second to '''hook2''' and so on.</td>
|-
</tr>
| <span id="newhook">'''newhook1'''</span><br/>''newhook2''<br/>''newhook3''<br/>''newhook4''<br/>...<br/>''newhook30''
<tr>
|valign="top"| '''name of each hook provided by the extension'''
<td><span id="newhook">'''newhook1'''</span><br/>''newhook2''<br/>''newhook3''<br/>''newhook4''<br/>...<br/>''newhook30''</td>
<td valign="top">'''name of each hook provided by the extension'''


You might also want to add the hooks to [[Extension hook registry]].
You might also want to add the hooks to [[Extension hook registry]].</td>
|-
</tr>
| <span id="username">'''username'''</span> || The author's username on MediaWiki.org (if they have one). May be omitted, but if present it will be used to link to the author's user & user_talk page. It should be provided without namespace and without <nowiki>[[]]</nowiki>s.
<tr>
|-
<td><span id="username">'''username'''</span></td><td>The author's username on MediaWiki.org (if they have one). May be omitted, but if present it will be used to link to the author's user & user_talk page. It should be provided without namespace and without <nowiki>[[]]</nowiki>s.</td>
| <span id="author">author</span>|| The extension author's name, if different from their MediaWiki.org username. Free text. If omitted then the 'username' field will be used (if present).
</tr>
|-
<tr>
| <span id="description">'''description'''</span>|| '''short description'''
<td><span id="author">author</span></td><td>The extension author's name, if different from their MediaWiki.org username. Free text. If omitted then the 'username' field will be used (if present).</td>
|-
</tr>
| <span id="image">image</span>|| screenshot or logo of extension. It should be provided without namespace and without <nowiki>[[]]</nowiki>s.
<tr>
|-
<td><span id="description">'''description'''</span></td><td>'''short description'''</td>
| <span id="imagesize">imagesize</span>|| ''facultative'', size of the image (default size is 220px)
</tr>
|-
<tr>
| <span id="version">version</span>|| last version
<td><span id="image">image</span></td><td>screenshot or logo of extension. It should be provided without namespace and without <nowiki>[[]]</nowiki>s.</td>
|-
</tr>
| <span id="update">update</span>|| date of the last update
<tr>
|-
<td><span id="imagesize">imagesize</span></td><td>''facultative'', size of the image (default size is 220px)</td>
| <span id="compatibility_policy">compatibility policy</span>|| {{ll|Compatibility#mediawiki_extensions|compatibility policy}} (accepted values are '''master''' and '''rel'''). ([[:Category:Extensions without a compatibility policy|backlog]])
</tr>
|-
<tr>
| <span id="mediawiki">mediawiki</span>|| required version of MediaWiki
<td><span id="version">version</span></td><td>last version</td>
|-
</tr>
| <span id="php">php</span>|| required version of PHP
<tr>
|-
<td><span id="update">update</span></td><td>date of the last update</td>
| <span id="needs-updatephp">needs-updatephp</span>|| '''''Yes''''' indicates that the extension requires a database table schema change or a similar action, before the MediaWiki can run. It is a common pitfall: your MediaWiki will stall, if you forgot to run update.php - if the extension requires it. '''''No''''' should be set as a value since this assures that the extension does not need update.php to be run and thus avoids uncertainty
</tr>
<tr>
<td><span id="compatibility_policy">compatibility policy</span></td><td>{{ll|Compatibility#mediawiki_extensions|compatibility policy}} (accepted values are '''master''' and '''rel'''). ([[:Category:Extensions without a compatibility policy|backlog]])</td>
</tr>
<tr>
<td><span id="mediawiki">mediawiki</span></td><td>required version of MediaWiki</td>
</tr>
<tr>
<td><span id="php">php</span></td><td>required version of PHP</td>
</tr>
<tr>
<td><span id="needs-updatephp">needs-updatephp</span></td><td>'''''Yes''''' indicates that the extension requires a database table schema change or a similar action, before the MediaWiki can run. It is a common pitfall: your MediaWiki will stall, if you forgot to run update.php - if the extension requires it. '''''No''''' should be set as a value since this assures that the extension does not need update.php to be run and thus avoids uncertainty


Extensions which conform to MediaWiki extension standards come with a '''schema change script which you need to start manually''' (once) before starting and accessing the MediaWiki through your browser, and after you copied all the extension files to <code>$IP/extensions/ExtensionName</code> and inserted <code>wfLoadExtension( "ExtensionName");</code> into "LocalSettings.php", run from the command line:
Extensions which conform to MediaWiki extension standards come with a '''schema change script which you need to start manually''' (once) before starting and accessing the MediaWiki through your browser, and after you copied all the extension files to <code>$IP/extensions/ExtensionName</code> and inserted <code>wfLoadExtension( "ExtensionName");</code> into "LocalSettings.php", run from the command line:
Line 212: Line 229:
  php update.php
  php update.php


{{TNT|$IP}}
{{TNT|$IP}}</td>
|-
</tr>
| <span id="php">composer</span>|| If applicable the name of the "vendor" as well as the "package" should be entered in the format <code>vendor/package</code>, e.g. <code>mediawiki/semantic-media-wiki</code> to point people directly to packagist.org, which serves as the package archive.
<tr>
|-
<td><span id="php">composer</span></td><td>If applicable the name of the "vendor" as well as the "package" should be entered in the format <code>vendor/package</code>, e.g. <code>mediawiki/semantic-media-wiki</code> to point people directly to packagist.org, which serves as the package archive.</td>
| <span id="table1">'''table1'''</span><br/>''table2''<br/>''table3''<br/>''table4''<br/>...<br/>''table30'' || '''name of each ''non-core'' table used by the extension'''
</tr>
<tr>
<td><span id="table1">'''table1'''</span><br/>''table2''<br/>''table3''<br/>''table4''<br/>...<br/>''table30''</td><td>'''name of each ''non-core'' table used by the extension'''


Links to a subpage of your extension page. For instance, "table1 = cu_changes" at [[Special:MyLanguage/Extension:CheckUser|Extension:CheckUser]] will link to [[Extension:CheckUser/cu_changes table]]. Don't list core tables such as [[Special:MyLanguage/Manual:Page table|page]] or [[Special:MyLanguage/Manual:Revision table|revision]]; only list tables that are added by extensions.
Links to a subpage of your extension page. For instance, "table1 = cu_changes" at [[Special:MyLanguage/Extension:CheckUser|Extension:CheckUser]] will link to [[Extension:CheckUser/cu_changes table]]. Don't list core tables such as [[Special:MyLanguage/Manual:Page table|page]] or [[Special:MyLanguage/Manual:Revision table|revision]]; only list tables that are added by extensions.</td>
|-
</tr>
| <span id="license">license</span>|| license governing use of this extension, as one of the codes found in https://spdx.org/licenses/, e.g. <code>GPL-2.0-or-later</code>, <code>GPL-2.0-only</code> or <code>GPL-3.0-or-later</code>, etc.
<tr>
|-
<td><span id="license">license</span></td><td>license governing use of this extension, as one of the codes found in https://spdx.org/licenses/, e.g. <code>GPL-2.0-or-later</code>, <code>GPL-2.0-only</code> or <code>GPL-3.0-or-later</code>, etc.</td>
| <span id="download">'''download'''</span>|| '''link to the download''' : [https://phabricator.wikimedia.org/r/project/mediawiki/core Git], {{tl|WikimediaDownload}} with server=svn in case it was not migrated from [[Subversion]]. If you put the code into page in the MediaWiki wiki, link to it using a full page name and section name, e.g. <code> <nowiki>[[Extension:Example/version_1.22a#Code]]</nowiki> </code> (it must remain valid when bot-copied elsewhere)
</tr>
|-
<tr>
| <span id="readme">readme</span>|| external link to the readme file, e.g. https://phabricator.wikimedia.org/r/browse/mediawiki/extensions/Flow;master;README
<td><span id="download">'''download'''</span></td><td>'''link to the download''' : [https://phabricator.wikimedia.org/r/project/mediawiki/core Git], {{tl|WikimediaDownload}} with server=svn in case it was not migrated from [[Subversion]]. If you put the code into page in the MediaWiki wiki, link to it using a full page name and section name, e.g. <code> <nowiki>[[Extension:Example/version_1.22a#Code]]</nowiki> </code> (it must remain valid when bot-copied elsewhere)</td>
|-
</tr>
| <span id="changelog">changelog</span>|| external link to the changelog file, e.g. [[Extension:LDAP Authentication/Changelog]]
<tr>
|-
<td><span id="readme">readme</span></td><td>external link to the readme file, e.g. https://phabricator.wikimedia.org/r/browse/mediawiki/extensions/Flow;master;README</td>
| <span id="parameters">parameters</span> || available parameters for LocalSettings.php
</tr>
|-
<tr>
| <span id="tags">tags</span> || any tags your extension uses (e.g. &lt;tag1&gt;, &lt;tag2&gt;).
<td><span id="changelog">changelog</span></td><td>external link to the changelog file, e.g. [[Extension:LDAP Authentication/Changelog]]</td>
|-
</tr>
| rights|| <span id="rights">rights</span> added by the extension. '''Not to be confused with the license!''' Rights are such as ''[[Special:MyLanguage/Extension:MakeBot|makebot]]'' or ''[[Special:MyLanguage/Extension:Desysop|desysop]]'', not such as GFDL or LGPL or GPL - those are licenses!
<tr>
|-
<td><span id="parameters">parameters</span></td><td>available parameters for LocalSettings.php</td>
| <span id="namespace">namespace</span> || namespace in which this extension is used
</tr>
|-
<tr>
| <span id="example">example</span> || example, website or screenshot of working extension
<td><span id="tags">tags</span></td><td>any tags your extension uses (e.g. &lt;tag1&gt;, &lt;tag2&gt;).</td>
|-
</tr>
| <span id="compatibility">compatibility</span> || Additional compatibility information, for instance compatibility charts (formerly using [[Template:Extension Testing]]). It's encouraged to add any client-side compatibility information here too, especially when diverging from [[Browser support|expectations of full support for a browser]].
<tr>
|-
<td>rights</td><td><span id="rights">rights</span> added by the extension. '''Not to be confused with the license!''' Rights are such as ''[[Special:MyLanguage/Extension:MakeBot|makebot]]'' or ''[[Special:MyLanguage/Extension:Desysop|desysop]]'', not such as GFDL or LGPL or GPL - those are licenses!</td>
| <span id="translate">translate</span> || Optional parameter to link the exact page where ([[Help:Extension:Translate/Glossary|message group id]] with which) the extension will be translatable on [[translatewiki.net]] if enabled. If the default link is incorrect, manually set it to:
</tr>
<tr>
<td><span id="namespace">namespace</span></td><td>namespace in which this extension is used</td>
</tr>
<tr>
<td><span id="example">example</span></td><td>example, website or screenshot of working extension</td>
</tr>
<tr>
<td><span id="compatibility">compatibility</span></td><td>Additional compatibility information, for instance compatibility charts (formerly using [[Template:Extension Testing]]). It's encouraged to add any client-side compatibility information here too, especially when diverging from [[Browser support|expectations of full support for a browser]].</td>
</tr>
<tr>
<td><span id="translate">translate</span></td><td>Optional parameter to link the exact page where ([[Help:Extension:Translate/Glossary|message group id]] with which) the extension will be translatable on [[translatewiki.net]] if enabled. If the default link is incorrect, manually set it to:
* ext-LOWERCASE(NOSPACES(Label as defined in {{git file|project=translatewiki|branch=HEAD|file=groups/MediaWiki/mediawiki-defines.txt|text=config}})), aka
* ext-LOWERCASE(NOSPACES(Label as defined in {{git file|project=translatewiki|branch=HEAD|file=groups/MediaWiki/mediawiki-defines.txt|text=config}})), aka
* the parameter you get in the URL after
* the parameter you get in the URL after
** typing the name of the extension in the search/filter box at [[translatewiki:Special:Translate]] or  
** typing the name of the extension in the search/filter box at [[translatewiki:Special:Translate]] or  
** searching for its name in [https://translatewiki.net/w/i.php?title=Special%3ALanguageStats&x=D languagestats] after clicking "expand all".
** searching for its name in [https://translatewiki.net/w/i.php?title=Special%3ALanguageStats&x=D languagestats] after clicking "expand all".</td>
|-
</tr>
| <span id="bugzilla">bugzilla</span> || Bugzilla MediaWiki extension component name
<tr>
|-
<td><span id="bugzilla">bugzilla</span></td><td>Bugzilla MediaWiki extension component name</td>
| <span id="phabricator">phabricator</span> || Phabricator project name
</tr>
|-
<tr>
| <span id="CheckUsageNameOverride">CheckUsageNameOverride</span> || override the page name used for the check usage link.
<td><span id="phabricator">phabricator</span></td><td>Phabricator project name</td>
|}
</tr>
<tr>
<td><span id="CheckUsageNameOverride">CheckUsageNameOverride</span></td><td>override the page name used for the check usage link.
</tr>
</table>


== Control parameters ==
== Control parameters ==
{| class="wikitable"
 
|+ '''Control parameters'''
<table class="wikitable">
|-
<caption>'''Control parameters'''</caption>
! Parameter
<tr>
! Description
<th>Parameter</th>
|-
<th>Description</th>
| '''templatemode''' || '''Controls auto-categorization of host page.'''
</tr>
<tr>
<td>'''templatemode'''</td><td>'''Controls auto-categorization of host page.'''


Normally left blank.  Alternate values are:
Normally left blank.  Alternate values are:
Line 267: Line 303:




If this is left blank, this template will add the host page to [[:Category:All extensions{{translation}}]] and to one or more additional categories, depending on the values assigned to the [[#Content parameters|Content parameters]].
If this is left blank, this template will add the host page to [[:Category:All extensions{{translation}}]] and to one or more additional categories, depending on the values assigned to the [[#Content parameters|Content parameters]].</td>
|}
</tr>
</table>


== Using the infobox ==
== Using the infobox ==
Anonymous user
Retrieved from "https://wiki.tessercat.net/wiki/Special:MobileDiff/11703"