Hypertext Templates

Hypertext Templates Customizing Visualizer Web Publishing Output v1.0 Perry A. Stupp Sr. Software Consultant

Introduction • Through the use of Hyptertext templates PATROL For Performance Management users can customize the output of their Visualizer Web Publishing efforts. This paper will explain how this process works and detail the steps required to address the most commonly requested changes to Visualizer’s output.

Outline • Necessary HTML Background. • Hypertext templates and the special <Visual/> variables • Controlling the browser through Dynamic HTML • Using VBScript and Javascript to modify output • Customizing the output with HTML Frames • Understanding the HTT Processing Flow • Generating the Web Publishing • Sample Output • Common Customization Requests • Supporting the customizations • Conclusion

Fundamental HTML • This section outlines the background information required to understand how to customize your Visualizer web publishing efforts using HTML and Javascript.

What are Hyptertext Templates? • Hypertext templates provide a code skeleton from which dynamic html pages can be derived. • Through a combination of copying code directly from the templates, performing variable substitution and Macro execution, the hyptertext templates produce html pages that contain dynamic content derived directly from the pages found within the Visualizer templates you are processing.

Variable Substitution / Macro Execution • Special tags embedded within the Hyptertext templates are expanded during processing to provide access to the content found within the Visualizer templates. These tags are easily identified by their Visual prefix. • <Visual/Variable> Where Variable can be any of • nGpP - Number of Graphs per Page in the template. • Scan=FILE.GRAPHIC - Replace the variable with the graphic file and • place a copy of the file in the output directory. • Scan=FILE.HTT - Force the processing of the hyptertext template, • replacing the entry with the name of the resulting • file. • Note - Replace with the notes for the project or page. • ByPage - Process the BYPAGE Template.

Variable Substitution / Macro Execution • PHdr - The Page Header (Numbered by default) • Pnum - The page number the graph is on • Page - Process the PERPAGE Template • Date - The date the page was generated. • (Not the date of the published data!) • Subl - The Text from the Graph’s Subtitle • Head - The name of the project • nPNF - Export a copy of the graph in PNF Format • nPNG - Export a copy of the graph in PNG Format • nJPE - Export a copy of the graph in JPE Format • nJPG - Export a copy of the graph in JPG Format • Graph - Process the PERGRAPH Template • ?Tbl - Is this graph a table? Returns Yes or No. • TREF - Execute the PERTABLE Template, replacing the • entry with the name of the resulting file.

Variable Substitution / Macro Execution • Cols=? - Replacing the question mark with anything else • will cause the output to be displayed in columns. • XinY=7 - Sets the Width of the Graph output • XinX=5 - Sets the Height of the Graph output • GREF - Execute the PERGRAPH Template, replacing • the entry with the name of the resulting file. • Titl - The Graph’s Title • PxlX - The width of the graph In Pixels • PxlY - The height of the graph In Pixels • PFtr - The Graph’s Footer • Tabl - Create the table for the values in the graph.

Dynamic HTML • Dynamic HTML can be used to create HTML documents that dynamically change their content and interact with the user. By using DHTML, authors can provide special effects on a Web page without relying on server-side programs. • Although there are a wide variety of objects available within DHTML model only the two used within the existing templates are discussed. • Document object – This object allows you to alter the properties of the document that you are displaying. The document.write() method allows you to write new content to the page as it is being rendered. • Navigator object – This object allows you to discover attributes about the browser that is displaying the page. This information can be used to identify the browser’s supported capabilities and provide custom results for the various browser types.

VBScript and JavaScript • A programming language is required to change the content of the Object Model. Javascript provides the most extensive language support since VBScript is only available in Microsoft’s Internet Explorer. For this reason, the current implementation uses Javascript although, if you have an all Microsoft environment, you may want to consider using VBScript instead (if it is easier or provides additional benefits / capabilities).

JavaScript • Although a full discussion of Javascript is beyond the scope of this presentation, a brief overview of some of the key operatives is appropriate. • To include Javascript in a web page, the code must be enclosed within the following tags: • <SCRIPT LANGUAGE=“JavaScript”> • … • </SCRIPT>

JavaScript • Other operatives include variable declaration and conditional logic as illustrated below. • <SCRIPT LANGUAGE=“JavaScript”> • var somevariable = 10 • if ( condition ) { • code to executed if true … • } else { • code to execute if false … • } • </SCRIPT>

Frames • Visualizer’s Web Publishing takes advantage of a modern browser’s ability to display content from multiple pages at one time. By splitting the screen into multiple partitions (or frames) it creates a functional user interface that allows both navigation and analysis at the same time.

Frames • Frames can be used to split a page into either columns or rows. Specifying the cols attribute splits the screen horizontally as illustrated. • The frame tag is used to specify the name and source of the html for the various columns on the page. <frameset cols=“300,*”> <frame name=“lefty” src=“left.htm”> <frame name=“righty” src=“right.htm”> <noframes>

Frames • Frames can also split a page into rows using the rows attribute. <frameset rows=“300,*”> <frame name=“top” src=“top.htm”> <frame name=“bot” src=“bottom.htm”> <noframes>

Frames • Frames can be nested to provide a series of columns and rows as with Visualizer’s default web publishing format. <frameset cols=“300,*”> <frameset rows=“150,*”> <frame name=“topleft”> <frame name=“bottomleft”> </frameset> <frame name=“rightside”> <noframes>

Frames • Some additional details about frames. • When splitting the frameset, you can specify the value in pixels or percentages. • <frameset cols="300,*"> • <frameset rows=“25%,*"> • The frame tag specifies the html source for the page (as specified by the src attribute). A name attribute can be also be applied allowing it to be referenced / altered by the DHTML object model. The ability to scroll within each of the pages is enabled by default, it can be explicitly included or excluded in each frame as appropriate. • <frame name="logo" src=“topleftpage.htm” scrolling="no">') • <frame name="contents" src=“bottomleftpage.htm" base target="main">') • When you click a hyperlink on a page that's displayed in one frame, the page pointed to by that hyperlink usually opens in another frame called the target frame. The special target “_self” means replace the content in the current page with the page referenced by the hyperlink. • <frame name="main" src=“rightpage.htm" base target="_self">')

Processing Flow • The Web Export processing flows through several templates before producing the final Web pages. Having a Visual representation of this flow makes it easier to understand when each step occurs and the output that it produces.

Template processing flow and output pergraph.htt bypage.htt project1.htt project.htt project.htm pertable.htt project1.jp? … projectN.jp? project1.htm project2.htm projectt1.htm … projecttN.htm bygraph.htt projectg1.htm … projectgN.htm perpage.htt project2.htt

Processing Flow – A Closer Look • When the Web Publishing process is started the first template to be called is project.htt. A closer look at the execution of this one template helps to illustrate what happens throughout the entire process. The processing of the project template can be split into three main section. - The header section is simply some HTML that initializes the page and creates a title. -The frame generation section lays down the DHTML that selects the display type (thumbnails or page selection). This section also launches the execution of the project1 and project2 templates. -The no frames section is what is displayed if your browser does not support frames, this includes the creation of the page background and any notes that have been included in the project. This section launches the PERPAGE template and ends with some content closing off the HTML page. {HEADER SUBSTITION} {FRAME GENERATION} {PROJECT1.HTT EXECUTION} {PROJECT2.HTT EXECUTION} {BMCLOGO.HTT EXECUTION} {NO FRAMES SECTION} {BACKGROUND} {PROJECT NOTES} {PERPAGE EXECUTION} {END OF PAGE DETAILS}

Processing Flow – A Closer Look • Taking a look at the results helps identify what happens during the processing phase. Project.htm - Output <HTML> <HEAD><TITLE>PROJECT NAME SUBSTITUTED HERE</title> </head> <SCRIPT LANGUAGE=“JavaScript” var GraphCount = 3 document.write('<frameset cols="300,*">') document.write('<frameset rows="150,*">') … '<frame name="logo" src=BMCCOLOR.HTM’ … if (3 > 1) … '<frame name="contents" src="PROJECT1.HTM" … else … '<frame name="contents" src="PROJECT2.HTM" … document.write('</Frameset>') Project.htt - Source <HTML> <HEAD><TITLE><Visual/Head></title> </head> <SCRIPT LANGUAGE="JavaScript"> var GraphCount = <Visual/nGpP> document.write('<frameset cols="300,*">') document.write('<frameset rows="150,*">') … ‘<frame name="logo" src=<Visual/Scan=BMCCOLOR.HTT>’ … if (<Visual/nGpP> > 1) … '<frame name="contents" src="<Visual/Scan=PROJECT1.HTT>" … else … '<frame name="contents" src="<Visual/Scan=PROJECT2.HTT>" … document.write('</Frameset>')

Processing Flow – A Closer Look • What is most interesting about the execution of the project template is what happens to the <Visual/Page> variable. Unlike the <Visual/Scan=PROJECTN.HTT> call which forces the execution of the PROJECT templates and the creation of separate hypertext pages, this call to the perpage template results in the output of the execution being redirected back into the project html page. Project.htm - Output <SCRIPT Language="JavaScript"> if (GraphCount > 1) { document.write('<CENTER><H3>Page 1</h3></center>') document.write('<CENTER><table cols=3 width="66%" align=center>') } </SCRIPT> <td> <SCRIPT LANGUAGE="JavaScript"> fname='sample2g4.htm' … This repeats for each page in the template… Project.htt - Source <Visual/Page>

Generating Web Publishing • This section covers some of the steps necessary to produce the Web Publishing output available from Visualizer. • Although a discussion on how to build effective templates is probably warranted it is beyond the scope of this presentation and should be addressed in a separate paper. As such, it is assumed that the user knows how to build at least a basic template for use with this effort.

Generating Web Publishing • There are two ways to generate Web Publishing from your Visualizer Templates. • Export - Writes out the Web Pages onto the local machine. • Web Publish – Writes out the Web Pages onto the local machine temporarily and then transfers them (via http or ftp) to a Web Server to be published.

Accessing the Publishing options • The Web Publishing option may be grayed out if you do not have the Microsoft Web Publishing Wizard installed. You can obtain a copy of this wizard from the Microsoft Web Site at: • http://windowsupdate.microsoft.com

Accessing the Publishing options • Using Automator, you can create Web Publishing through the Graphics / Costing events.

Accessing the Publishing options • You can also use a keystroke file to script the processing of the export which yields additional flexibility.

Specifying an alternate path for HTT’s • By default, the publishing mechanism will look to the Visualizer installation directory for the HTT files. Through the use of keystroke files, you can override this location. At the risk of a minor increase in complexity, this provides the following benefits: • It permits different customization for different groups of nodes. • It ensures that the htt files are not overwritten when an upgrade is performed.

Specifying an alternate path for HTT’s • To modify the location of the HTT files using keystrokes merely add the following line to your keystroke file; • {SetREPT} “c:\some path\…” • Note: If you choose to use the default BMC Logo’s then you will need to copy these files into this alternate path.

Exporting Tables • If you would like to make the underlying values within the graphs available as tabular output, simply add a note for the project with the following text: • (see table)

Exporting Tables • Now when you drill down into the individual graphs you will see an option to show the table associated with the underlying values.

Exporting Tables • Drilling down into the “Show Table” link reveals the underlying values for the graphs. End-users can easily cut and paste these tables into other applications like Excel if they wish.

Sample output • The output for Web Publishing will vary depending on the format of your template, largely due to the number of graphs within each page.

How page layout affects the output • If you create your template with more than one graph per page then the frame on the left side of web the page will contain a list of available pages.

Main Web Page – Multiple Graphs / page

How page layout affects the output • If you create your template with only one graph per page then the frame on the left side of the web page will contain one thumbnail per page.

Main Web Page – Single Graph / page

How page layout affects the output • Looking at the html for the main page (project.htm), you can see the DHTML statements that are used to select the html page for the page / graphic selection pane (bottom left panel). • If there are two or more graphs per page then the project1 html will be used, otherwise, the project2 html file will be displayed. if ( 2 > 1) document.write('<frame name="contents" src="sample1.htm" base target="main">') else document.write('<frame name="contents" src="sample2.htm" base target="main">')

If your Browser does not support frames • If your Web browser doesn’t support frames, then it is unlikely that it will support DHTML which is necessary to fully render the document. If it does support DHTML then you should see something like…

Common Customization Requests • This section outlines some of the most commonly requested customizations to the Web Publishing output as well as the changes to the Hypertext templates required to achieve the desired results.

Common Customization Requests • I have to scroll to see the entire graph, can I change the size so that it appears in the window? • In the pergraph.htt file add the following lines: • <Visual/Cols=?> • <Visual/XinX=7> • <Visual/XinY=5> • <td> • <SCRIPT LANGUAGE="JavaScript"> • This will create graphs that are 7” x 5”, change the values as per your requirements.

Common Customization Requests • How do I swap out the BMC Logo for my own? • In the bmccolor.htt file replace the name of the Scan file with your own logo: • <Img Src="<Visual/Scan=BMCLOGO.GIF>"> • <Img Src="<Visual/Scan=MYLOGO.GIF>"> • The same can be done for the wallpaper in the bmclogo.htt file. • Make sure that your logo file is in the directory specified by the {SetREPT} option in the keystroke file (if used) or else in the Visualizer installation directory.

Common Customization Requests • My site doesn’t allow frames, can I produce web pages without them? • Although the content will display in browsers that don’t support frames, some companies don’t want (or allow) the use of frames on their web sites. To remove the frames, simply remove the lines highlighted in red below from the project.htt file. • <HTML> • <HEAD><TITLE><Visual/Head></title> • </head> • <SCRIPT LANGUAGE="JavaScript"> • var GraphCount = <Visual/nGpP> • document.write('<frameset cols=“300,*">') • document.write('<frameset rows="150,*">') • document.write('<frame name="logo" src=<Visual/Scan=BMCCOLOR.HTT> scrolling="no">') • if (<Visual/nGpP> > 1) • document.write('<frame name="contents" src="<Visual/Scan=PROJECT1.HTT>" base target="main">') • else • document.write('<frame name="contents" src="<Visual/Scan=PROJECT2.HTT>" base target="main">') • document.write('</Frameset>') • document.write('<frame name="main" src="<Visual/Scan=BMCLOGO.HTT>" base target="_self">') • document.write('</Frameset>') • document.write('<Noframe>') • </SCRIPT>

Common Customization Requests • I prefer the thumbnail output format but my templates have more than one graph in each page, can I change this? • If you’re committed to a particular format for your output then you can simply remove the conditional logic that controls the format selection. From the Project.htt file, simply remove the lines highlighted in Red. • <HTML> • <HEAD><TITLE><Visual/Head></title> • </head> • <SCRIPT LANGUAGE="JavaScript"> • var GraphCount = <Visual/nGpP> • document.write('<frameset cols=“300,*">') • document.write('<frameset rows="150,*">') • document.write('<frame name="logo" src=<Visual/Scan=BMCCOLOR.HTT> scrolling="no">') • if (<Visual/nGpP> > 1) • document.write('<frame name="contents" src="<Visual/Scan=PROJECT1.HTT>" base target="main">') • else • document.write('<frame name="contents" src="<Visual/Scan=PROJECT2.HTT>" base target="main">') • document.write('</Frameset>') • - Remember, by using the {SetREPT} option in a keystroke file, you do not need to commit to this format for all templates! - By keeping the PROJECT2.HTT line instead, you can force the use of pages even if you have only one graph per page.

Common Customization Requests • Can I use Server Side Javascript or VBScript? • Provided the resulting pages are executed from a Web Server that supports scripting then you can, with a little creativity, include a limited amount server side code within your Web Publishing efforts. Over the course of the next few pages, an example of this process is illustrated for use on a IIS Server. Similar approaches can be used to provide the same functionality for JSP servers or CGI based Unix Servers. • Since the web pages produced through the publishing macros do not contain a .asp (or similar scripting) extension, they can not run server side code. Only by wrapping the existing code within an asp script can we actually achieve sever side scripting. • Remember, once this approach has been used, the pages will display only through a supported web server and will not work if executed directly through a browser on the local files.

Common Customization Requests • Can I use Server Side Javascript or VBScript? • First we need to modify the project.htt file to add the following code (highlighted in red); • document.write('<frameset rows="150,*">') • document.write('<frame name="logo" src=<Visual/Scan=BMCCOLOR.HTT> scrolling="no">') •  •  •  • <!– When using this approach it is easiest to simply select the format we want • rather than using the if GraphCount logic --> • document.write('<frame name="contents" src="<Visual/Scan=DYNCONT.ASP>" base target="main">') • document.write('</Frameset>')

Common Customization Requests • Can I use Server Side Javascript or VBScript? • Next, we need to create the dynamic content file (DYNCONT.ASP). Since there is no way to select an include file dynamically (at least not with ASP) we must know the name of the project file that we want to incorporate into our reporting from the dynamic content . As such, it becomes imperative that you use the keystroke file {SetREPT} option to ensure that the templates for this project are unique (since the project html filename that we must reference will be unique). The dynamic page might look something like this: •  • <Body><H3>It is now <%=Now()%></H3> •  •  •

Common Customization Requests • The results of applying the customizations discussed.

Common Customization Requests • Can I use Server Side Javascript or VBScript? • Unfortunately this means that server side code can only be run before or after the published html not throughout it.

Supporting your customization efforts • My web publishing has broken should I call support? • As you have seen, using Hyptertext Templates to customize your Web Publishing requires knowledge of several web based technologies. The flexibility of DHTML and Javascript provide limitless opportunities to customize your solution but also ample opportunity to introduce bugs into the publishing process. • As such, the only truly “supportable” configuration is the default Hypertext Templates that ship with the product. If you choose to modify these files, then be prepared to troubleshoot and debug them when problems arise – Support will be unable to help you with this process and should not be contacted. Enhancement requests, however, should continue to be submitted through the standard support channel. • If you find that your Web Publishing is no longer working, please revert to a saved copy of your configuration or else replace your templates with the originals from the installation directory. If after restoring the original files, your publishing still does not work then you should contact support. • Should you require additional assistance with your customization, please feel free to contact the author of this paper who will, on a best effort basis, attempt to respond as quickly as possible to your questions / comments.

Hypertext Templates