| To help end users get up to speed quickly, Contribute dedicates a section of the sidebar to answer the question, "How do I...?" The How Do I area provides links to explanations about common tasks, such as connecting to a Web site or editing a Web page. Although this areaalso called the Tasks panel in documentation for the Contribute developeris generally useful for the full spectrum of Contribute users, you might find as a Web designer/developer that you want to offer specific help to certain clients. Contribute is flexible enough to allow a complete customization and co-branding of the How Do I panel. Before we delve into customizing the How Do I panel, let's take a moment to see how it works from the user's perspective so that we can get a better idea of what's possible. 1. | In Contribute, expand the sidebar, if necessary, by clicking the arrow in the middle of the horizontal border. If you don't see topics in the How Do I panel, click the How Do I heading to expand the panel.
Users have complete control over hiding or exposing the How Do I panel. By default, the sidebar and How Do I panel are open, with the initial "Get started" topic heading expanded.
The How Do I panel appears as an outline with three topic headings: "Get started," "Add a page to my website," and "Administer a website." The headings are collapsible/expandable links for hiding or exposing their content. Each of these content items is linked to a specific task within the general category, such as starting the Contribute tutorial.
| 2. | Click the "Add a page to my website" heading to expand it. Select the "Add a new web page" option. When the new topic appears, choose either of the two links in the text: "Create a new page and link" or "Create a new page first." When your topic appears, note the structure of the document and then click Back. After you return to the "Add a new Web page" entry, click Topics to return to the main topic listing.
After you choose a link, every page has a Back button for viewing the preceding page, as well as a direct link to the top level of topics. If necessary, links within the help items (which can contain both text and images) allow the user to drill down to other items for more information.
| 3. | From the main topic listings, expand "Get started" if necessary and then click the "Contribute tutorial" link; when the subtopic opens, click the "Connect to a website" link. In the "Connect to a website" topic, click the text labeled "this link."
 In addition to displaying content within the How Do I panel, Contribute can open one special file in the built-in browser: the tutorial. The tutorial, used in conjunction with material in the How Do I panel, provides a generic learning environment so content contributors can learn the basics of Contribute.
|
Substituting Your Own Tutorial If you want to offer users some practice based more specifically on your organization, you can replace the standard tutorial with your own pages. Again, the key is to work with the pages found in the Content subfolder within the Contribute 3 system configuration directory. Inside the Content folder, you'll find another subfolder called Tutorial. All of your tutorial materialpages, images, style sheets, and even templatesmust reside in this folder, and the new home page for the tutorial must be stored as index.htm. The Contribute tutorial has only three sample pages, but you're not limited to any particular number of pages. If you decide to customize the tutorial, you have to alter the content of the relevant How Do I pages, as well, to ensure that the steps offered are correct. |
Understanding the How Do I Panel Structure All the files used in the How Do I panel are located in a directory within the Contribute 3 system Configuration folder, Configuration/Contents/Tasks. Two XML files are used to define the structure as well as the content of the top-level topic outline: TasksLayout.xml. Describes the structure of the initial How Do I panel outline by defining a series of elements (that is, category, category_section, category_separators) that are to be created in HTML. Tasks.xml. Lists the topic headers and each of the topic items, as well as links to the specific task items.
At launch, Contribute creates the initial How Do I panel display by reading both these files and programmatically combining them. The content displayed in the How Do I panel consists of a series of HTML files, numbered sequentially; the standard Contribute installation includes through task77.htm. The number-based naming convention is not required; you can replace all the task files'default names with custom names of your choosing. Let's take a closer look at each of the three file types and see how you might customize them. TasksLayout.xml File To maintain the most flexibility, Contribute uses the TasksLayout.xml file as the structural foundation for the various components of the How Do I panel. In a sense, this XML file acts as a structural style sheet; but instead of CSS selectors and rules, TasksLayout.xml works with table elements. For example, the overall structure, called main, is described like this: <main> <![CDATA[ <table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr> <td>{category_sections+category_separators}</td> </tr> </table> ]]> </main>
Notice that the table's content, within the <td> cell, consists of a couple of variables in curly braces: {category_sections+category_separators}. These variables refer to two of the other components defined in the TasksLayout.xml file. In all, there are seven components: main, category_section, category, category_separator, tasks, tasks_separator, and images. As you'll see later in this lesson, you can modify the TasksLayout.xml file to add a custom header to the opening page of the How Do I panel. Tasks.xml File The Tasks.xml file provides the content to fill out the structure described in TasksLayout.xml; in a sense, it's an outline view of the How Do I panel. This XML file comprises a series of <category> tagsin the standard Contribute setup, one for each of the three primary topicswhich contain, in turn, the individual <task> tags that define each topic. Here's how the initial topic, Get Started, is coded: <category name="Get started" > <task name="Contribute tutorial" file="task2.htm" /> <task name="Connect to a website" file="task14.htm" /> <task name="Navigate to my web pages" file="task17.htm" /> <task name="Edit a page on my website" file="task18.htm" /> <task name="Review a draft" file="task21.htm" /> <task name="Become a website administrator" file="task22.htm" /> </category>
If you look closely at the file, you'll see that there are six <category> tags, but only three topics show initially. The other three categories ("Add content to a web page," "Modify a web page," and "Finish up") are displayed only when Contribute is in edit mode. To show a <category> tag's contents while in edit mode, you need to add the enabled attribute to the tag, like this: <category name="Modify a web page" enabled="CCWorkspaceManager.getManager(dw.getDocumentDOM()).getState() == 'edit'" >
HTML Task Files For the most part, the HTML task files are straight HTML. Open any of them in Dreamweaver; you'll see a basic table layout with the content between navigation elements on top and below. The primary difference between these files and a regular HTML file are the links. To display the linked page within the How Do I panel, as almost all the links do, a call is made to a Contribute API function. Here's the code for linking to another HTML task file: <a href="#" onMouseUp="dw.tasksPalette.browseToPage('task3.htm')"> Connect to a website</a>
Notice that a specific JavaScript mouse event is referenced. The onMouseUp event triggers the Contribute API function dw.tasksPalette.browseToPage() and passes the filename, task3.htm, as an argument. If the browseToPage() function is called without an argument, like this: onMouseUp="dw.tasksPalette.browseToPage('')"
the link displays the opening categories defined in Tasks.xml. Note Although the vast majority of the links are intended to open in the How Do I panel, it's possible to open a specific file in Contribute's built-in browser. The API function dw.openCCTutorialSite() displays the index.htm file found in the Contribute/Configuration/Content/Tutorial folder.
When creating custom HTML task pages, you're freewithin certain limitationsto design the pages as you like. Images and other media must be stored within the Tasks folder. Although it is possible to use <div> tags rather than <table> tags to structure the layout, you can't add behaviors such as Show/Hide Layer to the pages. I've found that the easiest course is to replicate the current structure and simply replace the content. Creating New How Do I Panel Material Now that you have a good sense of which components make up the How Do I panel, you can begin your customization. All the work in this section takes place in Dreamweaver with the new site created for the Contribute 3 system configuration folder. The changes are immediately apparent when Contribute is relaunched. 1. | In Dreamweaver's Files panel, expand first the Content folder and then the Tasks folder within it. Double-click the TasksLayout.xml file to open it.
If you've never worked with XML files in Dreamweaver, you might be surprised that there is no Design or Split view; only Code view is available with XML files.
| 2. | Locate the XML tag <main> and place your cursor after the code directly below the tag <! [CDATA[. Press Enter (Return) to create a new line and enter the following code:
<h4>Courtesy of <br>Bounty General, Inc.</h4>
Choose File > Save to store the changes.
The XML CDATA tag acts as a container for HTML (CDATA is short for character data). Any text within the inner square brackets is inserted into the HTML page constructed for the How Do I panel. The text you just entered appears on the default page of the How Do I panel, but on no other pages.
In larger organizations, it's quite common for the majority of Contribute users to have no administrative functionality whatsoever. To reflect that reality, you'll remove the administration topics in the How Do I panel.
| 3. | From the Files panel, in the Tasks folder, double-click the Tasks.xml file to open it. When the file opens, locate and select the following code block near the bottom of the file:
<category name="Administer a website" > <task name="Define user roles" file="task73.htm" /> <task name="Set up other users" file="task74.htm" /> <task name="Enable page rollback" file="task75.htm" /> <task name="Enable users to delete files" file="task76.htm" /> <task name="Enable event logging" file="task77.htm" /> </category>
Choose Window > Snippets; when the Snippets panel opens, expand the Comments folder and double-click the Comment, Multi-line snippet to insert it.
 XML code can be commented out in the same fashion as HTML code. Generally, when working with system files, it's a better idea to comment out a block of code rather than delete it. To restore the code, just remove the opening <!-- and closing --> comment tags.
Let's add our own topic with information for users on how to get company-specific assistance.
| 4. | Place your cursor before the final tag in the file (</tasks>) and enter this code:
<category name="Get help" > <task name="Connection questions" file="bg100.htm" /> <task name="Design issues" file="bg110.htm" /> <task name="New pages needed" file="bg120.htm" /> </category>
Choose File > Save to store your changes.
Now the Tasks panel has a custom header and topics. In our final step, you'll finish by building one of the new HTML files.
| 5. | From the Files panel, double-click task75.htm to open it for editing. Choose File > Save As. When the Save As dialog box opens, make sure that you're in the Tasks folder and enter bg100.htm in the File Name field. Click Save to store the copied file.
Although you could build these pages from scratch, there's no reason to do so. If you copy an existing page, certain key navigational elements such as the Back and Topics button are already in place. Moreover, a consistent design structure throughout the How Do I panel makes it easier for users to concentrate on the content.
| 6. | When the file opens, in the Title field of the Document toolbar, replace "Enable page rollback" with Connection questions and press Enter (Return). In the Document window, select the heading "Enable page rollback" and again replace it with Connection questions.
The other chores to be done on this page are to replace the current text with material relevant to the new topic. The goal is to maintain the overall structure while updating the content.
| 7. | Remove the panel's opening sentence, which starts with "Contribute can maintain rollback..." and enter this text:
When you have problems connecting to the Bounty General site in Contribute, follow the recommended steps below.
| 8. | Replace the text "To enable page rollback:" with this text:
To get help making a connection in Contribute:
| 9. | Delete the text in the panel's first step and enter this text:
If you can't remember your username or password, contact your department manager.
| 10. | Remove the text in the second step and insert this text in its place:
If you are sure you've entered the correct username and password, but it is not recognized by the system, call IT at x4453.
| 11. | Place your cursor in the text below the second step that starts "The Administer Website..." and choose Modify > Table > Delete Row.
| 12. | Replace the text in the third step with the following:
For general information about making a connection in Contribute, click here.
| 13. | With your cursor anywhere in the new content, select the rightmost <table> tag in the Tag Selector. In the Property inspector, change the Rows value from 7 to 3 to delete the last four rows.
As noted earlier, creating a link to another topic in the How Do I panel is very different from the standard technique. Although an <a> tag is used, it's only to trigger a JavaScript event: onMouseUp.
| 14. | Select the phrase "click here" in the last step and enter # in the Property inspector's Link field. From the Styles list, choose alinkcustom to style the link. Press Ctrl+T (Command+T) twice to display the Quick Tag Editor in edit mode. In the pop-up tag editor, move your cursor to the end of the tag, just before the closing right angle bracket (>). Enter a space and then insert this code:
onMouseUp="dw.tasksPalette.browseToPage('task14.htm')"
When you're done, press Enter (Return) to confirm your tag change.
If you need to link to an existing How Do I panel page, your best source is the tasks.xml file, in which you can find a listing of all the titles of the pages with their corresponding filenames.
| 15. | Choose File > Save to store the file. Quit Contribute if it's open and then restart. In the How Do I panel, expand the "Get help" category and choose "Connection questions." When the "Connection issues" topic appears, verify that all your text is present. Click the "click here" link to go to the "Connect to a website" topic. On that topic page, click Back to return to the "Connection issues" topic; click Topics to revisit the main How Do I topic page.
|
As an additional exercise, you can create topic pages for the other two entries in the "Get help" category: "Design issues" and "New pages needed." Follow the same technique of copying an existing Contribute tasks page and save it with a different filename. For consistency's sake, continue the naming convention started with the initial new file, bg100.htm, and name your files bg101.htm and bg102.htm. |
