Open main menu

Extension:OCExtensions

MediaWiki extensions manual
OOjs UI icon advanced.svg
Outreach Connections Extensions
Release status: stable
Implementation User interface
Description A small suite of extensions that make the UI more friendly, especially if your wiki is geared toward an audience that prefers to fill out forms rather than use wiki text (i.e. for templates).

Although this is marked stable, you WILL need to modify the code to suit your wiki. Think of these extensions as a starting point for your project, rather than something that is ready-to-go.
Author(s) Scott Horlbeck (shorlbecktalk)
Latest version 1.0
MediaWiki 1.13.x
License GNU General Public License 3.0 or later
Download Download tar.gz
Download zip
Example http://native.outreachconnect.info/wiki
Translate the OCExtensions extension if it is available at translatewiki.net
Check usage and version matrix.

These extensions are no longer under active development, but that doesn't mean they are unusable, and you may be able to learn a lot from them. Improve upon them!

Outreach Connections ExtensionsEdit

This is the main page for a suite of extensions that was originally written for Outreach Connections: Native Health Information (aka OC). The intended audience of Outreach Connections has very little technical experience and thus finds wiki text very cumbersome and daunting. These extensions were written and intended to:

  1. make it easier to include a standard template, with parameters supplied by the user, on every page.
  2. improve usability for users that are intimidated by wiki text, especially template wiki text.
  3. to integrate well with FCK Editor and the CategoryTree extension.

I have tried to make these extensions as abstract as possible, and as easy to customize as possible, in order to benefit the open source community, so hopefully you will find them easy to integrate... BUT, just in case, you should be aware that you may need to make significant modifications to order to get them working according to your needs. Plan on spending a significant amount of time customizing them.

BY DEFAULT, THIS LIBRARY WILL REMOVE THE "SHOW CHANGES" BUTTON THAT APPEARS AT THE BOTTOM WHEN EDITING A PAGE. (The complexity of integrating these extensions with FCK Editor made me decide to nix the "Show Changes" option. You can re-enable it if you wish, but if you are using FCK Editor you will probably run into bugs.)

 
Example of a form generated by the OCProjectInfo extension.

IntroductionEdit

In my experience, average non-technical users find wiki text very intimidating. They are accustomed to using word processors such as Microsoft Word or Open Office. FCK Editor helps smooth the transition for these users, but the use of templates still requires wiki text, and it is very confusing to a lot of users.

Let's say you have a site-wide template called ocproject, which should appear on every page in the main namespace, and it requires the user to enter parameters, like so:

{{ocproject
|projectname = Granger Range Health Study
|startdate   = 2008-01
|enddate     = 2010-01
|tribe       = Cherokee
|tribe2      = Chickesaw
|tribe3      = Apache
|tribe4      = Navajo
(etc...)
}}

To make it easier for non-technical users to add this template to their page, the OC extensions contain a PHP class that will help you add a user-friendly form before the main editing area. This is the core functionality of the OC extensions. Additional functionality is documented below.

Individual DescriptionsEdit

What follows is a brief description of each extension in this suite.

OCProjectInfo and OCContactInfoEdit

The most prominent extension in this suite is OCProjectInfo, followed by OCContactInfo, which is similar, but without the AJAX interface. Most likely, you are not going to want to use these extensions as they exist in the snapshot, since they are highly specific to the Outreach Connections wiki. Instead, think of them as a starting point for creating and introducing your own forms into your edit page. You can rename them if you want (requires a bit of code modification), or just change the content to suit your needs. You can also create your own "OC" extensions based off of them, by extending the OCInfo class.

Both of these extensions contain a Settings file that allows you to define the field labels on the form. This should be your starting point (after you follow the installation instructions below). For more information, see the included documentation.txt file located in the same directory as the settings file.

What follows is a description of each, to give you a better starting point.

OCProjectInfoEdit

OCProjectInfo injects an HTML form into the edit page before the main textarea on every page in the main namespace. When you fill out the form and submit the page, it converts everything the user entered into wikitext, which gets prepended to the article text before it is saved. An example of the generated wikitext would be:

{{ocproject
|name     = A Health Study
|agency   = A Funding Agency
|contact  = Joe Blow
|contact2 = John Doe
}}

This functionality was needed because Outreach Connections' main namespace is dedicated to posting information gleaned from health sciences projects around the country, and it needed to have a standardized template on each page.

OCProjectInfo contains an AJAX interface that adds an auto-suggest box below each textbox in the form. It's a really cool interface, but the implementation is complex and you are unlikely to be able to use it without some major work, first because the template that was designed to receive the data puts everything into a category which is then further categorized by a bot (which I may not include in the download), and second because I doubt I will have time to document it.

OCContactInfoEdit

OCContactInfo is similar to OCProjectInfo in that it injects an HTML form into the edit page before the main textarea, but rather than doing it on every page in the main namespace, it does it in the category: namespace, and only on category pages that belong to category:contact. The idea behind this was to store contact information in a central place on the wiki, and to provide a user-friendly form for data entry. You may find this extension to be quite handy if you have similar needs on your wiki.

OC-CommonEdit

The core of the OC Extensions is OC-Common, which doesn't really do much on its own. It contains a PHP class called OCInfo, as well as javascript functions, all of which are required by the other OC extensions that generate HTML forms. So, if you want to create a custom form that will convert its input into wiki text (for template parameters), you can create as many of your own OC extensions as you want by placing each one in the directory "[path-to-your-mediawiki-installation]/extensions/OC/[your-OC-Extension-Name]/", and then extend the OCInfo class. (Details to come.) You can study OCContactInfo and OCProjectInfo for examples on how to do this.

Here is what the OC-Common extension itself will do:

  • Adds a CSS class to the HTML table displayed at special:allpages. (<table class="special_allpages">)
  • Adds a permanent sandbox header to the sandbox page (assuming you have a template called template:Please leave this line alone and a sandbox located at $wgSiteName:Sandbox). The reason for doing this (in an extension, rather than on the sandbox page in the wiki itself) is to prevent new users from being confused when they see a line that says, {{please leave this line alone}}. New, non-technical users do not understand what this is there for, and why this does not show when the page renders. It also creates an ugly template icon if using FCKeditor, which new users are likely to delete accidentally.
  • Adds a warning to the "Create User" page and the "Change Password" preferences section, telling the user to "pick a password unique to this site."

OCAddProjectEdit

OCAddProject will give your wiki a special page that will make it more intuitive for users to add a page to the main namespace. You will probably want to put a link to it in the main navbar (go to mediawiki:sidebar in your wiki to do so). The reason it is called "Add Project" is because every page in the main namespace on Outreach Connections is a "project" page (rather than an "article," as with most wikis). You may wish to change the text of the new special page by editing the OCAddProject.i18n.php file.

OCAddTeachingMaterialsEdit

OCAddTeachingMaterials is a simple extension used to make the process of adding subpages (aka "Teaching Materials" on Outreach Connections) more intuitive. It adds a link to the bottom of every page in the main namespace, which users can click on in order to add a subpage to each page.

Does not depend on the OCInfo class.

This extension is best used in conjunction with the SubPageList3 extension (optional, but highly encouraged).


InstallationEdit

Each extension within the OC suite is a fully independent extension (aside from the OCInfo class in OC-Common, which most of them depend on). To install, follow these steps.

Step 1: Create Templates in Your WikiEdit

You will need to make sure that you have pre-existing templates in your wiki that have the parameters your forms are designed to fill. You will most likely want to create your own, but if you want some samples for reference, you will find, included in the download, two xml files that were exported from the OC wiki, which can be imported into the template namespace (look in the OCContactInfo and OCProjectInfo directories). These will give you an idea of what types of templates these extensions are designed to help fill out. Note that you will also need the Parser Functions extension installed if you want to take advantage of the conditional logic in these templates. Alternatively, you can just view the source here: ocproject template and here: occontact template. You are not required to use these templates -- you can create your own template with parameters of your own choosing and any layout you wish.

Step 2: Determine Which Extensions You WantEdit

Look over the descriptions of each extension above, and decide which ones you want. There is a Settings file for OCProjectInfo and OCContactInfo that you will want to modify to suit your wiki -- start here. After that, you will want to determine which namespace(s) the forms should appear in. This is going to require some modification to the code; you will have to modify the child classes.

Step 3: Modify Local SettingsEdit

Add the following to LocalSettings.php:

# setup user rights first, if necessary
# ...
# ...

# Autoload the OCInfo class, which is the back-bone of all OC Extensions
$wgAutoloadClasses['OCInfo'] = "$IP/extensions/OC/OC-Common/OCInfo.class.php";

# OC Extensions - add/remove individual OC extension names here.
$OCExtensions = array(
	'OC-Common',
	'OCProjectInfo',
	'OCContactInfo',
	'OCAddProject',
	'OCAddTeachingMaterials'
);

# Automatically gets each extension listed above.
foreach ($OCExtensions as $extension) {
	require_once("$IP/extensions/OC/$extension/$extension.php");
}

Note that we add OCInfo to the $wgAutoloadClasses array manually, in LocalSettings.php. I could have just made the OC-Common extension itself do this, but the OC-Common extension performs a few minor utility functions on the site that you may want to disable by removing it from the $OCExtensions array.