AgileApps Support Wiki Pre Release

Difference between revisions of "User:Aeric/Customizing"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
 
(62 intermediate revisions by the same user not shown)
Line 1: Line 1:
===About Customizing===
These features are used to customize the wiki for generic ISV use, or for a branded wiki.  
These features are used to customize the wiki for generic ISV use, or for a branded wiki.  


{{Note|The ISV version of the wiki competes with the others. So a user-centric version  
====Platform-specific Versions====
of the wiki can be created for a specific ISV, but it is not possible to create an
To create a branded version of the Wiki for a particular ISV:
ISV-centric version for that brand.}}
# First, set up a subdomain for the ISV.<br>Every customization is controlled by the use of that
 
subdomain when accessing the common Wiki. For example, <tt>lj.platformatyourservice.com</tt>
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. (<tt>lj.platformatyourservice.com</tt>
and <tt>isv.platformatyourservice.com</tt> both go to the very same place--but
and <tt>isv.platformatyourservice.com</tt> both go to the very same place--but
the subdomain prompts differences in the wiki's look and content.)
the different subdomains changes the wiki's look and content.
 
#:
The next task is to customize the look and feel. After that, you take care of Wiki content.
#Then customize the look and feel for that brand.  
#:
#Finally, take care of the Wiki content.


{{Note|All changes should be made locally, and then uploaded to the server. Note, too,
{{Note|All changes should be made locally, and then uploaded to the server. Note, too,
Line 17: Line 17:
To do that, it is necessary to set up a server that runs the local copy of the files.
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...)}}
(One day, this too shall be done...)}}
====Product-Specific Versions====
To create a branded version of the Wiki for a particular application:
# Create a new domain for that product.
# Customize the look and feel for that product<br>For example, sidebars that have product-centered links only, rather than links to generic design and development pages.
# (We may or may not do this...)<br>To link to generic platform design & development pages, use ''external links'' <tt>(<nowiki>[url name]</nowiki></tt>) rather than internal links (<tt><nowiki>[[page name]]</nowiki></tt>). (The Google page search should then be confined to the product pages, since they're no longer in the same domain.)
'''How it works:'''
:* We're using <tt>rally360.info</tt> for the latest incarnation of the corporate wiki.
:* The default skin for <tt>rally360.info</tt> is the same as that used by <tt>hd.rally360.info</tt>
::* In other words, the "hd" skin is the default
::* where "hd" stands for "HelpDesk"
:* Future products in the same theme ("360-degree circle with customer at the center") will have their own subdomains. For example, "crm" for Customer Relations Management.
'''To change the product name:'''
:* The product pages are in the "HelpDesk:" namespace.
:* That name is defined by a variable--<nowiki>{{HD}}</nowiki>--so it can be changed.
:* Links to those pages and transclusion references use that variable, so they can be easily changed by modifying <tt>LocalSettings.php</tt>
:* Two things then need to be done:
:: a. Rename all pages to reflect the new namespace.
:: b. Change all REDIRECT pages, because the variable cannot be used in them.
:::  (Change all occurrences of "HelpDesk:" to "NewName:")


===Prerequisites===
===Prerequisites===
You'll need to have these things handy to set up the customized version:
You'll need to have these things handy to set up the customized version:
:* '''Content Controls'''
:* '''Content Controls'''
:** What brand name replaces the "{{EnterpriseBrand}}"? ('''EnterpriseBrand'''--always follows the word "the")
:** What brand name replaces the "{{EnterpriseBrand}}"? ('''EnterpriseBrand'''--always follows the word "the", typically followed by "platform".)
:** What label replaces "{{BrandLabel}}" in the Eclipse Plugin? ('''BrandLabel''')<br>(and in email-sync, when enabled.)   
:** What label replaces "{{BrandLabel}}" in the Eclipse Plugin? ('''BrandLabel''')<br>(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 <br>(A new page needs to be created for the branded version, and <tt><nowiki>{{:Common:HelpDesk}}</nowiki></tt> content needs to be transcluded into it.)
:** Are the branded whitepapers available?
:** Are the branded whitepapers available?
:** Should development information be displayed (Eclipse plugin, APIs, classes, etc)
:** Should development information be displayed (Eclipse plugin, APIs, classes, etc)
Line 44: Line 70:
===Set Up a Subdomain===
===Set Up a Subdomain===
The subdomain is the master switch that turns on everything else.
The subdomain is the master switch that turns on everything else.
# In UltraDNS, add a DNS entry for the subdomain?
# In UltraDNS, add a DNS entry for the subdomain
#: (Needed to direct the subdomain-URL to the HOST IP address).
#: (Directs the subdomain-URL to the HOST IP address).
#:* '''Access CPanel Securely > Subdomains'''
#:* '''Access CPanel Securely > Subdomains'''
#:* Create subdomain: '''{isvname}''' (lowercase)
#:* Create subdomain: '''{name}''' (lowercase)
#:* Document root: '''public_html'''
#:* Document root: '''public_html'''
#:
#:
#In the [https://www.siteground.com/ua_files/index.php?requri=my_accounts/access_cpanel.php&aid=124790 SiteGround CPanel] (control panel), create a new subdomain for the ISV.
# At the bottom of <tt>mediawiki.conf</tt>, add a subdomain entry to the <tt><VirtualHost></tt> tag:
#: (Needed so that the server recognizes the subdomain.)
#* <tt>ServerAlias  {name}.platformatyourservice.com</tt>
#:
#* Process:
#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:
#:: a. In <tt>www/apache_config</tt>, edit <tt>mediawiki.conf_new</tt>
#* <tt>/www/lj{curr_version}/index.php</tt><br>(makes a version-specific link go to the current wiki, in <tt>/wiki</tt>)
#:: b. Upload the file
#* <tt>/www/index.php</tt> <br>(makes <tt>/lj.platformatyourservice.com</tt> go to <tt>/wiki</tt>)
#:: c. In PuTTY, <tt>cd /usr/share/mediawiki/apache_config</tt>
#:: '''Note:'''
#:: d. Use <tt>./try</tt> to test it. Use <tt>./revert</tt> to go back to the previous version.
#:: "www" is a symlink to the Siteground /public_html folder for the platfor1 user.
#:: e. When changes are tested, <tt>cp mediawiki.conf_new mediawiki.conf_sav</tt>.
#:: All of the wiki folders live there.  
#::: (The new version is now the version you'll revert to, the next time you test changes.)
 
#:: r. Also copy it to <tt>mediawiki.conf_{date} so you have it for future reference</tt>
{{Note|
# Finally, consider the impact of the subdomain on the [[#Customized Wiki Search]]
:* There is a symlink from <tt>/www/lj{curr_version}/download</tt>
:: to <tt>/www/wiki/download</tt>
:: 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, <tt>/wiki</tt>.  
:* 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. <tt>/www/lj{curr_version}</tt>),<br> which includes both the wiki-page redirect file (<tt>index.php</tt>) and the download symlink--both of which point to the <tt>/wiki</tt> url.}}


===Create a New Skin===
===Create a New Skin===
Line 88: Line 108:
# In <tt>/www/{wiki}/LocalSettings.php</tt>, copy the "custom" else-if clause.
# In <tt>/www/{wiki}/LocalSettings.php</tt>, copy the "custom" else-if clause.
# Change the sitename variable, <tt>$wgsitename</tt>.  
# Change the sitename variable, <tt>$wgsitename</tt>.  
#: '''Note:''' This title will be used to condionalize Wiki content later.
#: '''Note:''' This title is still used to condionalize Wiki content, in some places.
# Point to the new skin in <tt>$wgDefaultSkin</tt>.
# Point to the new skin in <tt>$wgDefaultSkin</tt>.
# Make sure the image and icon pointers are going to the right files.
# Make sure the image and icon pointers are going to the right files.
Line 97: Line 117:
:;[[Template:JAVA_DOCHOST]]:The location of the standard Sun/Oracle javadocs. (This value should match the one used when generating platform javadocs.)
:;[[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.}}
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===
===Change the Graphics===
In <tt>skins/isvname</tt>, replace the ISV-specific graphics:
In <tt>custom_logos</tt>, copy and edit the graphics files:
#* Icon image: <tt>aspect_icon.ico</tt>
# Icon image: <tt>aa###.ico</tt>, where "###" is the version number
#:* Appears to the left in browser address bar, browser tabs, and bookmarks.
#* Appears to the left in browser address bar, browser tabs, and bookmarks.
#:* 32x32 pixels
#* 32x32 pixels
#:* The free [http://icofx.ro/ IcoFX] utility is good for editing.
#* The free [http://icofx.ro/ IcoFX] utility is good for editing.
#:
#:
#* Logo image: <tt>aspect_logo.png</tt>
# Logo image: <tt>aa###.png</tt>, where "###" is the version number
#:* GIF, JPG, or PNG
#* GIF, JPG, or PNG
#:* 160w x 135h pixels recommended, but height <= 135 is fine.
#* 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.)
#* (MediaWiki recommends 135x135, but we sidebar width has been increased to 160px in our instance.)


===Modify the CSS Styling===
===Modify the Styling===


====Working with Skins====
====Working with Skins====
Line 119: Line 139:
:* Anyone who isn't logged in will see your changes when they refresh the page.
:* 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!
:* 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.
:* To fix that, go to '''My Preferences > Skin''' and select the skin you want to use.
:* Or, to check out an individual page, add <tt>&useskin={skin}</tt> to the URL.
:* Or, to check out an individual page, add <tt>&useskin={skin}</tt> to the URL.
:*:For example: <tt>&useskin=lj7monobook</tt>
:*:For example: <tt>?useskin=lj7monobook</tt> or <tt>?...&useskin=lj7monobook</tt>


===Where to Make Changes===
:''Learn more:''
CSS styling that is intended for all looks should be created in [[Mediawiki:Common.css]]. That page overrides CSS in all skins.  
:* 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
:* Best instruction I've found to date:
:: http://charlesmartinreid.com/wiki/Skinning_MediaWiki


Skin-specific CSS goes into Mediawiki:{Skinname}.css, where the SkinName is always specified using an initial capital letter followed by lower case.  
{{Tip|<br>When viewing page source, all of the variables are defined at the top of the page, starting around line 35. For example:
<pre>
  <script type= "text/javascript">/*<![CDATA[*/
    var skin = "isvmonobook";
    var stylepath = "/wiki/skins";
    var wgArticlePath = "/wiki/$1";
    var wgScriptPath = "/wiki";
    var wgScript = "/wiki/index.php";
      ...
    var wgServer = "http://isv.platformatyourservice.com";
      ...
    var wgVersion = "1.15.5";
</pre>}}
 
====Making a Custom Sidebar====
Sidebars can't have embedded conditionals so if multiple sidebars are needed, copy [[Template:Sidebar]] to make one for each skin.
 
The format is:
:<syntaxhighlight lang="html4strict" enclose="div">
* Box title
** Bullet item target page | text to display
</syntaxhighlight>
 
Then create nested conditionals in [[Template:Sidebar]] to select the sidebar to display for the current skin.<br>
(Conditionals can be used to choose which sidebar to expand. They can't be used ''within'' the sidebar list.)
 
:''Learn more:'' http://www.mediawiki.org/wiki/Manual:Interface/Sidebar#Customize_the_sidebar
 
====Modifying Logo/Layout CSS====
The logo layout is controlled in skins/{skin}/main.css.
:* The main skin is lj7monobook
:* Adjustments can also be made using the content CSS pages below.
 
The vertical space available for the logo is controlled in #column-one.
:* '''padding-top''' controls how far down the page the first sidebar entry starts
 
The height of the box the logo is in is controlled in '''#p-logo''' (and '''#p-logo a''' below)
:* '''height''' determines the height of the box (>= logo height, <= column-one padding)
:* '''margin-top''' moves the logo image up or down in the available space
 
The height of '''#p-logo a''' needs to match the height in #p-logo, for some reason
:* '''height''' use the same value as specified for #p-logo. It's the link specification. If it isn't set to at least the height of the image, the image doesn't display. So maybe the #p-logo height could be specified as "auto"? (Something to try, in future.)
 
====Modifying Sidebar Width====
To change the width of the column, several other things must be adjusted to match.<br>(If width grows, they must shrink, and vice versa.)
 
To make a change, see the settings and instructions in [[MediaWiki:Common.css]].
 
====Modifying Content 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.  
{{#ifeq: {{Skin}} | LJ |
{{#ifeq: {{Skin}} | LJ |
Here are the skins we are using at the moment:
Here are the skins we are using at the moment:
Line 136: Line 210:
:* [[MediaWiki:Custom.css]] - Test domain
:* [[MediaWiki:Custom.css]] - Test domain
}}
}}
====What to Change====
What to change:
#* Copy content from one of the other <tt>MediaWiki:{Skin}</tt> pages for a starter set of things to change.
# Copy content from one of the other <tt>MediaWiki:{Skin}</tt> pages for a starter set of things to change.
#*: In particular, set the styles for these elements:
#:
#*:* <nowiki><hr></nowiki>
# In particular, set the styles for these elements:
#*:* <nowiki><body></nowiki>
#* <nowiki><hr></nowiki>
#*:* <nowiki><q></nowiki> (A "quote" element of some kind? Has some text settings.)
#* <nowiki><body></nowiki>
#*:* .horizontal_bar - set the color of the thick horizontal bar.
#* <nowiki><q></nowiki> (A "quote" element of some kind? Has some text settings.)
#*:* .vertical_bar - set the color for a table cell border used to create a thick "vertical bar"
#* .horizontal_bar - set the color of the thick horizontal bar.
#* Copy other CSS elements that need to be modified from <tt>skins/isvname/main.css</tt>
#* .vertical_bar - set the color for a table cell border used to create a thick "vertical bar"
 
#:
===Customize Wiki Content===
# Copy other CSS elements that need to be modified from <tt>skins/isvname/main.css</tt>
 
====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).
 
{{Note|SITENAME is defined by a variable in <tt>LocalSettings.php</tt>.
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 <nowiki><tt>{{enterprisebrand}}</tt></nowiki>,
so it is relatively easy to change the brand name displayed in the Wiki.
The bigger issue is avoid hardcoding a brandname in screen captures, in
diagrams, and in Wiki text.)
 
To add a brand name:
:* Modify <tt>LocalSettings.php</tt>


===Customize Locations for External Files===
===Customize Locations for External Files===
Line 190: Line 244:
With that code, DOCLINK is used if it is defined. If not, the <tt>download/</tt> directory that accompanies the current wiki is used.
With that code, DOCLINK is used if it is defined. If not, the <tt>download/</tt> directory that accompanies the current wiki is used.


===Conditionalizing Wiki Text===
===Customized Wiki Search===
{{Skin-specific Variables}}
We use the Google Custom Search Engine (CSE) to provide a search that is limited to pages that can be reached by robots, and to limit the results to the text that appears on the page (as opposed to the internal search, which searches the Wiki database--leading to the exposure of pages and text segments that are not limited to a specific audience.
 
Other advantages of that search:
:* It tends to list the most frequently accessed pages first
:* If you specify A and B, it puts pages with A alone or B alone at the bottom of the list, instead of somewhere near the top.
:* If you specify "A B", it searches for A-whitespace-B, not quote-A-space-B-quote.
 
At the moment, we have only one search enabled, for <tt>rally360.info</tt>. At some point, there could be multiple subdomains for different products, but for the moment we have only one (the <tt>hd</tt>, or "HelpDesk" subdomain).
 
'''To modify that engine:'''
:* http://google.com/cse 
:* Log in using our Google LongJump account username and password
:* Ensure that Uday has made you a co-admin for the search(es) (<tt>MediaWiki search</tt>, currently)
:* Click the control panel link.
:* In the sidebar, choose segment in which to make changes.
 
'''Notes:'''
:* The appearance in the sidebar of the google search and the internal search are controlled in <tt>skins/lj7monobook.php</tt>, in the range of lines from 283 to 323. The are currently set to:
::* Display the Google search only in the current version of the wiki (because search robots are allowed only in the current pages).
::* Display it only in rally360 domain (because that is the domain the CSE covers)
::* Display the internal search in all other circumstances (calling it "search")
::* If the CSE is displayed, and the current user is logged in, add an "internal search" box at the bottom, for times when we (the logged in writers) want to search a previous or future version of wiki, or we want to look for text in the database.
 
:* We use the Google analytics variable to determine if we are in the current wiki (<tt>$wgGoogleAnalyticsAccount</tt>, because that is the only time that analytics are enabled.
 
:* The results of the Google search are displayed in [[Site:Search]]. (The rawHTML flag is set in LocalSettings, to allow the appropriate tag to be inserted into the page.)
 
===Customize Wiki Content===
{{Variables}}

Latest revision as of 20:10, 2 June 2015

About Customizing

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

Platform-specific Versions

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.

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

Product-Specific Versions

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. (We may or may not do this...)
    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 be confined to the product pages, since they're no longer in the same domain.)

How it works:

  • We're using rally360.info for the latest incarnation of the corporate wiki.
  • The default skin for rally360.info is the same as that used by hd.rally360.info
  • In other words, the "hd" skin is the default
  • where "hd" stands for "HelpDesk"
  • Future products in the same theme ("360-degree circle with customer at the center") will have their own subdomains. For example, "crm" for Customer Relations Management.

To change the product name:

  • The product pages are in the "HelpDesk:" namespace.
  • That name is defined by a variable--{{HD}}--so it can be changed.
  • Links to those pages and transclusion references use that variable, so they can be easily changed by modifying LocalSettings.php
  • Two things then need to be done:
a. Rename all pages to reflect the new namespace.
b. Change all REDIRECT pages, because the variable cannot be used in them.
(Change all occurrences of "HelpDesk:" to "NewName:")

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
  3. Finally, consider the impact of the subdomain on the #Customized Wiki Search

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

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 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_logos, copy and edit the graphics files:

  1. Icon image: aa###.ico, where "###" is the version number
    • 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: aa###.png, where "###" is the version number
    • 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 My Preferences > Skin 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 or ?...&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
  • Best instruction I've found to date:
http://charlesmartinreid.com/wiki/Skinning_MediaWiki

Thumbsup.gif

Tip:
When viewing page source, all of the variables are defined at the top of the page, starting around line 35. For example: 

  <script type= "text/javascript">/*<![CDATA[*/
    var skin = "isvmonobook";
    var stylepath = "/wiki/skins";
    var wgArticlePath = "/wiki/$1";
    var wgScriptPath = "/wiki";
    var wgScript = "/wiki/index.php";
      ...
    var wgServer = "http://isv.platformatyourservice.com";
      ...
    var wgVersion = "1.15.5";

Making a Custom Sidebar

Sidebars can't have embedded conditionals so if multiple sidebars are needed, copy Template:Sidebar to make one for each skin.

The format is: 

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

Then create nested conditionals in Template:Sidebar to select the sidebar to display for the current skin.
(Conditionals can be used to choose which sidebar to expand. They can't be used within the sidebar list.)

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

Modifying Logo/Layout CSS

The logo layout is controlled in skins/{skin}/main.css.

  • The main skin is lj7monobook
  • Adjustments can also be made using the content CSS pages below.

The vertical space available for the logo is controlled in #column-one.

  • padding-top controls how far down the page the first sidebar entry starts

The height of the box the logo is in is controlled in #p-logo (and #p-logo a below)

  • height determines the height of the box (>= logo height, <= column-one padding)
  • margin-top moves the logo image up or down in the available space

The height of #p-logo a needs to match the height in #p-logo, for some reason

  • height use the same value as specified for #p-logo. It's the link specification. If it isn't set to at least the height of the image, the image doesn't display. So maybe the #p-logo height could be specified as "auto"? (Something to try, in future.)

Modifying Sidebar Width

To change the width of the column, several other things must be adjusted to match.
(If width grows, they must shrink, and vice versa.)

To make a change, see the settings and instructions in MediaWiki:Common.css.

Modifying Content 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:

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.

Customized Wiki Search

We use the Google Custom Search Engine (CSE) to provide a search that is limited to pages that can be reached by robots, and to limit the results to the text that appears on the page (as opposed to the internal search, which searches the Wiki database--leading to the exposure of pages and text segments that are not limited to a specific audience.

Other advantages of that search:

  • It tends to list the most frequently accessed pages first
  • If you specify A and B, it puts pages with A alone or B alone at the bottom of the list, instead of somewhere near the top.
  • If you specify "A B", it searches for A-whitespace-B, not quote-A-space-B-quote.

At the moment, we have only one search enabled, for rally360.info. At some point, there could be multiple subdomains for different products, but for the moment we have only one (the hd, or "HelpDesk" subdomain).

To modify that engine:

  • http://google.com/cse
  • Log in using our Google LongJump account username and password
  • Ensure that Uday has made you a co-admin for the search(es) (MediaWiki search, currently)
  • Click the control panel link.
  • In the sidebar, choose segment in which to make changes.

Notes:

  • The appearance in the sidebar of the google search and the internal search are controlled in skins/lj7monobook.php, in the range of lines from 283 to 323. The are currently set to:
  • Display the Google search only in the current version of the wiki (because search robots are allowed only in the current pages).
  • Display it only in rally360 domain (because that is the domain the CSE covers)
  • Display the internal search in all other circumstances (calling it "search")
  • If the CSE is displayed, and the current user is logged in, add an "internal search" box at the bottom, for times when we (the logged in writers) want to search a previous or future version of wiki, or we want to look for text in the database.
  • We use the Google analytics variable to determine if we are in the current wiki ($wgGoogleAnalyticsAccount, because that is the only time that analytics are enabled.
  • The results of the Google search are displayed in Site:Search. (The rawHTML flag is set in LocalSettings, to allow the appropriate tag to be inserted into the page.)

Customize Wiki Content

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

Global Variables

Application names (because marketing can change them):

Variable Definition Value in Current Domain Usage
HD name of the "HelpDesk" application ServiceDesk {{HD}}

Version Variables

Variable Value
{{MySqlVersion}} 5.5
{{VelocityVersion}} 1.7

Skin-Specific Variables

Variable Name Definition Value in Current Domain Usage
Skin Abbreviated name HD {{#if {{Skin}}|name|...|...else...}}
Domain Used in the platformURL template {yourDomain} Create platform links using {{platformURL}}, instead of https://...
platformURL Template:platformURL
Link used to access the platform		 https://{yourDomain}/networking {{platformURL}}
BrandLabel Label used in plugin GUIs
(Eclipse, Outlook,...)		 LongJump {{BrandLabel}}
EnterpriseBrand Name of the platform AgileApps Cloud platform {{EnterpriseBrand}}
BrandName Template:BrandName
Advertised brand		 AgileApps Cloud {{BrandName}}
TrainingLink A link for training sessions. {{#if {{TrainingLink}} | [{{TrainingLink}} Platform Training]}}
WhitepapersLink Future. Defined the same way as "TrainingLink", so it is easy to change.
 
Booleans
ShowWhitepapers Show whitepapers? (empty=false)
(Fixed branding)		 {{#if {{ShowWhitepapers}} | ...}}
ShowOutlookSync Show info related to Outlook Sync & Email Edition Plugin? (empty=false) {{#if {{ShowOutlookSync}} | ...}}
ShowIsvInfo Show info only ISVs care about (empty=false) {{#if {{ShowIsvInfo}} | ...}}
ShowMspInfo Show info only MSPs care about (empty=false) {{#if {{ShowMspInfo}} | ...}}
PlatformAdminInfo Show tenant configuration true (empty=false) {{#if {{PlatformAdminInfo}} | ...}}
ShowInstallInfo Show info for installers true (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/aadev-src/index.php?title=User:Aeric/Customizing&oldid=13561"