User:Aeric/Customizing

About Customizing

These features are used to customize the wiki for generic ISV use, or for a branded wiki.

Branded and Unbranded Versions for the Platform

To create a branded version of the Wiki for a particular ISV:

1. First, set up a subdomain for the ISV.
   Every customization is controlled by the use of that

subdomain when accessing the common Wiki. For example, lj.platformatyourservice.com and isv.platformatyourservice.com both go to the very same place--but the different subdomains changes the wiki's look and content.

2. Then customize the look and feel for that brand.

3. Finally, take care of the Wiki content.

Note: All changes should be made locally, and then uploaded to the server. Note, too, that it would be highly desirable to test the changes before uploading them. To do that, it is necessary to set up a server that runs the local copy of the files. (One day, this too shall be done...)

Branded and Unbranded Versions for Specific Products

To create a branded version of the Wiki for a particular application:

1. Create a new domain for that product.
2. Customize the look and feel for that product
   For example, sidebars that have product-centered links only, rather than links to generic design and development pages.
3. To link to generic platform design & development pages, use external links ([url name]) rather than internal links ([[page name]]). (The Google page search should then confined to the product pages, since they're no longer in the same domain.)

Problem to solve:

• If the domain reflects the brand name, there is no such thing as an "unbranded" wiki, or one that has a particular ISV's brand, because the URL always indicates the product.
• Either of those options requires a neutral domain like "platformatyourservice.com, or "platforminfo.com".
• But those neutral domains indicate "platform", rather than "product", so a new neutral domain is needed. Call it neutral.com, for now.
• It will be hard to come up with a new neutral domain for each product, so a single neutral domain is needed.
• We then need a product-branded version of the Wiki for our use. But we also need to allow for an ISV-branded product version of the wiki. At the very least, we need to allow for a whitewashed, brand-free version of the product wiki that ISVs can access.
• To do everything right, we need a matrix of subdomains: isv-product.neutral.com and product.neutral.com, for example, in addition to lj.neutral.com and isv.neutral.com.
• At this point, though, we're using {product}.info for the product-branded version of the wiki.

Prerequisites

You'll need to have these things handy to set up the customized version:

• Content Controls
  • What brand name replaces the "AgileApps Cloud platform"? (EnterpriseBrand--always follows the word "the", typically followed by "platform".)
  • What label replaces "LongJump" in the Eclipse Plugin? (BrandLabel)
    (and in email-sync, when enabled.)
  • What brand name to use for the Service and Support application? (HelpDesk)
    • Always follows the word "the"
    • HelpDesk is the original default.
    • It requires extra work to make a branded version of the HelpDesk page, so don't change it, if possible
      (A new page needs to be created for the branded version, and {{:Common:HelpDesk}} content needs to be transcluded into it.)
  • Are the branded whitepapers available?
  • Should development information be displayed (Eclipse plugin, APIs, classes, etc)
  • Should ISV info be displayed?
  • Should MSP info be displayed?
  • Should a training link be displayed? (TrainingLink) If so, where should it point?
• Font Style (Wiki default is "Sans Serif")
• Color of horizontal & vertical bars on Welcome page (default is lime green)
• Logo image
  • Displays in upper left of every page.
  • 160 pixels wide x 135 high. Any format browsers can handle.
• Icon image
  • Displays in the browser's address bar, in bookmarks, and in browser tabs
  • 32 x 32 pixels, .ico format (icon format)
  • Create using the free[ http://icofx.ro/ IcoFX] utility
• TBD
  • Support Link
  • Content of Subscription Summary page
  • Recipient of Wiki Feedback, if any (currently, this feature is disabled)

Set Up a Subdomain

The subdomain is the master switch that turns on everything else.

1. In UltraDNS, add a DNS entry for the subdomain

   (Directs the subdomain-URL to the HOST IP address).

   • Access CPanel Securely > Subdomains
   • Create subdomain: {name} (lowercase)
   • Document root: public_html

2. At the bottom of mediawiki.conf, add a subdomain entry to the <VirtualHost> tag:
   • ServerAlias {name}.platformatyourservice.com
   • Process:

   a. In www/apache_config, edit mediawiki.conf_new

   b. Upload the file

   c. In PuTTY, cd /usr/share/mediawiki/apache_config

   d. Use ./try to test it. Use ./revert to go back to the previous version.

   e. When changes are tested, cp mediawiki.conf_new mediawiki.conf_sav.

   (The new version is now the version you'll revert to, the next time you test changes.)

   r. Also copy it to mediawiki.conf_{date} so you have it for future reference

Create a New Skin

1. In {wiki}/skins, copy a folder for the new look and feel

   (This is where CSS styling and images will be placed.)

   E.g. Copy skins/custom/ to skins/isvname/ (lowercase)

2. In the skins folder, copy the two skin-index files:

   • Copy Custom.php to IsvName.php (camelcase)
   • Copy Custom.deps.php to IsvName.deps.php (camelcase)
   • File IsvName.deps.php doesn't need to be touched.
   • In IsvName.php, do two case-sensitive substitutions:
     • Custom ==> IsvName (camelcase)
     • custom ==> isvname (lowercase)

Learn more:

• This is an old page with excellent directions:
  http://www.mediawiki.org/wiki/Manual:Skins/From_Meta#Creating_a_Skin_based_on_MonoBook_.281.6.x.29
• This is the index pointing to newer pages. They're more detailed, but often lack good, task-oriented instruction:
  http://www.mediawiki.org/wiki/Manual:Skins

Configure the Wiki for the New Subdomain and Skin

1. In /www/{wiki}/LocalSettings.php, copy the "custom" else-if clause.
2. Change the sitename variable, $wgsitename.

   Note: This title is still used to condionalize Wiki content, in some places.

3. Point to the new skin in $wgDefaultSkin.
4. Make sure the image and icon pointers are going to the right files.
5. Customize the wiki variables.

Note: Currently, these variables are defined as "templates" in the Wiki: Template:DOCHOST The location of configuration files, code samples, platform javadocs, and other resource files referenced in the wiki. Template:JAVA_DOCHOST The location of the standard Sun/Oracle javadocs. (This value should match the one used when generating platform javadocs.) The expectation is that these values are wiki-specific, rather than than skin-specific. (They use Wiki variables so they automatically point to the current wiki's download files.) They are noted here, only in case it becomes desirable to point to skin-specific locations at some future date.

Change the Graphics

In custom_images, copy and edit the graphics files:

1. Icon image: aspect_icon.ico
   • Appears to the left in browser address bar, browser tabs, and bookmarks.
   • 32x32 pixels
   • The free IcoFX utility is good for editing.

2. Logo image: aspect_logo.png
   • GIF, JPG, or PNG
   • 160w x 135h pixels recommended, but height <= 135 is fine.
   • (MediaWiki recommends 135x135, but we sidebar width has been increased to 160px in our instance.)

Modify the Styling

Working with Skins

A few things to know going in:

• All of the skins are based on the default MONOBOOK skin
• When you set the default skin in LocalSettings.php, you're setting the default for new users.
• Anyone who isn't logged in will see your changes when they refresh the page.
• But you, being someone who has logged in so you can edit stuff, will always see the skin you had before!
• To fix that, go to Preferences > Skins and select the skin you want to use.
• Or, to check out an individual page, add &useskin={skin} to the URL.

  For example: &useskin=lj7monobook

Learn more:

• This page explains the names of the divs in the skin, and how they're used:

http://meta.wikimedia.org/wiki/Customization:Explaining_skins#Major_style_blocks_by_name

Making a Custom Sidebar

Sidebars can't have embedded conditionals, so create a sidebar using Template:Sidebar Basic as a guide, or one of the other Sidebar XX templates.

The format is:

* Box title
** Bullet item target page | text to display

Then modify the nested conditionals in Template:Sidebar, which selects the sidebar to display for the current skin.

Learn more: http://www.mediawiki.org/wiki/Manual:Interface/Sidebar#Customize_the_sidebar

Modifying the CSS

Where to make changes:

• CSS styling that is intended for all looks should be created in Mediawiki:Common.css. That page overrides CSS in all skins.
• Skin-specific CSS goes into Mediawiki:{Skinname}.css, where the SkinName is always specified using an initial capital letter followed by lower case.

What to change:

1. Copy content from one of the other MediaWiki:{Skin} pages for a starter set of things to change.

2. In particular, set the styles for these elements:
   • <hr>
   • <body>
   • <q> (A "quote" element of some kind? Has some text settings.)
   • .horizontal_bar - set the color of the thick horizontal bar.
   • .vertical_bar - set the color for a table cell border used to create a thick "vertical bar"

3. Copy other CSS elements that need to be modified from skins/isvname/main.css

Customize Locations for External Files

The Wiki points to a variety of external documents. For example: configuration files and code samples. The ability to easily change such locations is highly desirable, both to allow for a local copy of the Wiki and to simplify platform upgrades.

These customizable locations are used in links:

• Template:DOCHOST
• Template:JAVA_DOCHOST -- points to the location used when building javadocs
• Template:J2EE_DOCHOST -- ditto

The key variable is Template:DOCHOST. It contains a URL that points to the download/ area for the current wiki, so that links to files that accompany the wiki don't need to change when the Wiki is moved or renamed.

Usage

Links to external files are coded in the Wiki like this: [{{DOCHOST}}/somefile The link]

The result is a link like this: The link.

Note that the DOCHOST link could conceivably be customized for each skin. That can be done by defining a DOCLINK variable in LocalSettings.php, and then using in the DOCHOST template, like this:

{{#if: {{DOCLINK}}|{{DOCLINK}}|{{SERVER}}{{SCRIPTPATH}}/download}}

With that code, DOCLINK is used if it is defined. If not, the download/ directory that accompanies the current wiki is used.