home *** CD-ROM | disk | FTP | other *** search
/ Internet 53 / INTERNET53.iso / pc / software / windows / building / html_px / sample / uguide.htt < prev   
Encoding:
Text File  |  1999-01-19  |  6.3 KB  |  130 lines
  1. #set title htmlPX - User's Guide
  2.  
  3. {hdr}
  4.  
  5. #call section Introduction
  6.  
  7. <p>
  8. htmlPX, the HTML Programmer's Extension, is a tool to help the user build and maintain their website.
  9. htmlPX is a command-line Java application that pre-processes HTML template files to create HTML files.  It provides
  10. a way of creating consistent, well-designed websites easily.  It also supports maintenance by making it easy to
  11. modify the template files and then regenerate the website.  htmlPX was designed with the experienced power-user or
  12. programmer in mind.
  13.  
  14. <p>
  15. The basic process is that variables are defined and values are assigned to those variables.  Then HTML template files
  16. are processed and replacements are made based on keywords that match the variables.  Colors, images, text, and
  17. formatting can be dependent on the values assigned to each variable.  htmlPX also supports conditional generation
  18. based upon the values of the variables.  Other files can be inserted into the HTML files as they are being generated
  19. so that true reuse of code can be achieved.  This, of course, means that less HTML code actually has to
  20. be written.  When the processing has completed, a set of HTML files have been generated
  21. that are ready to be put onto the web.
  22.  
  23. #call section htmlPX Processing
  24.  
  25. To understand htmlPX, you must think of your website, many HTML files and assorted images and binary files, as a
  26. <b>project</b>.  htmlPX is a utility that will generate the website from the files that make up the project.  There
  27. are three types of files that make up an htmlPX project.  They are:
  28.  
  29. <ol>
  30. <li> the <b>.SF</b> file - the <i>site file</i>
  31. <li> <b>.HTT</b> files - the HTML <i>template</i> files
  32. <li> <b>.LIB</b> files - the code <i>library</i> files
  33. </ol>
  34.  
  35. <p>
  36. The site file is really the project file.  That file is passed to htmlPX where it serves as the driver behind the
  37. site generation process.  The site file contains definitions of global variables that will be used by the site and
  38. the <b>#MAKE</b> commands that identify the HTML template files that need to be processed to generate the desired
  39. site.  Each line in the .SF and the template files is checked to determine if it is an htmlPX command.  htmlPX
  40. commands all begin with the '#'.  If the line is a command, the command is processed.  If the line is not a
  41. command, it is written to the output file.
  42.  
  43. <p>
  44. One or more library files can be loaded by the site file.  Each library file contains variable definitions, code
  45. block definitions, and function definitions.  These defined "objects" can be used by any of the
  46. template files.
  47.  
  48. <p>
  49. Each #MAKE command results in an HTML template file being processed and an HTML file being generated.  Defined
  50. variables that are delimited by '{' in the front and '}' in the back are replaced by the value currently assigned
  51. to that variable.
  52. <p>
  53. You should read the <a href="ref.htm">Reference Guide</a> for a more detailed description of each command.
  54.  
  55. <p> A site file could look like the following:<br>
  56. <code>
  57. <br>#SET name Keith Wilson
  58. <br>#SET color red
  59. <br>#MAKE index.htt index.htm
  60. <br>#MAKE second.htt second.htm
  61. </code>
  62.  
  63. #call section Executing htmlPX
  64.  
  65. <p>
  66. htmlPX is a command-line program, so you execute it from a command-line shell.  A batch file is included as a
  67. sample, since it is easier to execute with a batch file.  Using the batch file included, you can execute it
  68. with a command such as<br><br>
  69. <code>
  70. htmlpx mysite.sf.
  71. </code>
  72.  
  73. <p>
  74. The complete format of the command is<br><br>
  75. <code>htmlpx [-a] <site file> [var1 var2 var3 var4 var5 var6 var7]</code><br><br>
  76. where [-a] is an optional parameter that causes all output files to be remade regardless of dates.  Var1 - var7
  77. are optional variables that are passed to the templates as keywords #CL1 - #CL7.  These can be used however you
  78. want within your htmlpx scripts.  One suggested use is for conditional generation.
  79.  
  80. #call section Sample Site
  81.  
  82. <p>
  83. The help files, which you are now looking at, serve as a sample of the use of htmlPX.  htmlPX was used to generate
  84. these help files.  You can go to the subdirectory SAMPLE where you installed htmlPX to see the template files,
  85. the library file, and the site file used to generate these files.  This is a rather simple example, but it serves
  86. as a reasonable starting place to begin learning the power of htmlPX.
  87.  
  88. #call section Special Topics
  89.  
  90. #call subsection Scope
  91.  
  92. <p>
  93. Variables, code blocks, and functions can be defined in the site file, a library file, a template file, or an
  94. included file.  The scope of the object varies depending on where it is defined.  The rule is quite simple, an
  95. object is only available at the level it is defined and all levels below.  Thus, a function defined in the library
  96. file is available for all template files and all included files that the template files access.  A code block
  97. defined in an included file will only be available in that template file, and will go out of scope and "
  98. disappear" when that template file is completed.
  99.  
  100. <p>
  101. An object can be overridden by a definition at a lower level.  When the new definition goes out of scope, the
  102. previous value or definition will be available once again.
  103.  
  104. #call subsection Placing Variables, Code Blocks, and Functions in Template Files
  105.  
  106. <p>
  107. Variables, code blocks, and functions can be defined in template files as well as library files.  When they are
  108. defined in template files, they are only available for that template file and will go out of scope when that
  109. file is completed.
  110.  
  111. #call subsection Processing Data Files
  112.  
  113. <p>
  114. ASCII text files can be processed as data files using the #FORALL/#ENDLOOP commands.  Each row in the data file
  115. will be processed in succession.  The fields in each row will be parsed and can be accessed by the code in the
  116. block by referring to them as {$1}, {$2}, etc.
  117.  
  118. #call subsection Which Output Files are Made?
  119.  
  120. <p>
  121. htmlPX has a make facility which allows HTML files that do not need to be remade to be skipped.  This makes it
  122. quicker to regenerate a site that has only a few changes in one or more template files.  You can cause all HTML
  123. files to be made by placing a '-a' parameter as the first parameter passed to htmlPX.  Please also read in the
  124. <a href="ref.htm">Reference Guide</a> about #USING to see more on the make facility.
  125.  
  126. {button}
  127. {foot}
  128.  
  129.  
  130.