User:PerfektesChaos/js/citoidWikitext/software/wikiProject

Creating a plug-in for a particular wiki project to run citoidWikitext.

Project dependant template specfications and other adaptions need to be provided. The plug-in will receive the common results of the investigation, and shall determine whether and how that shall be inserted into the wikitext source.

Project identifier

Each WMF wiki has a unique identifier by database name, which is available for JavaScript by wgDBname configuration specifier.

Typical values are:

• enwiki for English Wikipedia
• dewiki for German Wikipedia
• frwikisource for French Wikisource

This code is referred on this page as wikiDB placeholder.

Requirements

• Every plug-in is supposed to provide the Resource Loader module identification ext.gadget.citoidWikitext/wikiDB as soon as possible; beginning with loading and ready when built.
• The function mw.libs.citoidWikitext.wikiDB.fire() has to be supported as specified below.

Source code location

There are three ways to provide the plugin code.

1. By default, registered projects are expected at the tool’s root directory:

   w:en:User:PerfektesChaos/js/citoidWikitext/wikiDB/r.js

   That may consist of two statements:

   1. declare loader state to be still loading
   2. load from any other place, e.g. project’s MediaWiki space or trusted user page or anywhere else.

2. By previous external activities, Resource Loader module identification may have been satisfied.
   • This may be used to provide own forks, e.g. for testing or debugging, and goes for all modules.
3. A string value at the JS variable component was set in advance:

   mw.libs.citoidWikitext.wikiDB

   This is supposed to be a URL which resolves to something which is returning text/javascript MIME type.

Minimum functionality

Plug-in object

A JS variable component is set to be an object (non-null):

mw.libs.citoidWikitext.wikiDB

.fire()

Within the plug-in object the following function has been defined:

mw.libs.citoidWikitext.wikiDB.fire( results )

• results – Array of citoid server results
  • results[ 0 ] – combined and enhanced result
  • Further elements of results are distinctive results, when multiple query URLs have been sent to server.
• Return value: Array, string, or false.
  • false – no meaningful text insertion could be derived from these results.
  • Array, with elements:
    • [ 0 ] – Array, with elements describing the entire template:
      • [ 0 ] – string, with template title or any page name
      • [ 1 ] – boolean, on multi-line insertion
        • true – permit multiple lines
        • false – always compact
      • [ 2 ] – boolean, on bibSection option
        • true – offer bibSection unordered list
        • false – do not mention
    • [ n ] – Array, with elements describing one single parameter for n>0:
      • [ 0 ] – string, with parameter name (currently no unnamed parameters expected, but might be supported by false)
      • [ 1 ] – boolean, on empty values
        • true – show empty parameter assignment, even in compact mode
        • false – never show empty parameter assignment
      • [ 2 ] – string, with parameter value, or false or null
  • string, with preformatted insertion text
    • No bibSection option.

It is up to the wiki project to determine how to react on a result.

Stated as ready

The Resource Loader module identification

ext.gadget.citoidWikitext/wikiDB

pretends to be ready.

Extended functionality

Templates on input

The plug-in object may contain a component templates as object:

mw.libs.citoidWikitext.wikiDB.templates

That object may contain functions like this:

mw.libs.citoidWikitext.wikiDB.templates.Google_books()

This function will be called, if a template of this name has been chosen for input.

• One string as input parameter, starting with first pipe or terminating brackets of template transclusion.
• Supposed to return a URL or other keyword/data, or false.

The .core.fold() utility below might help.

Common library

For the benefit of plug-in programmers, a set of public components of the application object is provided.

.core.fold()

Derive simple template parameter assignments; not nested, no links.

Available from beginning.

• One string as input parameter, starting with first pipe or terminating brackets of template transclusion.
• Returns object, with parameter components identified by strings

.opus.fetch( assembly, access )

Retrieve string value from query result

• assembly – object, with query result
• access – string, with component name

.opus.figures( apply )

Format list of comma-separated hyphen-joined number ranges

• apply – string, or not

.opus.fork( array )

Duplicate template definition Array

• array – Array with basic citoid query

.opus.format( assembly )

Guess URL content type, like PDF

• assembly – object, with citoid server result

.opus.freeze( amount )

Retrieve ISO 8601 string of current date and time

• amount – Number of digits; 10: date

The .opus components are available for result evaluation only.

Sandbox

If the project sandbox like WP:Sandbox shall be equipped by default, it needs to be registered at d:Q3938.