From phpCMS

Contents 1 PAX - using PHP code in content files and templates 1.1 What is PAX? How does it work? 1.1.1 Including PHP into templates 1.1.2 Available variables 1.1.3 Example PAX code-snippets 1.2 What are PAX TAGS? 1.2.1 PAXCOMBOALL: Create a list of entries from your menu file 1.2.2 PAXCOMBO: Create a filtered list of entries from your menu file 1.2.3 PAXHIGHLIGHT: Syntax-highlighted PHP code 1.2.4 PAXINC: Including additional templates or (text) files 1.2.5 PAXLASTMOD: Date of last page modification 1.2.6 PAXMENU: Calling on menu classes and fields 1.2.7 PAXRTF: Include simple RTF files and display them as HTML

[edit] PAX - using PHP code in content files and templates

[edit] What is PAX? How does it work?

PAX offers a way to have PHP code in either your content file or template that differs from the use of the {SCRIPT} method.

With PAX turned on in the admin panel, templates and content files alike will be preprocessed by the PAX module before being parsed by phpCMS. PAX strips PHP code from these files, processes it and stores its results for later inclusion into the page after it has been parsed by phpCMS. This ensures smooth operation of phpCMS and allows for further development of the PAX module without the need for major modifications to phpCMS' core routines.

PAX works similar to the {SCRIPT} inclusion method that comes with phpCMS.

{SCRIPT} allows you to include scripts into content files but not templates. PHP scripts included via {SCRIPT} are dynamically inserted into a page at runtime. While the static part of a page may be cached on the server (if caching is turned on in the admin panel), scripts are inserted into the page each time the page is requested. PAX works similar to {SCRIPT} inclusion as far as caching is concerned, but may be used to insert scripts into templates as well.

PAX is needed to include PHP into templates.

[edit] Including PHP into templates

It is important to note that debugging is not available when including scripts via PAX! Inclusion of PHP in templates is achieved quite easily and at your own risk:

Example:

<!-- PAXPHP name_of_code_block
 echo 'Hello World!';
PAXPHP name_of_code_block -->

Within PAX, PHP code needs to be written in a single block. This block of code is stripped by PAX before the template is parsed by phpCMS. It is then reinserted into the page before the page is served.

The "name_of_code_block" must NOT be used more than once, regardless of which template it is used in!

The "name_of_code_block" may contain lower/upper case letters, underscores_ , and numbers ( A-Z , a-z , _ , 0-9 ). NO SPACE or SPECIAL CHARACTERS are allowed!

The block of code consists of a start tag and an end tag

<!-- PAXPHP name_of_code_block 
$yourcode = here;
PAXPHP name_of_code_block -->

It is important that there is a space between the PAXPHP-Tag and the name_of_code_block.

NO PHP START TAGS ( <? , <?php ) or END TAGS ( ?> ) must be used!

[edit] Available variables

Within PHP code included via PAXPHP you have access to all global variables that were defined prior to the page being parsed by phpCMS/PAX. Available are all superglobals ($_GET, $_POST, $_SERVER, ...), thus you can access all form results that were send either with method="post" or "get" (just don't rely on those values being auto-registered - get them from the respective superglobal array). Additional variables that are defined are:

$PHP_SELF 

File currently displayed, relative to the document root (identical to $_SERVER["PHP_SELF"])

$CHECK_PAGE 

See How to write plugins#Available Variables for further details about this

$PHP 

See How to write plugins#phpCMS-supplied function for further details about this

$PAGE->tags 

Tag-List used on this page. As a PAXPHP block is evaluated AFTER the page has been completely parsed, the Tag-List can be considered read-only - adding new tags won't help, though it's not forbidden.

There might be more variable registered (you can check the $GLOBALS array, but be aware of cyclic references in there).

One important note: When caching is activated, some of the abovementioned variables will be undefined or empty. This is especially true for $PAGE (the parser does not need to re-compose the page, just run the PAXPHP script, so there's no need to load the tags). $CHECK_PAGE and $PHP should be available though, and the superglobals from PHP will be filled in any case.

[edit] Example PAX code-snippets

Let's start with a very simple, yet very useful tool: A variable content inspector. Of course, such a block should never been put onto a final website, but during development it can be valuable to have such a thing. Let's say you want to know the content of the $_POST array, as your page is the recipient of a 'post'ed form:

<!-- PAXPHP variable_test
 echo("<pre>Content of the _POST array:\n");
 var_export($_POST);
 echo("</pre>);
PAXPHP variable_test -->

It's really as easy as that. The output of course depends on the page and the form that sends its data. Be careful though - this method does not really work for $GLOBALS, as there are cyclic references within $GLOBALS (e.g. $GLOBALS["GLOBALS"] exists and is a backlink to itself, thus $GLOBALS["GLOBALS"]["GLOBALS"] exists, and so on).

Next in line: A language changer. Let's assume your website is available in two languages, your website in the document root, the two languages (german and english) are in /de and /en, the structure and naming of files and directories in the two directories is identical and every file is available in both languages. (The assumptions are mainly for simplicity of the example.)

<!-- PAXPHP language_changer
 $language = substr($PHP_SELF,1,2);
 $file = substr($PHP_SELF,4);

 if ($language == "de")
  echo('<img src="/images/de_flag_on.png" alt="German" />');
 else
  echo('<a href="/de/'.$file.'><img src="/images/de_flag_off.png" alt="German" /></a>');

 if ($language == "en")
  echo('<img src="/images/en_flag_on.png" alt="German" />');
 else
  echo('<a href="/de/'.$file.'><img src="/images/en_flag_off.png" alt="English" /></a>');
  
PAXPHP language_changer -->

Doesn't look too complicated, now - does it? Okay, this would be better suited for a static plugin (an english site doesn't become a german one on a request just because it wants to, so this doesn't need to be a dynamic PAXPHP script at all), but it's working. Of course, if you want to use this, you'll need the 4 flag-images, but that's up to you.

[edit] What are PAX TAGS?

PAXTAGS are available within templates and/or content files.

PAXTAGS are always static. This means when changing a content file that has a PAXTAG in it, this will automatically reflect in the served page. After changing a template file with a PAXTAG in it, however, if server caching is turned on, you need to flush the server cache in order for the change to appear in the served page.

To be able to use PAXTAGS, both them and PAX must be enabled in the admin interface.

[edit] PAXCOMBOALL: Create a list of entries from your menu file

PAXCOMBOALL creates a drop-down-list / combo-box, filled with data taken from your menu file (.mnu).

SYNTAX:

<!-- PAXCOMBOALL name_field,size,multi,needs_form,first_option --> 

PARAMETERS:

name_field 

name of the field within the menu file that holds the texts you want (required)

size 

size of the listbox (optional)

multi 

Shall the list be multi-select? (optional)

needs_form 

Wrap the list-box with a form. (optional)

first_option 

Additional, pre-pended text for the list box (optional)

The only required filed is the first one which tells the system where to find the texts that should be listed. Choose one of the field names within your menu file. The other fields are optional. If you leave out an optional field, just skip the value, but set the comma.

size is the size in lines the listbox should have. Skipping it or setting it to 0 or 1 will all result in the list being a drop-down box, every other (positive) number will give you a list-box of said number of lines (and a scroll-bar, if there's more entries than lines).

multi is a very limited value - either state "on" or skip it. If you set it, it turns the listbox into a multi-select listbox. This of course only makes sense for real listboxes, not for drop-down lists.

needs_form is another "on" or skip - parameter. If set, the listbox will become a navigation tool that automatically switches over to the page that corresponds to the selected entry. Otherwise, the listbox itself will do nothing, but you can put your own form around it. The resulting value will always be the content of the LINK field entry of the line corresponding to the selected entry, and the name of the parameter will be PAXCOMBONESTED0, PAXCOMBONESTED1, ..., with the appended number corresponding to the order of the PAXCOMBOALL tags used within the file.

first_option represents a special first line for the listbox. This is mainly useful in listboxes of size 1, as it can explain the meaning of this drop-down list.

EXAMPLES:

<!-- PAXCOMBOALL MNAME,,,on,-- Select a Destination -- -->

This will create a fully function navigation tool that holds all the possible sites, subsites and so on (all that are in the menu file) and has "-- Select a Destination --" as initial, pre-selected value. Note that the second argument (size) has been skipped / left out, therefore making this a drop-down list. The labels in the list are identical to the link names used in the menu

<!-- PAXCOMBOALL MNAME,,,, -->

This is the shortest possible usage: Just give the name of the field the listbox should take it's labels from and be done with it. This again is a drop-down box, but this time there's no form, nor an automatic submission once you choose a value - therefore, you'd need to wrap this baby in your own form-code.

<!-- PAXCOMBOALL CLASS,5,on,, -->

This will create a 5 lines high multiple-select listbox that lists the possible menu classes. Of course, a multiple-select box makes no sense in combination withan auto-submit functionality, so the form is again off.

[edit] PAXCOMBO: Create a filtered list of entries from your menu file

PAXCOMBO is much like PAXCOMBOALL, as it takes your menu definition and displays it in a list, either drop-down or classic. Unlike PAXCOMBOALL, you can define which menu to use among other possibilities:

SYNTAX:

<!-- PAXCOMBO menu,name_field,value_field,selected,size,multi,needs_form,first_option --> 

PARAMETERS:

menu 

Name of the menu template within the .mnu menu file (required)

name_field 

Name of the field acting as source for the list entry texts (required)

value_field 

Name of the field acting as source for the list entry values (required)

selected 

Line number to be pre-selected (optional)

size 

size of the listbox (optional)

multi 

Shall the list be multi-select? (optional)

needs_form 

Wrap the list-box with a form. (optional)

first_option 

Additional, pre-pended text for the list box (optional)

For the recurring parameters, please read the explanation of PAXCOMBOALL right above. Additional notes:

menu should be the name of a menu block (e.g. MAIN, SUB1, ...) within your menu file.

value_field is the name of the field within the menu file that holds whatever value you want the list entries to have. Make sure to use either LINK or another field with URLs here if you plan of using the needs_form parameter, as the values of the list entries are used as target page when selecting an entry.

selected lets you pre-select an entry. It denotes the line number of the entry to be selected, starting from 1

The listbox will again get an autogenerated name, this time named PAXCOMBO_<menu>0 and counting up, with menu being the value of the abovementioned first parameter.

EXAMPLES

<!-- PAXCOMBO MAIN,MNAME,CLASS,,,,, -->

Shortest possible usage, this will create a drop-down list with the main category link texts as labels and the corresponding class numbers as values. No form around it, so you'd have to wrap it into one on your own.

<!-- PAXCOMBO MAIN,MNAME,LINK,,,,on,-- Select Destination -- -->

Like above, but this time with the links as values and a form wrapped around - this will create a drop-down navigation list that only holds the first menu level. Per default the drop-down list shows "-- Select Destination --"

<!-- PAXCOMBO SUB1,MNAME,CLASS,3,5,on,, -->

Now, this is a 5 rows hight list-box that is multiple-select, has row 3 pre-selected and contains all level-2 menu entries (first sub-menu) and the corresponding class numbers.

[edit] PAXHIGHLIGHT: Syntax-highlighted PHP code

With PAXHIGHLIGHT you may include syntax-highlighted PHP code files (local or external) into your template or content files.

SYNTAX:

<!-- PAXHIGHLIGHT filename --> 

PARAMETERS:

filename 

local file or http-url to be included

Note that you cannot access the source code of remote PHP files with this as long as the PHP parser pre-processes those files on the server. This is not a backdoor to a foreign page's source code but a way to show your own plugin's code to visitors.

Be careful though: External sources from other webservers might not work if the http-wrappers of PHP are switched off. As this is a usual setting (think security measures), it's better to rely on local files for this.

EXAMPLES:

<!-- PAXHIGHLIGHT /path/from_root/to/my/file.php --> 

or

<!-- PAXHIGHLIGHT http://www.example.net/data.phps --> 

[edit] PAXINC: Including additional templates or (text) files

With PAXINC you may include additional templates or external files (not! scripts) into your template or content files.

SYNTAX:

<!-- PAXINC filename --> 

PARAMETERS:

filename 

local file or http-url to be included

Note that within those templates/files included via PAXINC, links are NOT being checked, but PAX-tags within those included files will be evaluated, with the exception of PAXINC itdelf.

Be careful though: External sources from other webservers might not work if the http-wrappers of PHP are switched off. As this is a usual setting (think security measures), it's better to rely on local files for this.

EXAMPLES:

<!-- PAXINC /path/from_root/to/template/or/file.html --> 

or

<!-- PAXINC http://www.example.net/data.html --> 

It is also possible to use $home or $plugindir

[edit] PAXLASTMOD: Date of last page modification

PAXLASTMOD lets you put an automated 'last modified' field onto your page.

SYNTAX:

<!-- PAXLASTMOD date-format --> 

PARAMETERS:

date-format 

string telling the date()-function of PHP how to format the date

Usually, the following options of 'date()' (which are a subset of the available parameters) should suffice (table taken from PHP documentation):

format character	Description	Example returned values
a	Lowercase Ante meridiem and Post meridiem	am / pm
A	Uppercase Ante meridiem and Post meridiem	AM / PM
d	Day of the month, 2 digits with leading zeros	01 to 31
D	A textual representation of a day, three letters	Mon through Sun
F	A full textual representation of a month, such as January or March	January through December
g	12-hour format of an hour without leading zeros	1 through 12
G	24-hour format of an hour without leading zeros	0 through 23
h	12-hour format of an hour with leading zeros	01 through 12
H	24-hour format of an hour with leading zeros	00 through 23
i	Minutes with leading zeros	00 to 59
j	Day of the month without leading zeros	1 to 31
l (lowercase 'L')	A full textual representation of the day of the week	Sunday through Saturday
m	Numeric representation of a month, with leading zeros	01 through 12
M	A short textual representation of a month, three letters	Jan through Dec
n	Numeric representation of a month, without leading zeros	1 through 12
r	RFC 2822 formatted date	Thu, 21 Dec 2000 16:01:07 +0200
s	Seconds, with leading zeros	00 through 59
S	English ordinal suffix for the day of the month, 2 characters	st,nd,rd or th. Works well with 'j'
T	Timezone setting of this machine	EST, MDT, ...
Y	A full numeric representation of a year, 4 digits	1999, 2003
y	A two digit representation of a year	99, 03

Note that textual representations will be given in the language the webserver is configured to use, so it might be wise to refrain from using them.

EXAMPLES:

A usually good default would be:

Page last modified: <!-- PAXLASTMOD Y-m-d H:i:s -->

which will result in something like

Page last modified: 2005-04-12 14:27:58

Now, if you want to have text besides the date (like formatting the date according to english standards), you need to "escape" every letter that should NOT be interpreted by the date-function with a backslash (\) like in this example:

Page last modified: <!-- PAXLASTMOD l, \t\h\e jS \o\f F Y, g:i a -->

which will - provided that the webserver is set up properly - result in

Page last modified: Tuesday, the 12th of April 2005, 2:32 pm

[edit] PAXMENU: Calling on menu classes and fields

PAXMENU gives you the ability to call on any menu class or field.

SYNTAX:

<!-- PAXMENU fieldname,class --> 

PARAMETERS:

fieldname 

Name of the field within your menu file (.mnu) that hold the required data

class 

Value of the CLASS field in the line you're after

EXAMPLES: Suppose you wanted to create a link to a specific item of your menus within a template or file. This is how you would do it:

 <a href="<!-- PAXMENU LINK,00.08.06.12 -->"><!-- PAXMENU  MNAME,00.08.06.12 --></a>

This would create a link to the menu item with class 00.08.06.12. The link text would be what you have defined for MNAME for that menu.

Example with "title", target frame/window, and status message on mouseover:

<a href="<!-- PAXMENU LINK,00.08.06.12 -->" 
   target="<!-- PAXMENU TARGET,00.08.06.12 -->" 
   onmouseover="window.status = '<!-- PAXMENU TEXT,00.08.06.12 -->';return true;" 
   title="<!-- PAXMENU TEXT,00.08.06.12 -->">
 <!-- PAXMENU MNAME,00.08.06.12 -->
</a>

In the above example the menu fields (field names in the .mnu-file) are as follows:

LINK and CLASS 

these fields and their exact spelling are required by phpCMS, and may not be changed!

TARGET 

the "target=" frame/window for LINK

TEXT 

message to be display in the status bar on mouseover.

MNAME 

the actual text that is turned into a link.

Summing up, you may call on any menu field that has been defined in your .mnu file.

[edit] PAXRTF: Include simple RTF files and display them as HTML

With PAXRTF you may include (simple) RTF files (local or external) into your template or content files. They will be converted to HTML as good as possible.

SYNTAX:

<!-- PAXRTF filename --> 

PARAMETERS:

filename 

local file or http-url to be included

Note that you cannot access the source code of remote PHP files with this as long as the PHP parser pre-processes those files on the server. This is not a backdoor to a foreign page's source code but a way to show your own plugin's code to visitors.

Be careful though: External sources from other webservers might not work if the http-wrappers of PHP are switched off. As this is a usual setting (think security measures), it's better to rely on local files for this.

EXAMPLES:

<!-- PAXRTF /path/from_root/to/my/document.rtf --> 

or

<!-- PAXRTF http://www.example.net/doc.rtf -->