User:Applicationswhisperer

The advice here is intended for folks who are new to MediaWiki, are using MediaWiki on a hosted site, and/or have little to no experience managing websites. Also, everything described here was completed from my laptop, using only the resources listed below. No command-line processes were executed in the building of these sites.

Last summer, we migrated existing online help content to MediaWiki, replacing a FrameMaker-to-RoboHelp solution that didn't work well for the PaaS services we offered. Result: LongJump Support.

Next, we set new goals:
 * build one MediaWiki instance that supports two products (similar services, different branding), i.e. one wiki, two sites
 * single-source the articles (i.e. write once, use many; conditional text/images)

We achieved our goal soon after:
 * http://lj.platformatyourservice.com/~platfor1/wiki/index.php?title=Main_Page
 * http://rn.platformatyourservice.com/~platfor1/wiki/index.php?title=Main_Page

(We're planning to add Short URLs soon)

Key Resources and Advice

 * Resources:
 * Manual:FAQ
 * MediaWiki announcements and site admin list
 * Since we do our wiki editing live, this combo saved the day: Text editor (TextPad, etc.), FireFox and the It's All Text] FireFox extension
 * Install these apps:
 * 7-zip to unzip .tar.gz file to my PC
 * FileZilla for ftp access
 * Choose a hosting provider; We used Siteground; They have helpful MediaWiki advice

Setup a Hosted Site and Domain Names

 * 1) Acquire a site; For the purposes of this article, my site name is: www.foo.com
 * 2) Install MediaWiki according to the excellent instructions at MediaWiki, as follows:
 * Download the latest copy of Mediawiki (filename: mediawiki-1.14.0.tar.gz)
 * 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</tt> folder on the hosted site, i.e. /www/wiki</tt>
 * 1) 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)
 * 2) Using FileZilla, create new folders (under /www</tt>, at the same level as /wiki</tt>):
 * /apples</tt>
 * /oranges</tt>
 * These folders are empty!!! However, they create these domain names: apples.foo.com</tt> and oranges.foo.com</tt>

Prep the Skin Files
The file edits in this section were created using FileZilla, modified to use TextPad as the default editor.

Open FileZilla and add the following folder/files in the /skins</tt> folder
 * {| border="1" cellpadding="5" cellspacing="0"
 * {| border="1" cellpadding="5" cellspacing="0"

/skins/monobook</tt> /skins/apples_monobook</tt>
 * Copy this...
 * ...and Paste as:

/skins/oranges_monobook</tt> /skins/MonoBook.deps.php</tt> /skins/apples_MonoBook.deps.php</tt>

/skins/oranges_MonoBook.deps.php</tt> /skins/MonoBook.php</tt> <tt>/skins/apples_MonoBook.php</tt>

<tt>/skins/oranges_MonoBook.php</tt>
 * }

Customize the Skins Files
With your handy-dandy text editor, customize the <tt>/skins/apples_MonoBook.php</tt> and <tt>/skins/oranges_MonoBook.php</tt> 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 <tt>CaPitaLIzaTIon</tt>. 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 {

Create Logo and Favicon Files

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

Customize <tt>localsettings.php</tt>

 * 1) In <tt>localsettings.php</tt> add this block of code at the end; It will set the sitename, based on hostname
 * 2) Install any other extensions, also at the end;

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

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

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

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

}

else if(($_SERVER['HTTP_HOST'])==('lj.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) ## (With my avatar as the logo, it makes me happy,   ##  and whatever makes me happy helps me be more effective) $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/sandbox.png";

}

Add any additional MediaWiki Extensions at the end of the file, after this section of code.

Try it Out
Congratulations, you have achieved a one-wiki, two-sites state! Next, build out the conditional content.
 * 1) Open one of the sites
 * 2) Login
 * 3) Add some content and save the page
 * 4) Open the second site, navigate to the page (you might need to refresh the page) and see the copy in the new skin.

Advanced MediaWiki Stuff to Know
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
With the site setup as defined, the following parser function example can be used to set conditional text, depending on the name of the site. With this concept, the conditional "chunks" can be images, images with text, text only, or whole pages -- you decide.

In the following example, <tt> </tt>


 * ''In this example, a page is transcluded:

Extensions We Use

 * ContactPage
 * TopTenPages
 * BreadCrumbs2
 * ParserFunctions

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, tho, 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.

It took a while to realize that none of the templates defined in MediaWiki or WikiPedia exist, and have to be added to the hosted instance. Doh!

Brand Template
Template:Brand plugs in the Apples or Oranges name whenever needed in an article: <!--contents of Template:Brand>

Within pages, use Template:Brand This is an article about the 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.


 * 1) Install the CategoryTree extension
 * 2) Build the following template pages

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

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
 * topic-n|Topic N
 * Category:Glossary|Glossary
 * 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
 * different-topic-n|Topic N
 * different-topic-n|Topic N
 * different-topic-n|Topic N

MediaWiki:Sidebar already exists. Replace the contents with:

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 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.

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 problems
 * I know just enough about DOS/UNIX commands to be dangerous
 * Until now, I have used other tools to create user documentation (FrameMaker, RoboHelp, DreamWeaver, Acrobat), plus some of the early programming languages...so, Fortran, Cobol and BASIC, yes ...PHP and mySQL, no, but learning very quickly

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

Applicationswhisperer 19:14, 3 April 2009 (UTC)