Portal has a variety of template variable arrays that contain the data used by the HTML template pages for display. When making custom Portal sites it becomes a common need to investigate the data found in these arrays via a PHP print_r statement like the following.

<?php
print "<pre>";
#print_r($_SERVER);
#print_r($_SESSION);
#print_r($volume_info);
#print_r($dir_info);
#print_r($file_info);
#print_r($files_info);
#print_r($keywords_info);
#print_r($tmpl->variables['PORTALPAGE']);
#print_r($links_info);
#print_r($spreads_info);
print "</pre>";
?>

Through using this approach it becomes possible to display Portal’s template variables arrays directly in a web browser, which can be convenient for inspection and debugging. This article expands on alternatives and twists to this standard approach.

When exploring a variable's contents in PHP var_dump() and var_export() are common alternatives to the print_r() function. Each performs a similar task with a slightly different behavior. var_dump() prints slightly more informative (but less readable) information about the given variable’s data, while var_export() prints interpretable PHP code. The following table illustrates the output differences for these functions.

Array
(
[0] => Apples
[1] => Oranges
[2] => Pears
)
      

array(3) {
    [0]=>
    string(6) "Apples"
    [1]=>
    string(7) "Oranges"
    [2]=>
    string(5) "Pears"
}
      

array (
    0 => 'Apples',
    1 => 'Oranges',
    2 => 'Pears',
)
     

Depending on your needs, these standard functions give a good set of options for displaying Portal template variable data for inspection and debugging.

Sometimes it is not always ideal to send Portal’s template variable data to the web browser for inspection and debugging. To help alleviate this issue the print_r() and var_export() functions both accept a second Boolean parameter that, when set as true, causes both of these functions to return a variable’s data from the function call instead of printing it. This allows for capturing a variable’s data in another variable and/or file for later inspection and debugging. The following snippet is an example of such an approach.

<?php
$portal_page = print_r($tmpl->variables['PORTALPAGE'], true);
file_put_contents('/some/directory/var_data.log', $portal_page);
?>

The print_r() function is called with a second parameter set to true. This cause the print_r() function to return the $tmpl->variables['PORTALPAGE’] variable information to the $portal_page variable instead of printing it. The contents of the $portal_page variable are then written to an external log file. This data could then be viewed, searched, and stored at another point in time.

Using PHP it is also possible to store the portal variable information in your own XML format. This XML data could then be transmitted and interpreted by any type of program geared to help inspection and debugging of Portal’s template variable arrays. The following code example could be placed inside of any one of your site’s local.inc.php files. This code snippet checks known Portal template variables arrays, and inserts their data into a hierarchical XML data structure. This file is then saved as XML on the server in the same directory as the file being executed.

<?php

$var_trees = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>";

//start the xml var trees hierarchical data structure
$var_trees .= "<var_trees>";

//check the known portal variables. If they exist generate an xml tree of the data
if ($volume_info != NULL) $var_trees .= var_tree('$volume_info', $volume_info);
if ($file_info != NULL) $var_trees .= var_tree('$file_info', $file_info);
if ($files_info != NULL) $var_trees .= var_tree('$files_info', $files_info);
if ($keywords_info != NULL) $var_trees .= var_tree('$keywords_info', $keywords_info);
if ($tmpl->variables['PORTALPAGE'] != NULL) $var_trees .=
var_tree('$tmpl->variables[\'PORTALPAGE\']', $tmpl->variables['PORTALPAGE']);
if ($links_info != NULL) $var_trees .= var_tree('$links_info', $links_info);
if ($spreads_info != NULL) $var_trees .= var_tree('$spreads_info', $spreads_info);
if ($_SERVER != NULL) $var_trees .= var_tree('$_SERVER', $_SERVER);
if ($_SESSION != NULL) $var_trees .= var_tree('$_SESSION', $_SESSION);

//close the xml var_tree hierarchical data structure
$var_trees .= "</var_trees>";

//store the xml data in an external xml file
file_put_contents(dirname(__FILE__).'/var_trees.xml', $var_trees);

//recursive function to generate nested xml data structure for a given variables data
function var_tree($key, $value){
   $var_tree = "";
   if(is_array($value)){
      $var_tree .= "<var_tree label=\"".htmlentities($key)."\" >";
      foreach($value as $key => $val){
         $var_tree .= var_tree($key, $val);
      }
      $var_tree .= "</var_tree>";
    }else{
       $var_tree .=  "<var_node label=\"".htmlentities($key)."\" value=\"".htmlentities($value)."\" />";
    }
    return $var_tree;
}

Taking this one step further, you can then utilize this developed XML format to create more advanced debugging tools. One quick example for this is a small Flex application that I quickly developed to interpret the previous example’s generated XML data. This debugger interface is automatically opened in a separate window when any portal template page embeds the {varviewer} template tag, which can be generated in your site’s local.inc.php file using a code snippet similar to the following.

$tmpl->variables['PORTALPAGE']['varviewer'] = 
"<SCRIPT TYPE='text/javascript'>winRef ="+
"window.open( '/VarViewer/templates/varviewer/PortalVariableViewer.html', 'varviewer',"+
"'height=450, width=750'); </SCRIPT>";

View the demo of this application HERE (user: blogdemo/pass: blogdemo). This XML variable debugger application has also been packaged as a House portal site named VarViewer that you can use and experiment with on your own portal server. You can download it HERE. This is a simple example, but illustrates the possibility of developing a more advanced and searchable Portal template variable arrays debugger.

There are a variety of ways to inspect and debug the Portal template variables. Using PHP’s built in variable display functions, and even custom data XML formats allows for a greater degree of flexibility when working with them. In the end these variables are an important to understand when trying to modify and extend Portal’s appearance and functionality, and using these techniques may help you during this learning process.

Customizing a Portal Site is a straightforward process and can offer you the ability to change the default look & feel of a site, or even increase the default functionality of a site.

How it all works

All sites follow a similar file structure.  Looking at the example above, we see that the default Exhibit site contains a few PHP files and a templates folder.

Config.inc.php – Contains all site configurations.
Index.php – Responsible for initializing (bootstrapping) the Portal architecture.
Startup.php – Responsible for initializing (bootstrapping) the Portal architecture.

Inside the templates folder, we see a bunch of html/css/js files and a single php file local.inc.php.  These are the files a web developer will modify to change the look & feel of a site and/or add their own functionality.

The first step in learning to develop for the Portal platform is understanding how Portal works and how a Portal site works.  The diagram below demonstrates how Portal creates the screens you see when browsing a Portal Site.

Inside a template file

The templates folder contains several *.tmpl.html files.  These are the front-end of the Portal Site and it’s where you can make layout and design changes.  You may structure these files the same way you structure your HTML documents normally.

A typical layout file contains mostly standard HTML, however they also contain tags and tag domains.

From the Xinet Portal manual:

A tag domain contains several tags.  Depending on the template (i.e. ImageInfo, Browse, etc), and the tag domain being used, certain tags will be available. 

During the bootstrapping process the default values for each tag are set, however a PHP programmer has the ability to change these values using the local.inc.php file.

Customizing a Tag

Before making any PHP customizations, one should always investigate whether a change can be made to the config.inc.php file first to give the desired result.

Xinet’s templating system works with a few arrays of data in which tags are derived.  These arrays store a variety of information about files, directories, volumes, keywords, etc.  Referencing the diagram above, it becomes clear that the values in these arrays can be accessed and manipulated using the local.inc.php file.

For example, if I wanted to append to all files Comment attribute I would write a block of code like this in the local.inc.php file:

The above block of code would append “ – Copyright of my company” to the end of each files comment attribute.

Please reference the Xinet manual for a complete listing of PHP arrays.

Conclusion

Customizing a Portal Site is fairly simple and provides you with the ability to brand the interface and expand the functionality as you see fit, while still maintaining a powerful & secure asset management interface.