--------------------- PTM 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 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" 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 GET method postings without matching "=value" when there is GET data, but no name=value pairs have been entered $_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 atripped 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 very 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. $_PTM_PREPROCESS - Stores the code from PREPROCESS tags and, though it COULD be modified during run time, it would most likely have no effect @_REQUIRE - Stores PTM Perl module names from the REQUIRE tag to be loaded immediately before preprocessing. There are, of course, also $_DOCUMENT_ROOT and $_DEFAULT_PTM_FILE which are the first variables defined and are used to tell the PPA where to look for data. 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 part of the rest of your PTM script. Any variables defined here will NOT be carried over into your DO, DISPLAY, etc. tags. Only modification of predefined global variables will be carried over from PREPROCESS tags to your normal script. Regardless of where you place PREPROCESS tags in your script, they will ALWAYS be run first. Because PREPROCESS tags are evaluated BEFORE the HTTP header is printed, print statements should not be used here. Other than that, they work basically 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. As a matter of fact, they are the very first thing to be evaluated, regardless of where they are placed in your PTM script. They are important because they are the only means of including a module into BOTH your PREPROCESS and regular PTM tags at the same time and are, therefore, the preferred method of requiring external non-PTM/HTML files. "require" statements are 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! ;)