Extension:CollaborationKit/Technical documentation

CollaborationKit is a MediaWiki extension that uses ContentHandler, special pages, and EditPage extensions to make it easier to organize on-wiki projects.

Content models
CollaborationKit implements two novel content models: CollaborationHubContent and CollaborationListContent. Both of these content models represent data in JSON according to the schemas defined in CollaborationHubContentSchema.php and CollaborationListContentSchema.php respectively. Pages of either content type are validated against their respective schemas through the schema validation library in EventLogging. Note, however, that this library does not work perfectly, especially since it is not caught up with the latest version of the JSON Schema specification. There are long term plans to integrate a schema validation library in core MediaWiki and use that instead; see Requests for comment/JSON validation.

Each of these content models use a serialization format called text/x-collabkit for editing. The details depend on the content model, but the basic thing is that each high-level key-value pair is represented as one or more lines, separated by a specific number of hyphens, with the order of these blocks of text pre-determined by the serialization/deserialization methods. For sub-objects, key-value pairs are presented, one per line, as key=value. In some cases, this serialization is used to build the editing interface, minimizing exposure of code-like syntax to the user. The exact JSON stored in the database can be edited directly through the "Edit as JSON" tab, or through the  parameter in the edit URL.

Most forms of page interaction that exist with MediaWiki also work with these content models. They can be deleted, moved, etc. like other pages.

CollaborationHubContent
The CollaborationHubContent model represents "Collaboration Hubs," which are landing pages for on-wiki projects. Collaboration Hubs are essentially shell pages that then transclude other pages, including little content of its own.

A sample Collaboration Hub:

{   "display_name": "Project Hampshire", "introduction": "A WikiProject dedicated to the ceremonial county of Hampshire in the United Kingdom.", "footer": "", "image": "Flag_of_Hampshire.svg", "colour": "red", "content": [ {           "title": "WPX:WikiProject Hampshire/Requests", "image": "quotes", "display_title": "Requests" },       {            "title": "WPX:WikiProject Hampshire/Resources", "image": "book", "display_title": "Resources" }   ] }

Let's break this down:
 * display_name – a name to show other than the actual page title (optional)
 * introduction – Some introductory content. Supports any arbitrary wikitext.
 * footer – To display on the bottom of the page. Supports any arbitrary wikitext; you could use this for navboxes, categories, etc.
 * image – An image to serve as an "icon" for the project. Can be any image accessible on the wiki or a key for one of the "canned icons."
 * colour – Can be one of 23 preset colours. The image and colour collectively are the "hub theme"
 * content – the main body of the project. Each object in this array is a "feature," a project subpage containing something of interest to the project. The parameters for the content object include:
 * title – the full name of the page to transclude. Generally, features are subpages of the project, but they do not have to be!
 * image – an icon to use in the hub's auto-generated table of contents, typically one of the canned icons. As with the image parameter above, you could also use an on-wiki image for this (though it probably won't look as good)
 * display_title – Normally the subpage name would be displayed as the section header and table of contents item (e.g. "X" for "Project:Foo/X"), but this parameter lets you override that.

In addition to the named features, two additional pages are transcluded: the /Announcements subpage, which is wikitext, and /Members, which is CollaborationListContent. These subpages are created upon hub creation via Special:CreateCollaborationHub, but if those subpages don't exist, then the hub handles it gracefully. Announcements are shown below the introduction, members in a box to the right of the introduction, the table of contents and the transcluded pages below that, and the footer below that.

A note on feature transclusion behavior: there are different rules for how this works with different content models:
 * wikitext – Generic wikitext pages only have the lead section ("section zero") transcluded. This is intentional; this allows the lead to serve as a teaser or summary, with a link in the feature header that leads people to the full page contents.
 * CollaborationListContent – In the future this will be highly configurable, but for the time being, the default transclusion options are used, which are defined in the  method and currently are:
 * includeDesc (include list description text): false
 * maxItems (maximum number of items to show per column): 5
 * defaultSort: random
 * offset: 0
 * tags: none
 * mode: normal (as opposed to no-img)
 * showColumnHeaders: true
 * iconWidth: 64px
 * CollaborationHubContent – Only the hub image and hub introduction are presented. This is partly in keeping with the above principle but also because of implementation issues involving how the MediaWiki parser handles transclusion.

Special pages
CollaborationKit implements two special pages: Special:CreateCollaborationHub and Special:CreateHubFeature.