Applicationswhisperer

In learning how to use and administer MediaWiki, I found that many of the Help articles were directed at folks who had an understanding of PHP and MySQL, and/or had years of developer experience. All of the command-line instructions were a bit intimidating to see. This article is intended for folks (like me) who are new to MediaWiki, are using MediaWiki on a hosted site, or have little-to-no experience managing websites.

As a technical writer, I follow the "See one, Do one, Teach one" philosophy of learning. This article is my "Teach one" advice to build an online help system using MediaWiki on a hosted site.

How we Built Two Help Sites from One Instance of MediaWiki

Backstory

In the spring of 2008, I was tasked with replacing an online help system (based on FrameMaker/RoboHelp) with a MediaWiki-based solution. I had no prior experience with MediaWiki, but didn't let that stop me.

Phase I

As with most projects, it took more time than anticipated, however, once we procured a hosted site and installed MediaWiki, I quickly became familiar with the basic editing and formatting syntax. Significant effort was spent reorganizing the existing help documents to fit an improved category scheme.

Finally, the help content was imported, and we launched the site. It was designed to behave as most context-sensitive help systems do: when the user clicks a Help link/icon in a web-based application, a new page opens with the relevant help content. Happy to say, this was successful and the MediaWiki-based help system went live in August 2008.

Phase II

Flush with our success, we set new goals:

build a single MediaWiki instance that supports two products, i.e. one wiki, two sites
single-source the articles (using conditional pages, text, images and navigation)

We found that with these MediaWiki features: Templates, Magic Words and ParserFunctions, we could achieve our goal of single-sourcing one wiki, supporting two sites. Here are the results of that effort:

How to Build an Online Help System using MediaWiki on a Hosted Site

How did we do it? Read on to learn more.

Key Resources and Advice

Resources:
- Wikipedia:Cheatsheet
- Help:Contents
- Wikipedia User Page Design Center
- MediaWiki announcements and site admin list
- Manual:Wiki_family
- For Editing: FireFox and the It's All Text] FireFox extension, plus a Text editor (TextPad, Notepad++, etc.)

Update on editors: Our users like FCKeditor Extension because it offers a WYSIWIG interface

Install these apps:
- 7-zip to unzip .tar.gz files to my PC
- FileZilla for ftp access (PC <-> Hosted Site)
Choose a hosting provider; We used Siteground; They have helpful MediaWiki advice

Setup a Hosted Site and Domain Names

The instructions here assume you want to create two websites that are built on a single MediaWiki database, i.e. Phase II

Acquire a site; For the purposes of this article, my site name is: www.foo.com
- Your hosting provider may offer to install MediaWiki (say yes)
- Because mediawiki.org offers periodic upgrades, it's good practice to understand How to Install MediaWiki Upgrades
Using FileZilla, create new folders (under /www, at the same level as /wiki):
- /apples
- /oranges
These folders are empty!!! However, they create these domain names: apples.foo.com and oranges.foo.com

Prep the Skin Files

Alternate advice to create new skin files: MediaWiki Look And Feel - Creating a Skin Based on MonoBook

This is what I did (via the PC, with the usual MS Windows commands):

Copy this...	...and Paste as:
`/skins/monobook`	`/skins/apples_monobook` `/skins/oranges_monobook`
`/skins/MonoBook.deps.php`	`/skins/apples_MonoBook.deps.php` `/skins/oranges_MonoBook.deps.php`
`/skins/MonoBook.php`	`/skins/apples_MonoBook.php` `/skins/oranges_MonoBook.php`

Customize the Skins Files

With your text editor, customize the /skins/apples_MonoBook.php and /skins/oranges_MonoBook.php files with the following code; This code is is located near the beginning of the file; The following code is (obviously) a sample for Apples. Build the Apples files and do it again for Oranges. Pay attention to CaPitaLIzaTIon. Also, note that there are five places in this code that need to be tweaked:

/**
 * Inherit main code from SkinTemplate, set the CSS and template filter.
 * @todo document
 * @ingroup Skins
 */
class SkinApples_MonoBook extends SkinTemplate {
	/** Using monobook. */
	function initPage( &$out ) {
		SkinTemplate::initPage( $out );
		$this->skinname  = 'apples_monobook';
		$this->stylename = 'apples_monobook';
		$this->template  = 'Apples_MonoBookTemplate';
		# Bug 14520: skins that just include this file shouldn't load nonexis-
		# tent CSS fix files.
		$this->cssfiles = array( 'IE', 'IE50', 'IE55', 'IE60', 'IE70', 'rtl' );
	}
}

/**
 * @todo document
 * @ingroup Skins
 */
class Apples_MonoBookTemplate extends QuickTemplate {

Load the Skins Folder to the Hosted Site

Launch FileZilla and upload the following from your PC to the /skins folder on the server:

Folders:

/skins/apples_monobook
/skins/oranges_monobook

Files:

/skins/apples_MonoBook.deps.php
/skins/oranges_MonoBook.deps.php
/skins/apples_MonoBook.php
/skins/oranges_MonoBook.php

Create Logo and Favicon Files

These images/files create a graphic personality for your sites.

Create apples_logo.png file and place it in this folder: skins/common/images/
Create oranges_logo.png file and place it in this folder: skins/common/images/
Create apples_favicon.ico file and place it in this folder: /www/wiki/ root (i.e. $wgScriptPath in this example)
Create oranges_favicon.ico file and place it in this folder: /www/wiki/ root (i.e. $wgScriptPath in this example)

Customize `localsettings.php`

In localsettings.php add this block of code at the end; It will set the sitename (Apples Support or Oranges Support) based on the hostname (apples.foo.com or oranges.foo.com)
Install any extensions after this code

####
# added to resolve Apples vs Oranges parserfunction issues on the home page
$wgEnableParserCache = false;
$wgCachePages = false;


#
# Choose the wiki support site, based on the host name (apples.foo.com or oranges.foo.com)
#
if(($_SERVER['HTTP_HOST'])==('apples.foo.com'))
{
    $wgSitename = 'Apples Support';
    $wgLocalInterwiki   = $wgSitename;
    ## Default skin for Apples

    $wgDefaultSkin = 'applesmonobook';
    $wgLogo = "skins/common/images/apples_logo.png";

    $wgFavicon = "$wgScriptPath/apples_favicon.ico";

}

else if(($_SERVER['HTTP_HOST'])==('oranges.foo.com'))
{
    $wgSitename = 'Oranges Support';
    $wgLocalInterwiki   = $wgSitename;
    ## Default skin for Oranges

    $wgDefaultSkin = 'orangesmonobook';
    $wgLogo = "skins/common/images/oranges_logo.png";

    $wgFavicon = "$wgScriptPath/oranges_favicon.ico";

   
}
else
{
    ## For convenience, all edits are conducted from (wiki.foo.com)
    ## I use a goofy logo and the monobook skin as the default
    ## 
    $wgSitename = 'SandBox Support Wiki';
    $wgLocalInterwiki   = $wgSitename;
    ## Default skin: you can change the default skin. Use the internal symbolic
    ## names, ie 'standard', 'nostalgia', 'cologneblue', 'monobook':

    $wgDefaultSkin = 'monobook';
    $wgLogo = "skins/common/images/sandboxlogo.png";

}

Extensions

We use these Extensions:

CategoryTree
ContactPage
TopTenPages
BreadCrumbs2
ParserFunctions
FCKeditor (Official)

In order for the site to work as promised, both the CategoryTree and ParserFunctions extensions must be installed.

Installing Extensions

Easy, once you know how. Generally, there are two steps to installing a MediaWiki Extensions:

Download/save a .php file to the /extensions folder on your site; common situations:
- If a download link is provided, download and save the file to your local drive (then unzip it if it's a compressed file/folder set)
- If there is a big chunk of code displayed in the extensions page, copy and paste the code into a file (use a text editor), and save the file to your local drive (make sure to create the filename exactly as indicated)
- After you have the file/folder set saved to your local drive, use FileZilla (ftp) to copy the files to the /extensions folder on your site
Add the specified line of code to the end of the localsettings.php file; the exact code will be specified in the extensions page

Try it Out

Open one of the sites
Login
Add some content and save the page
Open the second site, navigate to the page (you might need to refresh the page) and see the copy in the new skin.

Congratulations, you have achieved a one-wiki, two-sites state! Next steps:

add several more test pages
add categories to a few pages
build out the conditional content

How to Install MediaWiki Upgrades

Before installing an upgrade, use FileZilla to backup the following to your local computer:

/skins folder
localsettings.php file
/images folder
.ico favicon images

Because these files and folders will be overwritten during install/upgrade, change each of the folder names, so you don't have to copy the files back to the server.

Install MediaWiki according to the excellent instructions at MediaWiki Installation, as follows:
- Download the latest copy of Mediawiki (filename: mediawiki-1.14.0.tar.gz in this example)
Extract the mediawiki-1.14.0.tar.gz file to a folder on your PC; To do this, hover the cursor over the file, right-click and select 7-Zip, choose Extract Files; Click [OK] (trust the defaults)

Open the \mediawiki-1.14.0.tar folder and use 7-Zip again, to unzip the mediawiki-1.14.0.tar file

The result is a folder named: \mediawiki-1.14.0
- Using FileZilla, copy the contents of the \mediawiki-1.14.0 folder to the /wiki folder on the hosted site, i.e. /www/wiki
In a browser window, navigate to your wiki site and install MediaWiki (this can take a while for first-timers; Great guide here: Siteground Knowledge Base)
Restore your original /skins folder and /images folders:

Delete the (newly created) /skins folder and /images folders
Rename your original folders to use /skins and /images
Edit the localsettings.php file
Rename the .ico favicon images

Advanced MediaWiki Stuff for Conditional Content

Read about Templates, Magic Words and ParserFunctions - they are key to building a single-sourced site.

Parser Functions

If you're familiar with building conditional text in a publishing application, parser functions can do the same thing:

substitute page content, based on the site name
substitute brandname/feature/spec, using parser functions in a template
Change the Sidebar, based on site name

Substitute Page Content

Assuming the site is set up as defined previously, the following parser function example can be used to build conditional text; the sitename is used as the test criteria. With this concept, the conditional "chunks" can be images, images with text, text only, or whole pages -- you decide. Users of apples.foo.com will see apples-related content, and oranges.foo.com users will see oranges content.

In the following example, 

 
{{ #ifeq: {{SITENAME}} 
 |Apples Support
 |<!--include text here related to the Apples page-->
 |<!--include text here related to the Oranges page
      Articles can go on and on, and include Images: [[Images:logo.gif]],
      or anything else whatsoever-->
 }}

In this example, a page is transcluded:

 
{{ #ifeq: {{SITENAME}} 
 |Apples Support
 |{{:Introduction to Apples}}
 |{{:Introduction to Oranges}}
 }}

CSS for Dummies

Get friendly with your local web developer. Provide a copy of the monobook folder and ask for whatever css cusomizations strike your fancy. Don't go wild, because making major changes will break some extensions. My advice is to stay with basic fonts and colors, logos and favicons. We went very zen: (LongJump Support).

About Templates

Templates are powerful tools that support the single-source model.

A cautionary tale about templates

This guide is very useful and is a great starting point to understanding templates: Help:Template. I learned the hard way that templates defined in MediaWiki or Wikipedia must be added to your hosted instance. Doh!

Brand Template

Template:Brand plugs in the Apples or Oranges name whenever needed in an article. As a parser function, it compares the SITENAME with the first value Apples Support. If it's a match, the term Apples is used, otherwise, Oranges:

<!--contents of Template:Brand>
{{ #ifeq: {{SITENAME}} 
|Apples Support
|Apples
|Oranges
}}

Within pages, use Template:Brand as follows:

This is an article about the {{Brand}} industrial-strength power of bla-de-bla...

Which results in an article containing one of the following, depending on the URL they visited:

This is an article about the Apples industrial-strength power of bla-de-bla...
This is an article about the Oranges industrial-strength power of bla-de-bla...

When viewed in the Apples or Oranges skin, it's seamless. And, if the brand names change in the future, just change the template, and ALL instances will be updated with the new content when the page is viewed.

Using ParserFunctions with CategoryTree

This section describes how to have a custom sidebar in each site, based on the sitename.

Install the CategoryTree extension
Build the following template pages

Template:Tree chooses which category tree to display in the SideBar (based on Category Tree extension):


{{ #ifeq: {{SITENAME}} 
|Apples Support
|{{Apples}}
|{{Oranges}}
}}

Template:Apples contains the Apples site SideBar:

* navigation
** mainpage|Main Page
** topic-1|Topic 1
** topic-2|Topic 2
** .
** .
** .
** topic-n|Topic N
** Category:Glossary|Glossary

Template:Oranges contains the Oranges site SideBar:

* navigation
** mainpage|Main Page
** different-topic-1|Topic 1
** different-topic-2|Topic 2
** .
** .
** .
** different-topic-n|Topic N

MediaWiki:Sidebar already exists. Replace the contents with:

{{tree}}

With these Templates (Apples, Oranges and Tree), the sidebar will reflect the CategoryTree structure of each site. Because the concept of Categories is so powerful, the trees can be radically different, even though they are built from the same wiki database.

Project History

When I started this project, the RoboHelp content was six months out of date
First milestone: Pull RoboHelp articles into MediaWiki

I tried the robo2wiki extension, but the RH site had many pop-ups and fold-out content, so the result in MW was very ugly, with jillions of tiny articles from all the pop-ups, plus similar-but-different redundant content
The best result was exporting RH to PDF, then copying and pasting from PDF into MW...cumbersome, but it allowed me to become familiar with the materials, and identify needed art and category topics
The result was that I could consolidate redundant content, and build a single MW page; These pages could be cross-referenced from an article, or used as a template for inclusion into a larger overview article

In the following months, I added extensions and learned the subtleties of templates and parser functions

Disclaimer: Everything described here was completed from my laptop, using only the resources listed ...no command-line processes were executed in the building of these sites.

About Me

I have experience in product marketing, user training, technical communications and support desk operations:

I am comfortable diagnosing and solving most user-level PC/application issues
I know just enough about DOS/UNIX/LINUX commands to be dangerous
Until now, I have used other tools to create user documentation (FrameMaker, RoboHelp, DreamWeaver, Acrobat Suites), plus some of the early programming languages...so, Fortran, Cobol and BASIC, yes,...PHP and mySQL, not so much, but learning very quickly

Currently, I'm a technical writer in the SF Bay area. Contact me at eyoder at gmail dot com.

I recently installed WAMP - very cool - I can play with the wiki locally. Applicationswhisperer 19:14, 3 April 2009 (UTC)