﻿*******************************************************

CREATING AND MODIFYING THE RATIONAL INSTALLATION ROADMAP

v2.0

*******************************************************

Need help? You can try Lee Reamsnyder || ljreamsn@us.ibm.com

CAVEAT: I made this in my spare time, so you can't expect miracles.




****************************************************

TO UPGRADE FROM A PREVIOUS VERSION

****************************************************

Mahmoud, this is you. This will probably be the worst one.

1. We're using the DOJO and DIJIT framework now, so you must get the most recent (1.4.2) from https://cs.opensource.ibm.com/frs/?group_id=2078 Replace the dojo folder with the latest, and add the dijit folder at the same level.
2. You must add the DIJIT framework (see above). The /dijit/ folder goes at the same folder level of the /dojo/ folder you already have
3. To style the Dijit buttons and tooltips, add class="tundra" to the <body> element of the page. So <body class="tundra">
4. With the other stylesheets, add a <link> to the path_to_dijit/themes/tundra/tundra.css stylesheet in the Dijit folder. It'll look like this: <link media="screen, projection" type="text/css" href="dijit/themes/tundra/tundra.css" rel="stylesheet">
5. In the <form> There's a new way to do context help using the DIJIT tooltip framework. Instead of some general spans, these use a dojotype="dijit.Tooltip" element to create the proper styling and behavior. They look like this: <span class="csh" dojotype="dijit.Tooltip" connectId="standardEdition">You cannot deploy Standard edition to an IBM WebSphere<span title="WebSphere is a registered trademark of IBM">&reg;</span> Application Server cluster</span> where connectId is the ID of the element over which to hover to show the tooltip (so, the ID of the label)
6. If you used the class="inlineOption" way to conditionally show specific inline elements (like <span>s or <a> links), stop using them and replace them with conditional <div>s or class="blockOption" for <li> list items, <p> paragraphs, or other block elements. Showing and hiding inline elements is causing a lot of problems with styling and scripting. Sorry about that.
7. VERY IMPORTANT: In the #results section, look for any links that are NOT topics in this information center. So, they're IBM.com, or jazz.net, or a public information center for a different product, or whatever. A good way to check is if they begin with "http://". Add the following attribute and value to the link: rel="external"  So <a href="http://ibm.com/" rel="external">Blah blah</a>    I try to check this anyway with some scripting, but this is a safeguard for the AJAX loading script, so that it does not attempt to load the content of external links (which would fail anyway). VERY IMPORTANT. You only need to do this for outside/external links. Leave internal topics alone.
8. Take your old "I had to edit this" objects from the javascript file and place them in the new one. Their locations should be approximately the same:
	line 30: var buttons = [...] -- form button interactions
	line 176: dojo.query(...).addClass('seen') -- the elements to always show, no matter what
	line 193: var formED = ... -- the optional variable names for named elements from the submitted form
	line 216: var a = [...] -- the array of inputs and which classes to show if they've been selected
	
	Take those elements from your old file and drop them at the appropriate place in my new roadmap.js file.

	You shouldn't need to adjust the roadmap.js file other than that. The other new features are self-contained.
	
9. Back to roadmap.html: Around line 11, where there are some strings that can be translated, now there are a few more (for the "Start over?" and the "Load all and print" buttons). So the full <script> element looks like this now:
<script type="text/javascript">
var errorMsg = 'Please select an option',
	printAllLabel = 'Load and print all topics',
	backToFormLabel = 'Start over?',
	backToFormTitle = 'Go back and change your selections',
	loadErrorText = 'This file failed to load. Sorry about that. Click here to go directly to it.';

var djConfig = {
	parseOnLoad:true,
	isDebug: false
};
</script>
	
	So, you can just copy/paste that, and adjust the strings to your liking. These are in the html file here so the translators can change them without touching javascript.
	
10. (Optional) Take a look at the included roadmap_form.html file. I've changed the organization of the <form> element to use <fieldset>s and <legends>s instead of <div>s and <p>s for semantic purposes. You don't have to change, but double-check the .css stylesheet to make sure things still look all right if you don't want to make that switch
11. (optional) I think you already did this, but I replaced the #reset link with a <button> element. The ID ("reset") is the same, so it should be functionally identical
12. (Optional) If you want, there's styling in place for an optional "short description" style paragraph, just after the page title <h1>. Like so: 
	<p id="shortDesc">This guide describes installing the Rational Asset Manager server applications.</p> 
	
	It's totally optional, though.

****************************

CHANGE LOG

****************************

2.0:
	Added the DIJIT Dojo UI framework, which allows standard-looking form inputs and tooltips across all browsers
	Adding style hooks for an id="shortDesc" short description paragraph
	REQUIRED FIX:
		If you used the "inlineOption" way to conditionally show inline elements (like <span>s or <a> links), you must get rid of them. It's proving problematic with the "Load all and Print" tool for various performance/testing reasons
	Recommend upgrading to IBM-approved Dojo 1.4.2 (original used 1.3.1)
	BIG FRACKING DEAL: Added a "Load and Print All Topics" button to the javascript/form.
	Added a "Start over?" button that resets the page
	Labels and Inputs on the form should now give a pointer for the cursor
	Added info on IBM UI guideline:
		Legends should PROMPT, not ASK
		Hover help MUST be in complete sentences
	Added <fieldset> elements to groups of inputs, to improve semantic meaning
	In <fieldset> groups, replace <p> tags with <legend> tags, for improved semantics
	Replaced custom context-sensitive hover help with Dojo-standard infopops. This results in arguably cleaner markup, and should work always across all browsers.
		Added better-looking max-width and line-height to infopops.
		Added additional CSS styles to infopops. This resolves an issue where infopops with long lines wouldn't line up with the appropriate label.
	Changed the reset link/button to a <button> element, for improved semantics
	Fixed an Internet Explorer 6 bug where infopops would appear outside the document frame

1.0: Initial version


****************************

PREREQUISITES

****************************

First and foremost, you MUST know every install scenario inside and out.

You need to be able to immediately and correctly answer the following questions:
	How many individual tasks are required to install my product? (Your install guide should cover this in the fact that a .dita file should be a task)
	In what order do people need to do those tasks?
	What middleware (Operating system/Database/Application server/Other applications) do people need?
	If they don't have a particular piece of middleware, do we provide one? (For example, if they need DB2, do we include it with the product?)
	How thoroughly does Installation Manager help you?
	How thoroughly does Installation Manager -- umm -- NOT help you?
	Depending on their install environment, do users have to do more or fewer tasks? For example, if you use Installation Manager, can you skip a few things that you have to do manually?
	Depending on their environment, does the order of fundamental tasks change?
	If the user is using a particular piece of middleware, does that limit their other options? For example, if you use Apache Tomcat as a web server, can you then not use Installation Manager because it only supports IBM WebSphere?
	
This is NOT trivial knowledge. And it is NOT easy. Every option exponentially increases the number of possible install paths. For example with Rational Asset Manager, you have 2 editions x 4 application servers x 4 database servers x 4 operating systems = 128 possibilities (roughly)

Technical Requirements:
Working with this requires basic knowledge of:
	HTML
		Format
			Semantic, well-formed HTML v4.01 syntax
			The CLASS and ID attributes for elements
		Forms
			Basic form elements and data structure
			Radio buttons

	CSS 
		Simple element styling
		The display: none || block property, used for hiding/showing nested DIV elements
		Shifting the location elements with position: relative and position: absolute
		Simple Internet Explorer fixes/hacks

	Javascript
		Variable, Object, and Array syntax and formatting
		Knowledge of the Dojo framework wouldn't hurt
			

****************************

THE GOAL

****************************

Typically, our install guides are a dense collection of tasks, and we ask our users to figure out which tasks they have to do, and in what order.

Unfortunately, the tasks that an individual might have to do can drastically vary depending on their choice of operating system, database server, application server, product, integrations, and the different possible versions of all of those.

This installation walkthrough aims to prevent that. We ask the person, in plain language, about all the things that might alter their install path. Then, with that information, we show them ONLY the information they need to install the product.


***************************

THE CAVEATS (Open issues)

***************************

- It doesn't look exactly the same in Internet Explorer 6 as it does Firefox/Safari/Chrome. Tough.
- If your information center uses IEHSc (formerly known as VCC) or other components that require Dojo, it DOES NOT WORK. I haven't had time to figure out how to resolve the conflicts yet.
- For pop-up help, you have to add another element to the page. I want to make this dynamic, preferably from, say, the TITLE attribute of a label.


****************************

THE PREP WORK

****************************

You need to get the IBM-approved Dojo toolkit (a JavaScript framework). Dojo is a script framework that lets us quickly build scripts with some assurance that they'll work the same across all browsers.

ONLY get the framework from this link:
https://cs.opensource.ibm.com/frs/?group_id=2078

That's the IBM-approved version of the library, and it's the only one that can go in our products.

Grab the latest (As of this writing, 1.3.1-20090508-IBM) standard library.

Now, copy the /dojo/ folder into the /topics/ folder of your install guide plugin.

I've experimented with other places for the DOJO library, but it seems like the best place for it is in the /topics/ folder. Sorry.


****************************

MODIFYING THE HTML FILE

****************************

The roadmap_form.html file contains the form and all the install guide content. Based on the data that the user submits to a script, the appropropriate content is revealed.

THE <HEAD> ELEMENT
	
	<title>
		Update the <title> element for your product
	<link>s
		Change the href="" attributes as necessary to point to the CSS files for this roadmap. You'll definitely need these.
	First <script>
		If you want, change the text of the variable "errorMsg". This is the text that will appear in a red box if you specify that a question is required, and the user doesn't answer it. 
		It's included in this file because it's the one bit of dynamic information that requires translation.
	Next <scripts>
		Change the SRC attributes to point to first the location of the dojo.js file, then the roadmap.js file. The order is important, as dojo.js must come first.

<BODY>

	<h1 id="pagetitle">
		Update the title for your product.
		This is the first visible mention of the product, so add copyright/registered trademark symbols as needed.

	<div id="qa">
		Everything within this <div> will be hidden when the user successfully submits the form

	<form id="theForm">
		The form is broken into groups of radio <inputs>
		
		<div>
			Each group of inputs is surrounded by a <div>
			Each <div> must have a unique ID attribute.
			If a user MUST answer this question (it can't be left blank), add class="needsSelected" to the <div>
			
			<fieldset>
				Groups each set of inputs, and the descriptive legend
		
			<legend>
				This is the question you want answered. In early versions, I had this as a Q&A ("What app server are you using?"); however, IBM UI standards are that these should PROMPT users, not ask them. So, "Select an application server:" is more appropriate.
			
			<ul>
				Each group of inputs is in an unordered list
				
				<li>
					Every input is in an <li> tag.
					
					<input>
						You need an input for every option. Each input MUST have:
							type="radio" -- All inputs need this. You only want people to select one option, so you need Radio buttons
							name="something" -- an identifier for the information you're after. Each radio <input> in a group needs the same name="" attribute. For example, if you're asking about the user's application server, it might be name="appserver"
							value="something" -- the value for that input. It MUST be unique. For example, if you're asking about application servers, possible values might be "was6" or "apache" or "tomcat"
							id="name_value" -- Every input needs a unique ID. Like all ID attributes, it must be unique. I usually combine the name="" and value="" attributes to make the id="", so if name="os" and value="windows", it'd be id="os_windows" and it should be unique. You can use whatever convention you want, though.
					
					<label>
						Every <input> will have a <label> as a sibling element. Each label MUST have:
							for="id_for_input" -- The value of the for="" attribute must be the same as the ID for the associated label. This is for usability and semantic value.
							The text of the label will be clickable to select the radio button, which improves usability (bigger target to click)
						
						<span class="csh" dojotype="dijit.Tooltip" connectId="something"></span>
						Optionally, you can add pop-up text (context-sensitive help) for the label. To do so:
							Per IBM UI standards, hover help MUST be a complete sentence.
							Add this class attribute to the parent <label> tag: 
								class="has_csh"
							Add a unique ID attribute to the <label>
							Immediately after the opening <label> tag, add this markup: 
								<span class="csh" dojotype="dijit.Tooltip" connectId="something">Your pop-up text goes here</span>
								Where the connecId="" attribute MUST be the ID of the parent <label> tag.
									EXAMPLE: with <label class="has_csh" id="appserverTomcat">, the pop-up element is <span class="csh" dojotype="dijit.Tooltip" connectId="appserverTomcat">
							The CSS and javascript handle the rest.
		
		<div id="form_buttons">
			The contents are the submit and reset buttons/links. You shouldn't have to edit these.
			
			If you do, IBM UI standards are that the text should be in a headline capitalization (eg "Submit Your Preferences").
			
			The reset <button> is styled to look more like a link, because resetting is a secondary action.
			
			The form data is not actually submitted anywhere. The data is intercepted and parsed by the javascript, and used to parse out and do something with the results.

	<div id="results">
		This is the <div> that will be shown after the <form> is successfully submitted. You'll be spending a lot of time here.
		
		<h2>
			Another title. Be sure to update the product name
		
		<div class="bigStep">
			So, here's how everything works... all <div>s are hidden by default with CSS (display:none).
			I'll repeat that: ALL <div>s that are decendents of #results are INVISIBLE BY DEFAULT. ALL OF THEM.
			After you submit the form, the script checks what's been selected, and uses that data to change certain <div>s to visible (style="display:block"). Then they're visible. So you're selectively revealing blocks of content.
			The highest level of order is <div class="bigStep">. These are your MAJOR steps. (For example, "Retrieve application files" or "Deploy application files to your server.")
		CONDITIONAL CLASSES (forDB2, forTomcat, etc.)
			The additional classes on elements are the CONDITIONAL CLASSES. Every block that may or may not need to be seen requires one of these. Every <div> is hidden by default, and the script uses these classes to figure out what to then make visible. 
			You need conditional classes for EVERY SINGLE INPUT IN YOUR FORM. No exceptions!
			For example, for Database servers the user could use, they might have a choice of (a) DB2 that they have already, (b) they need DB2 from us, or (c) they have Oracle. So you'd need a conditional class for each of those: (a) forHasDB2, (b) forNeedsDb2, (c) forHasOracle.
			You can use anything you want for the classes, with the following exceptions:
				No spaces (you separate multiple CLASSES with spaces)
				Classes are case-sensitive!!
				Classes can't start with a number (0-9)
			I recommend the "forSomething" format, to help you keep them straight, but the names don't really matter.
			You must be absolutely consistent with these throughout!!!! Watch out for typos.
		
			<h3>
				Every <div class="bigStep"> needs an <h3> summary of the task.
				Step numbers will be added dynamically to this element if it's visible, so don't worry about them
			
			<div class="whatYouNeed">
				Think of this like prerequisites: list anything the user might need to complete this major task. Some questions to ask:
					What kind of administrative/file access do they need?
					What files do they need?
					What kind of information do they need?
					Licenses?
					Internet access?
				List them as an unordered list, in a <ul> tag.
				So many of our installs are just needing to know the right admin access, so better to highlight that info up front.
				
				<ul>
				
					<li>
						List items for the class="whatYouNeed"
						To make them visible/invisible based on form inputs, add the class="blockOption" and a conditional class.
							KNOWN BUG: Some <li> elements will appear without bullets if nearby ones are or were invisible, especially in Firefox. Not sure what's behind this.
							
			<p> or <ul> or <ol>
				Here's where you lay out, in plain language, links to the tasks that a user must complete. You can use this space to clarify instructions, or otherwise guide the user through the install process.
				
			Other <div>s
				Via CSS, ALL <divs> are invisible until the script reverses it.
				
				This is how you build very complicated, nested content: you must ask yourself, at each level, what could affect the install story here.
				
				FOR EXAMPLE, if you have a class="bigStep" like this:
					<div class="bigStep"> <!-- No condition here, so this will be visible ALWAYS after the form is submitted. -->
						<h3>Create the database tables for your product</h3> <!-- After each class="bigStep" you'll want a single <h3> visible. This is where the step counter will be placed dynamically.
						
						<p>You need to use your database software to create the tables</p> <!-- Everyone can see this, if the <div> container is visible.
						
						<div class="forDB2"> <!-- Only For people that need DB2 -->
							
							<div class="forNeedsDB2"> <!-- Only for people that NEED DB2. People that have it already don't need this information. -->
								<p><a href="t_install_db2.html">First, install DB2</a>. Then:</p>
							</div>

							<div class="forHasDB2"> <!-- Only for people that have DB2 already -->
								<p><a href="t_instructions_db2.html">Build your tables in DB2</a></p>
							</div>
							
						</div>
						
						<div class="forOracle"> <!-- Only For people that need Oracle -->
							<p><a href="t_instructions_Oracle.html">Build your tables in DB2</a></p>
						</div>
						
					</div>

			<a> links
				During the regular Dita->XHTML transform, .dita topics get turned into .html files. So link to .html files with your href="something.html" (not href="something.dita", since that's what'll be there.

			Repeat for each major installation step.
			
			When you're all done, it's time to tweak the roadmap.js javascript file.
			
			PLANNED ENHANCEMENT: With some complex CSS, we can add step counts without Javascript. It might not work on IE...
			
			
****************************

THE CSS FILE

****************************

You really shouldn't have to mess with these. I recommend against it.

The colors have been OK'd by MDS, and they currently match the aesthetic of our Rational ICs.


****************************

The Javacript file

****************************

The Javascript file is heavily commented to guide you through it. 

You have to really do four things. I've marked them in Comments in the file:

THIS REQUIRES YOUR INPUT, PART 1: 
	Define what happens when you click on certain form inputs.

	Basically, if I click an input, does anything else get de-selected? Or fully disabled?	 Or does clicking an input mean another form field MUST be a certain value?

	You'll create a Javascript Array of Objects with the ID attributes of the inputs. See the examples.
	
	FUTURE ENHANCEMENT: Write a function so you don't have to keep copy-pasting the Key/Value syntax.

	
Lots of functions that you shouldn't have to touch follow.

Then you'll get to THIS REQUIRES YOUR INPUT, PART 2:

	In the dojo.query function, list the IDs (using CSS selector notation: #idName and separated by commas) of elements that will ALWAYS be shown to users, no matter what they select.
	
	Alternatively, you can skip this, and just add a class of "seen" to any elements that you always want visible in the HTML file. Your call.
	
	It's probably faster to just list IDs here, for long-term maintenance.
	

THIS REQUIRES YOUR INPUT, PART 3:

	Just before this, there's a function dojo.formToObject that turns the form inputs into a Javascript object (o={}) after the user submits the form.
	
	Create variables out of each sub-object. The subobjects will be the name="" values from the FORM. So if the form had a name="operatingSystem" set up inputs, the value of that field, in the object, would be o.operatingSystem
	
	You'll be using these values extensively in a second, so name the variables something useful, or something easier to type than javascript objects.
	
	You don't necessarily have to do this. If you don't want to do this, just use the object notation (o.operatingSystem) in the next segment (Part 4).
	
THIS REQUIRES YOUR INPUT, PART 4:

	FUTURE ENHANCEMENT: Like part 1, I need to write a function that automates the key:value part of this for you.
	
	OK, you're editing another array (a=[]) with javascript objects with the following key/values:
		toCheck: the variable that represents the value from the form, above
		possibleValue: One of the values from the INPUT in the HTML page.
		classToShow: This should be "classes" to show. List classes, using CSS selector notation (.className, separate multiple classes with commas) that will be shown if the user has selected the possibleValue. So, all those conditional classes you had to figure out in the HTML? They go here.
		
		You can use multiple classes. In my roadmap, I have four conditional classes for WebSphere:
			forWASNode -- the user has a single node of WAS.
			forWASCluster -- the user has a WAS ND Cluster.
			forEWAS -- The user NEEDS WebSphere, and we include it for them in that case.
		And, the kicker:
			forWAS -- For any type of WAS. This content is of interest to anyone with WAS.
			
			So, say, if the user chooses "I have a WAS cluster" I want to show them BOTH the "forWASCluster" content, AND the "forWAS" content. So you'll see that my classToShow lists multiple classes: ".forWASCluster, .forWAS."
			
			With the ability to show multiple classes for each value, things can get complex quickly. You have to thoroughly plan this out in advance.
		
		Repeat for each input (each possibleValue) in the form.
		
		And that's it!!
		
		... ... or is it??
		
		
*************************************

DEBUGGING

*************************************

Save yourself the stress of waiting for Information Center builds and just test it locally. Open roadmap_form.html in a web browser from your hard drive.

If everything isn't working like it should -- trust me, it won't the first time -- here are some things you can do to track down the problem.

First and foremost, use Firefox 3.5+ to debug, and get Firebug: http://getfirebug.com/
	The ability to inspect the HTML and see logged javascript errors will be crucial.
	You can also use Chrome or Safari (they have very nice built-in Inspectors that are like Firebug) but I think Firebug is more user-friendly.
	
Second, look for a line (roughly line 180) labeled "DEBUGGING" in the javascript file. Uncomment the two lines with logging, and a reader-friendly list of all data submitted to the form will be added to Firebug's console.


Now, other problems:

FAQS:

	Q: Nothing is happening, and the Firebug console says my script is poorly formed??
	A: Quadruple check the format of the objects in the javascript file. Objects (in curly brackets {}) in the array must be separated by commas, but there MUST NOT be comma after the last one. Same deal with the "key: value," within of objects.	

	Q: Something that I expected to show up isn't there after I submit the form??
	A: Check things in this order:
		The conditional classes of the element that isn't showing up.
		The conditional classes of ALL PARENT ELEMENTS of the element that isn't showing up. If you don't make a containing <div> visible, the children can't be visible.
		Check that all elements are properly closed (</div>). You will be punished for poorly-formed HTML code. A decent HTML editor that allows you to collapse elements (like Notepad++) can help you here.
		Check for typos in the PART 4 of the script or for any of the above.
		
		

***************************************

ADDING THE ROADMAP TO A PLUGIN

***************************************

Here's some issues to tackle when you finally add it to your install guide plugin:

	ADDING IT TO A DITAMAP NAVIGATION
	
		Because it's not a .dita file, you'll have to specify META information in the DITAMAP manually.
		So, to the <topicref> you have to:
			Add a LOCKTITLE attribute (locktitle="yes")
			Add a NAVTITLE attribute
			Add <topicmeta> > <linktext> and <topicmeta> > <shortdesc> elements to the <topicref>
		EXAMPLE:
			<topicref format="html" href="topics/roadmap_form.html" locktitle="yes" navtitle="Guide for installing Rational Asset Manager">
				<topicmeta>
					<linktext>Guide for installing Rational Asset Manager</linktext>
					<shortdesc>Describe your environment and see all the steps to install Rational Asset Manager</shortdesc>
				</topicmeta>
			</topicref>
		
	CHANGE BUILD.PROPERTIES (if necessary)
		Make sure that the build.properties file for your plugin will allow the /topics/dojo/ folders, subfolders, and files; the roadmap_form.html file; and the CSS files (wherever you put those; I chose a /common/ folder). I used the following addition to the bin.includes argument:
		       topics/dojo/,\
               topics/dojo/*,\
               topics/dojo/*/*,\
               topics/dojo/*/*/*
               topics/*.htm*,\
               common/,\
		
		This is probably overkill, but it works.
		
		Your build rep can help with this.
	
	AFFECTS ON 1-PAGE HTML/PDF INSTALL GUIDES
	
		OK, these don't work AT ALL in a 1-page install guide. (Compiled from an IDD file)
	
		When creating the .idd file or the separate .ditamap for the .idd file, DO NOT INCLUDE the roadmap_form.html file. Just don't!!
		
		Because the 1-page HTML stands alone, the roadmap cannot be a part of the 1-pg HTML or PDF install guides.