LongJump Support Wiki

User:Aeric/customizing

From LongJump Support Wiki
< User:Aeric
Revision as of 18:58, 26 May 2011 by imported>Aeric (Created page with "These features are used to customize the wiki for generic ISV use, for LongJump, for Relationals, and for specific ISVs. {{Note|The ISV version of the wiki competes with the o…")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

These features are used to customize the wiki for generic ISV use, for LongJump, for Relationals, and for specific ISVs.

Notepad.png

Note: The ISV version of the wiki competes with the others. So a user-centric version of the wiki can be created for a specific ISV, but it is not possible to create an ISV-centric version for that brand.

To change the CSS styling in an ISV-dependent way, the first task is to set up a subdomain for the ISV. (Every customization is controlled by the use of that subdomain when accessing the common Wiki. (lj.platformatyourservice.com and isv.platformatyourservice.com both go to the very same place--but the subdomain prompts differences in the wiki's look and content.)

The next task is to customize the look and feel. After that, you take care of Wiki content.

Notepad.png

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

Prerequisites

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

  • Content Controls
    • What brand name replaces "LongJump Platform"? (EnterpriseBrand)
    • What label replaces "LongJump" in the Eclipse Plugin? (BrandLabel)
      (BrandLabel is also used in the Outlook-sync GUI, but that functionality is only exposed in the LongJump and Relationals domains.)
    • Should LongJump-branded whitepapers be 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 when discussions conclude
    • 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?
    (Needed to direct the subdomain-URL to the HOST IP address).
    • Access CPanel Securely > Subdomains
    • Create subdomain: {isvname} (lowercase)
    • Document root: public_html
  2. In the SiteGround CPanel (control panel), create a new subdomain for the ISV.
    (Needed so that the server recognizes the subdomain.)
  3. Make sure that Wiki-redirects for the new subdomain work the same as they do for the existing subdomains. Do that by adding the subdomain to the wiki-redirect files:
    • /www/lj{curr_version}/index.php
      (makes a version-specific link go to the current wiki, in /wiki)
    • /www/index.php
      (makes /lj.platformatyourservice.com go to /wiki)
    Note:
    "www" is a symlink to the Siteground /public_html folder for the platfor1 user.
    All of the wiki folders live there.

Notepad.png

Note:

  • There is a symlink from /www/lj{curr_version}/download
to /www/wiki/download
That symlink makes a version-specific link go to the right place when that version is the primary wiki living at the current-wiki URL, /wiki.
  • There is also one at the root dir that goes to the /wiki space.
  • When we are hosting the Wiki ourselves, we can use a single Apache redirect for those URLs, instead of needing an index.php to redirect wiki pages and a symlink to redirect downloads.
  • For now, though, we copy the "redirect folder" (e.g. /www/lj{curr_version}),
    which includes both the wiki-page redirect file (index.php) and the download symlink--both of which point to the /wiki url.

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:

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 will be used to condionalize Wiki content later.
  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.

Notepad.png

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 are noted here, just in case it becomes desirable to point to skin-specific locations at some future date.

Change the Graphics

In skins/isvname, replace the ISV-specific graphics:

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

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.

Here are the skins we are using at the moment:

What to Change

    • Copy content from one of the other MediaWiki:{Skin} pages for a starter set of things to change.
      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"
    • Copy other CSS elements that need to be modified from skins/isvname/main.css

Customize Wiki Content

Customize the Brand Name

MediaWiki does not have dynamically modifiable variables. The only usable variables to control runtime behavior are SITENAME and PAGENAME. Of those, the only one we have any control over is SITENAME. So we use that to conditionalize text inside of MediWiki "templates" (text segments that can be transcluded where needed).

Notepad.png

Note: SITENAME is defined by a variable in LocalSettings.php. It should be possible to define other variables in the same way. When we do that, customizing the brandname will become a lot simpler than it currently is. (See below.)

Wiki pages are coded using <tt>{{enterprisebrand}}</tt>, so it is relatively easy to change the brand name displayed in the Wiki. The bigger issue is making sure that the "LongJump" brand name is not included in screen captures, in diagrams, and that it is not hard-coded in Wiki text.)

To add a brand name:

1. Copy this template and substitute the appropriate values:

{{ #ifeq: {{SITENAME}}
|__Wiki Sitename__
|__ISV Platform__
|LongJump Platform}}


<-- Use the text assigned to $wgsitename in LocalSettings.php
<-- The text that will be substituted everywhere the template is used
<-- The default text (LongJump Platform)

2. Open Template:Enterprisebrand and insert your customized conditional.
The trick is to insert it in the right location, because there is no "else if" in MediWiki.
The only way to achieve the same effect is to place the entire phrase where the previous "else" clause used to be.
So if the original version is 
{{ #ifeq: {{SITENAME}}
|ISV Support Wiki
|ISV Platform             
|LongJump Platform}}
And you want to add a new entry:
{{ #ifeq: {{SITENAME}}
|NEW ISV WIKI NAME
|New ISV Platform             
|LongJump Platform}}
Then you substitute the entire ifeq-phrase where the previous "else" clause ("LongJump Platform") used to be, nesting it inside the previous ifeq.
The result looks like this: 
{{ #ifeq: {{SITENAME}}
|ISV Support Wiki
|Platform
|{{ #ifeq: {{SITENAME}}
|NEW ISV WIKI NAME
|New ISV Platform             
|LongJump Platform}}}}
(Note that the double-braces are doubled again, at the end.)

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:

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.

Conditionalizing Wiki Text

Variables and Their Usage

These variables are defined for each skin in LocalSettings.php.
They are case-insensitive.

Variable Name Definition Value in Current Domain Usage
Version Platform version identifer (global) Template:Version {{Version}}
Skin Abbreviated name LJ {{#if {{Skin}}|name|...|...else...}}
Domain Used in the platformURL variable na.longjump.com Create platform links using {{platformURL}}, instead of https://...
BrandLabel Label used in GUI
(Eclipse, Outlook,...)		 LongJump {{BrandLabel}}
EnterpriseBrand Name of the platform LongJump Platform {{EnterpriseBrand}}
TrainingLink A link for training sessions. http://www.longjump.com/index.php?option=com_eventlist&view=eventlist&Itemid=178 {{#if {{TrainingLink}} | [{{TrainingLink}} Platform Training]}}
WhitepapersLink Future. Defined the same way as "TrainingLink", so it is easy to change.
 
Booleans
ShowWhitepapers Show whitepapers? true (empty=false)
(Fixed branding)		 {{#if {{ShowWhitepapers}} | ...}}
ShowOutlookSync Show info related to Outlook Sync & Email Edition Plugin? true (empty=false) {{#if {{ShowOutlookSync}} | ...}}
ShowIsvInfo Show info only ISVs care about true (empty=false) {{#if {{ShowIsvInfo}} | ...}}
ShowMspInfo Show info only MSPs care about true (empty=false) {{#if {{ShowMspInfo}} | ...}}
PlatformAdminInfo Show tenant configuration (empty=false) {{#if {{PlatformAdminInfo}} | ...}}
ShowInstallInfo Show info for installers (empty=false) {{#if {{ShowInstallInfo}} | ...}}

Variable Combinations

Use this pattern to conditionalize information intended for all Service Providers (both ISVs and MSPs):
{{#if: {{ShowIsvInfo}} {{ShowMspInfo}} |
__Info for all Service Providers (LJ and ISV domains)__
}}

Notepad.png

Note: Information intended for both is generally conditioned using ShowIsvInfo--whether or not that was a wise choice remains TBD. So the combination above isn't strictly necessary.

Use this pattern if it is necessary to distinguish information intended for ISVs (which may mention MSPs) from information intended for MSPs, in Wiki versions that do not include ISV info (e.g. Relationals):
{{#if: {{ShowIsvInfo}} |
__ISV info (ISV DOMAIN) __

| <!-- HideIsvInfo -->
{{#if: {{ShowMspInfo}} |
__MSP info (LJ DOMAIN)__
}}}}
Retrieved from "https://agileappscloud.info/ljwiki-src/index.php?title=User:Aeric/customizing&oldid=9490"