PROGRAM PTM Parser Application (PPA) 0.5.1 Beta [ptm.cgi] VERSION 0.5.1 Beta AUTHOR Michael L. Spencer (xmxspencer@users.sourceforge.net) CREATED 09.17.2005 MODIFIED 04.16.2006 COPYRIGHT 2005-2006 Michael L. Spencer ADDITIONAL PACKAGED FILES PTMDB Database Interface Module 0.5.0 Beta [PTMDB.pm] RSS20 Class Module 0.5.0 Beta [RSS20.pm] PTM Test Page 0.5.1 Beta [index.ptm] PTM .htaccess redirect for Server Integration Emulation 0.5.0 Beta [.htaccess] -------- I. INDEX -------- I. Index II. COPYING - GNU General Public License III. DESCRIPTION IV. INSTALLATION V. LANGUAGE OVERVIEW ---------------------------------------- II. COPYING - GNU General Public License ---------------------------------------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA ---------------- III. DESCRIPTION ---------------- PTM is a Perl/HTML hybrid, that uses inline, HTML-style tags to implement Perl within your dynamic web development file tree. It acts as a developers' front-end for commonly used Perl interfaces such as the CGI and DBI modules, while allowing you to drop your Perl code in right where you need it. PTM effectively streamlines development time by wrapping HTML form data, cookies, and database functionality into neat, predefined functions and variables. Additionally, it provides functionality that would, otherwise, take a lot of time to implement even for a single use; such as encoded ID cookie-based sessions and a well rounded set of wrapper functions that can currently be used on nearly every major database type on the market, including MySQL, MS SQL, mSQL (Mini SQL), Oracle, Sybase, Informix, and ADO, just to name a few. And those aren't different functions; the SAME functions can be used across all database types, so there aren't an infinite number of new functions and syntaxes to learn every time you switch databases. Most importantly, PTM is entirely written in Perl -- the very language it was written to implement. This has a variety of advantages, but primarily there are three (3) that prominently stand out. First, the ONLY requirements to run PTM are that you are on an Apache host server that has Perl/CGI support installed. Considering over 70% of the world's web servers run Apache, and almost all of them have Perl installed (SIGNIFICANTLY more than PHP or ASP), that's a great requirement set. Secondly, your host doesn't even need to support PTM for you to get started with it right away! Unlike alternatives such as PHP or ASP, your host doesn't even need to install PTM for you to use it. You can fully emulate server support simply by dropping the PPA (PTM Parser Application) into your cgi-bin and the prewritten .htaccess file in your root web accessible directory and you're ready to go. This is also handy if your host is running an older version of PTM, and you'd like to upgrade to a new one -- particularly if they aren't keeping their software up to date. Third, because PTM is written in Perl, and implements Perl, odds are that your average PTM developer can go so far as to modify PTM itself. Unlike many other languages, PTM doesn't restrict the developer to it's predefined list of functions and global variables. Users can write and reuse their own plugin modules, and, for the particularly crafty Perl programmers, even modify the language itself to fit their needs. ----------------------------- IV. INSTALLATION INSTRUCTIONS ----------------------------- Because this is a UNIX release, the installation information provided here will be for installation in a UNIX/Linux environment running the Apache web server. However, much of the focus of this content is on Apache's httpd.conf config file and is, therefore, very similar on a Microsoft Windows configuration as well. It should first be stated that the PTM Parser Application (PPA) may be installed/used in three ways: 1) As a standalone parser to which all requests are directed and subsequent redirection and loading of files is handled automatically with use of the packaged .htaccess file 2) As a built-in server-side PTM parser loaded via Apache's httpd.conf 3) Via the command line, accepting file names from the command line via the predefined global @ARGV variable ASSUMPTIONS - Perl is installed to /usr/bin/perl and is in your system's PATH variable list - *.cgi files have been associated with Perl to run as cgi-scripts - You have standard Perl modules such as CGI, Fcntl, and possibly DBI and any required DBD modules (for the PTMDB module) installed Please contact your system administrator if you are unsure of any of these assumptions. ----------------------------------------------------------------------- STANDALONE PARSER - Emulated Integration - You are a User on the server ----------------------------------------------------------------------- 1) Copy the "ptm_test" directory to your web accessible DocumentRoot directory (the base directory of your web accessible file tree) - chmod 755 both the /ptm_test/ directory and the "index.ptm" file within 2) Copy the PPA (ptm.cgi) and any PTM Perl module files (*.pm) from the "ptm" directory into your web server's /cgi-bin/ directory - chmod 755 the PPA (ptm.cgi) and any PTM Perl module files (*.pm) 3) Open the PPA (ptm.cgi) in your text editor of choice and modify the $_DOCUMENT_ROOT line's value to be either the absolute physical path to your DocumentRoot directory (the base directory of your web accessible file tree) or the relative physical path from your /cgi-bin/ directory to your DocumentRoot directory. If $_DOCUMENT_ROOT is left empty, it will attempt to pull the value from the DOCUMENT_ROOT system evironment variable. - EXAMPLE: - Assume /cgi-bin/ is "/var/www/cgi-bin" - Assume DocumentRoot is "/var/www/html" Modify the PPA's $_DOCUMENT_ROOT line to be one of the following: ABSOLUTE PATH: $_DOCUMENT_ROOT = '/var/www/html'; RELATIVE PATH (if you don't know the absolute path): $_DOCUMENT_ROOT = '../html'; - if necessary, also change the first line of the PPA (ptm.cgi) file (#!/usr/bin/perl) to match your server's installed Perl path. Once modifications are complete, close the PPA (ptm.cgi) file. 4) Copy the ".htaccess" file from the "htaccess" directory to your web accessible DocumentRoot directory (the base directory of your web accessible file tree) - chmod 755 the ".htaccess" file - If you are virtually hosted, or are installing PTM to only run within a certain directory (and its children) after placing the .htaccess file, open it and adjust the RewriteBase to match this subdirectory. For example, if you are planning on hosting PTM scripts only within the /scripts/ directory (http://www.site.com/scripts/) then your RewriteBase should be changed from "/" to "/scripts/". 5) Use your web browser to navigate to the newly installed test directory - if on local machine: "http://127.0.0.1/ptm_test/" - may need to adjust for port if you're running Apache on a non-standard port -- e.g. "http://127.0.0.1:8080/ptm_test/" 6) If all was successful you should now be looking at the PTM test page 7) Write as many PTM scripts as you like and use them everywhere ;) 8) Thats all for now! ---------------------------------------------------------------------------- APACHE'S httpd.conf FILE - Full Integration - You are a System Administrator ---------------------------------------------------------------------------- ASSUMPTIONS - You have reasonable knowledge of the Apache httpd.conf file and know approximately where specific lines belong 1) Copy the source file directory (ptm) to "/usr/bin/" (/usr/bin/ptm/) - or applicable perl installation directory - if necessary, open the PPA script file (ptm.cgi) and change the first line of the file (#!/usr/bin/perl) to match your installed Perl path. - chmod 755 the /ptm/ directory, the PPA (ptm.cgi), and any PTM Perl module files (*.pm) within 2) Copy the test directory (ptm_test) to your httpd DocumentRoot directory - e.g. "/var/www/html/ptm_test" - chmod 755 both the /ptm_test/ directory and the "index.ptm" file within 3) Open the httpd.conf file - default path is usually one of the following: /etc/httpd/conf/httpd.conf /usr/local/apache/conf/httpd.conf 4) Add the following 3 lines in their appropriate positions: (make any necessary path adjustments) ScriptAlias /ptm/ "/usr/bin/ptm/" AddType application/x-httpd-ptm .ptm Action application/x-httpd-ptm "/ptm/ptm.cgi" 5) Add "index.ptm" (no quotes) to the end of your "DirectoryIndex" list 6) Save and close the httpd.conf file 7) Restart Apache service 8) Use your web browser to navigate to the newly installed test directory - if on local machine: "http://127.0.0.1/ptm_test/" - may need to adjust for port if you're running Apache on a non-standard port -- e.g. "http://127.0.0.1:8080/ptm_test/" 9) If all was successful you should now be looking at the PTM test page - if you did not not add "index.ptm" to your DirectoryIndex per Instruction #5, append the file name "index.ptm" to the end of the URL 10) Write as many PTM scripts as you like and use them everywhere ;) 11) Thats all for now! -------------------------------------------------------------------- VIA COMMAND-LINE - No Integration (most commonly used as debug mode) -------------------------------------------------------------------- 1) Copy the "ptm_test" directory to your directory of choice - chmod 755 both the /ptm_test/ directory and the "index.ptm" file within 2) Copy the PPA (ptm.cgi) and any PTM Perl modules (*.pm) from the "ptm" directory into your newly installed "ptm_test" directory - chmod 755 the PPA (ptm.cgi) and any PTM Perl module files (*.pm) - if necessary, open the PPA script file (ptm.cgi) and change the first line of the file (#!/usr/bin/perl) to match your installed Perl path. 3) Via command line, navigate to your newly installed "ptm_test" directory 4) Run the PPA script file (ptm.cgi) - PTM script file name should be added as follows: [user@host ptm_test]$ perl ptm.cgi index.ptm 5) If all was successful you should now be looking at the PTM test page output code 6) Write as many PTM scripts as you like and use them everywhere ;) 7) Thats all for now! -------------------- V. LANGUAGE OVERVIEW -------------------- Definition of terms: PTM - The name of the language, short for "Perl Template" PPA - Short for "PTM Parser Application", refers to the "ptm.cgi" file PTMDB - PTM's Database interface module RSS20 - PTM's RSS 2.0 compatible XML stream parser module PTM, allows for inline Perl/HTML. More precicely, it allows you to put Perl code right in the middle of your HTML. To facilitate users that are used to working in the popular PHP language, the following global variables have been created: %_SERVER - PTM equivalent of PHP's _SERVER variable %_GET - PTM equivalent of PHP's _GET variable %_POST - PTM equivalent of PHP's _POST variable Additionally some other globals are hanging around for your use: $_VERSION - Current PPA version installed (PTM Language Version) $_URL - Full requested URL, not including any "?name=value" GET method additions $_PATH - The physical system path to your PTM script, not including the PTM script's file name -- slash terminated (/) $_BASE - The URL path to your PTM script, not including the PTM script's file name -- slash terminated (/) $_SCRIPT - The file name of the PTM script being called $_CGI - A Perl CGI object. Direct Access to CGI module capability @_KEYWORDS - Stores "keywords" GET method postings (?keywords=some+words+here) and also any GET method posts without matching "=value" when there is GET data, but no name=value pairs have been entered. Reminder: When installing in standard Standalone/Emulation mode there is ALWAYS at least one "?PTM_SCRIPT=script.ptm" pair, so solo entry keywords would not exist. This capability may be restored on servers that support Apache mod_rewrite environment variable creation by enabling secure script passing (see $_USE_SECURE_SCRIPT_PASSING) and removing the GET method PTM_SCRIPT variable pass in the default .htaccess file. $_HEADER - The HTTP header to be printed before the page to let the browser know what kind of information is coming and what to do with it %_SET_COOKIES - A hash containing the "Set-Cookie:" strings that are to be written as part of the HTTP header -- rarely accessed directly %_COOKIES - The cookies stored in the users' browser. This includes all cookies, both session and time-based, except those with "PTMSESSION___" names, which are used to facilitate PTM sessions, and are stored in %_SESSION %_SESSION - Similar to the %_COOKIES variable, this has stores all PTM session cookies. The cookie names are stripped of their leading "PTMSESSION" characters before being entered into the hash -- therefore, "PTMSESSIONID" becomes "ID" And there are a few more that you probably shouldn't touch =) $_SYNTAX_... - These variables define how the PTM language itself is formed and should ONLY be changed by experienced PTM developers. @_PTM - Stores the formatted Perl snippets to be evaluated and printed, and should NEVER be modified during run-time -- unless of course you are trying to crash your own site, then by all means go ahead =) $_PTM_POS - Tells the snippets going into @_PTM where and in what order they are to be printed. Just as above, this should never be modified at run-time. @_REQUIRE - Stores PTM Perl module file names from the REQUIRE tag to be loaded immediately before preprocessing. As of PTM version 0.5.0 Beta this variable serves no functional purpose, but has been kept for legacy purposes. May be used to reference which PTM modules have been loaded. There are, of course, also the following two variables which are the first variables defined and are used to tell the PPA where to look for data. $_DOCUMENT_ROOT - The path to the user's root web accessible directory. This may be either the physical system path to this location or it's relative path from the location of the PPA (ptm.cgi) $_USE_SECURE_SCRIPT_PASSING - This variable is set to 0 (zero) by default. It may be enabled (set to 1) on web servers which support Apache's mod_rewrite environment variable creation functionality via the [env|E=VAR:VAL] method. Unfortunately, many commercial web hosts do not have this capability enabled. For those that do, however, secure script passing may be enabled and used in place of the ?PTM_SCRIPT=script.ptm method in Standalone/Emulation installation mode. After enabling this feature the "?PTM_SCRIPT=$1" may be removed from the last line of the accompanying .htaccess file. To find out if your host supports secure script passing, access the /ptm_test/index.ptm script in your web browser after installing PTM in Standalone/Emulation mode and look for a variable called REDIRECT_PTM_SCRIPT in the %_SERVER variable list. If it is listed, secure script passing is possible. Due to security enhancements in PTM 0.5.0 Beta, there is no security risk in using either method. The only advantage gained in using secure script passing is enabling the @_KEYWORDS solo entry keyword method which is otherwise only available in full server integration installations. If you are familiar with PHP the first three globals above should look familiar. The only real difference in their usage is that Perl syntax must be used instead of PHP. The most noticable difference is the use of curly braces {} instead of square brackets [] when retrieving a value - e.g. $_POST{'name'} As with any language, PTM is best explained through example, so here are some samples of how to use each of the above mentioned PHP-like globals -- each example assumes you are somewhere in the middle of an PTM/HTML document and wish to insert the given value at that point: Displaying the server software information (italic): Displaying the value of a "name" form input using the GET method (bold): Listing the names and values of all POSTed form inputs (table):
:
As you can see above different tag types are used, always beginning and ending with ''. But additionally you will note the use of '" works but "" does not. This is to avoid the mixing and confusion of tag values and intended Perl code within the PPA. Another note, though all PTM tags can be closed with the standard '?>' they may also be closed using the same symbols with which they were opened, which might be used if you have a lot of content within a PTM tag and need to know specifically which type of tag closing you are looking at -- meaning "" is the same as "". And of course you can mix and match using the symbols and words, like "". DO tags - Whatever is inside of them is run as straight perl code. Use semicolons (;) where appropriate to "end your Perly thought" ;) DISPLAY tags - Behind the scenes this runs Perl's "print" statement on the contents, so make sure content is formatted accordingly -- meaning use quotes and dots to denote text and concatenation. TEMPLATE tags - Used to import another text file in place of the tag in PTM format -- meaning the contents will be evaluated as a PTM file. Because variables can be used to denote file name or parts of file names, tag contents will be read as they would be in Perl -- meaning use quotes and dots to denote text and concatenation. FILE tags - Used to import another file in place of the tag in plain text/HTML format -- meaning no PTM tags will be evaluated in the imported text NOHTML tags - Same as FILE tags (no PTM tags are evaluated) except that the standard HTML characters "&<> will be converted to their ordinal macro equivalents. For example, the ampersand symbol (&) is replaced with "&". This means that these characters will show up in your HTML document as text, and will not be formatted as HTML. Use this format to openly display yout PTM/HTML documents, or to disable HTML characters when showing a text file that may contain these characters. IMPORTANT NOTE: DO NOT use NOHTML tags to display any PTM/HTML documents that may contain sensitive information such as user names, passwords, database login info, etc., as ALL PTM and HTML are shown in their entirety. PREPROCESS tags - Used when you want to process something BEFORE the normal PTM statements are run. Most commonly used for setting up cookies, sessions, and the HTTP header, the contents of the PREPROCESS tag are not a direct inline part of the rest of your PTM script. Regardless of where you place PREPROCESS tags in your script, they will ALWAYS be run first, along with REQUIRE tags in a linear fashion, relative to other PREPROCESS and REQUIRE tags. Because PREPROCESS tags are evaluated BEFORE the HTTP header is printed, print statements should not be used here. Other than that, they work essentially the same as DO tags. REQUIRE tags - These tags are used to include Perl modules into your PTM script. Like the PREPROCESS tag, the REQUIRE tags are evaluated BEFORE any of your normal PTM script. They are one of the first things to be evaluated, regardless of where they are placed in your PTM script, along with PREPROCESS tags, in a linear fashion. Behind the scenes this tag implements the "require" statement, which is used to include Perl modules into your Perl code at run-time, whereas "use" statements are used to include them at compile time. As all PTM is processed at run-time, the "use" statement is not necessary. Quick Tag Examples: DO tags html DISPLAY tags TEMPLATE tags FILE tags NOHTML tags PREPROCESS tags REQUIRE tags Those are the basics to get you started. See the PTM online documentation for more information. That's all for now! ;)