Designing Wiki Output : Integrating ePublisher Online Help with the WebWorks Documentation Wiki
Integrating ePublisher Online Help with the WebWorks Documentation Wiki
The ePublisher product team has integrated the ePublisher online help with the WebWorks documentation Wiki. This integration provides the following benefits:
*WebWorks employees, partners, and customers can add comments, edits, and content to the ePublisher topics on the docs.webworks.com Wiki in real time, improving, enhancing, and extending the ePublisher documentation as needed instantaneously.
*ePublisher users with an Internet connection who view the ePublisher online help system installed on their computers can quickly see the following information:
*If a page they are viewing in the ePublisher help system on their local computer has been updated on the Wiki
*If other users have added comments about the page on the Wiki
For more information about how this integration appears to ePublisher users, see “Contacting Quadralay”.
This section contains information about how the ePublisher product team performed the integration. If you want to perform a similar integration, understand that your steps may be different based on the following combination of factors:
*How you generate your content
*The output formats you use
*The type of Wiki server you use
*How you configured your Wiki server
The information provided here is provided only as example information. It is intended to help advanced ePublisher Stationery designers who are comfortable performing complex ePublisher Stationery designs and customizations better understand the approach the ePublisher team used when integrating the ePublisher online help system with the docs.webworks.com Wiki.
To integrate the ePublisher online help system with content on the docs.webworks.com Wiki, the ePublisher team performed the following actions:
*Created an ePublisher WebWorks Help target that used the WebWorks Help output format.
*Created a docs.webworks.com Wiki target that used the Wiki - MoinMoin output format.
*Specified that ePublisher use the same page naming pattern for each target. This ensured that a content page generated for the WebWorks Help output used the same name as the corresponding page generated for the Wiki output. For more information about specifying file names for generated output, see “Defining File Names”.
*Created a status.html page and supporting image (.gif) and text (.txt) files. These files render the Wiki and Discussion links and radio buttons displayed in the top right corner of each page of the ePublisher online help system using a simple table and graphical layout. For more information about the status.html page and to see an example of a status.html page, see wiki.webworks.com/DevCenter/Projects/WikiFeedback.
*Created an AJAX JavaScript file to place on the docs.webworks.com Wiki server. The computer running the ePublisher online help system locally uses this script to obtain information about page status on the docs.webworks.com Wiki server. For more information about the AJAX JavaScript file and to see an example of the AJAX JavaScript, see wiki.webworks.com/DevCenter/Projects/WikiFeedback.
*Embedded an iframe element in the upper right corner of each page in the WebWorks Help system by modifying the Page.asp file. The iframe element displays the status.html page and its associated images and displays the Wiki and Discussion links and radio buttons. The iframe element also communicates with a page on the docs.webworks.com Wiki server that queries for updates on the Wiki server.
The iframe is an inline frame from a frame set that allows you to embed a document within another document. The ePublisher product team embedded an iframe on each page of the ePublisher online help set in order to give the pages in the ePublisher online help system a way to communicate with the docs.webworks.com Wiki. Without the iframe, the pages in the ePublisher online help system cannot communicate with the docs.webworks.com Wiki because they are simply HTML files running on the local file system. The iframe element is required in order to provide the security context needed for communication back to the docs.webworks.com Wiki.
Following is an example of the iframe element added to the Page.asp file for the ePublisher online help system:
<iframe src="http://docs.webworks.com/webworks_static/status/2009.1/status.html?/FrontPage" wwpage:attribute-src="wiki-status-url" width="96" height="43" frameborder="0" scrolling="no">
</iframe>
For more information about working with Page.asp files, see “Customizing the Content Page Design”.
When users access a page in the ePublisher online help system, the following actions occur:
1. The iframe element on each page of the ePublisher online help system communicates back to status.html page on the docs.webworks.com Wiki.
2. The status.html page calls the AJAX JavaScript on the docs.webworks.com Wiki to do an AJAX request to determine if there is a difference between the contents of the page in the online help system and on the docs.webworks.com Wiki.
3. If there is a difference, then the images presented in the frame on the ePublisher online help system page are updated to indicate new information is available.
4. Users can click the appropriate link in the ePublisher online help system to see the updated Wiki content or add a comment to the page on the Wiki.
The ePublisher online help and docs.webworks.com Wiki integration provides simple yet powerful example of how you can link and integrate an online help system with a Wiki, leveraging the easy-to-use, approachable feedback mechanisms built into Wiki software to update, enhance, and extend your content in real time.