| Previous | Up | Next |
| Writing a New Converter | Writing a New Converter | Writing a Converter, Methods |
As of phpDocumentor version 1.2.0rc1, all Converters share certain template variables in common. This is made possible by the common use of the Smarty template engine. Smarty makes it possible to truly separate data from its display, allowing ultimate control of the display through the templates.
What is Smarty? This is a versatile compiling template engine, and has its home page at http://smarty.php.net, please read the manual and the tutorials if you are unfamiliar with Smarty. This tutorial only describes how to use the templates, and will be confusing if you have never used Smarty before. In particular, you must understand fully how to use the {section} and {foreach} tags. Please read http://smarty.php.net/manual/en/language.function.section.php and http://smarty.php.net/manual/en/language.function.foreach.php
All template files have available to them these smarty variables:
{$date} string - the current date and time, as formatted by date("r",time)
{$maintitle} string - the contents of the phpDocumentor Tutorial command-line switch
{$package} string - the package of the current template item
{$subpackage} string - the subpackage of the current template item
{$phpdocversion} string - the version number of phpDocumentor
{$phpdocwebsite} string - the official phpDocumentor website (http://www.phpdoc.org)
Source code elements are described in Documentable PHP Elements. For most converters, documented elements are split up into two categories: class and procedural page. The template variables that contain this information are also grouped in this manner.
The source code elements (function, include, global variable, define, class, class variable, method) all have a few template variables in common. They are:
{$sdesc} string - Summary from the DocBlock
{$desc} string - Long description from the DocBlock
{$tags} array - Tags found in the DocBlock, array('keyword' => tagname, 'data' => description). access in this manner:
{section name=sec loop=$tags}{$tags[sec].keyword} = {$tags[sec].data}{/section}
or
{foreach from=$tags item=tag}{$tag.keyword} = {$tag.data}{/foreach}
{$api_tags} array - Tags found in the DocBlock useful in documenting the API, array('keyword' => tagname, 'data' => description). Access in the same manner as {$tags}
{$info_tags} array - Tags found in the DocBlock that are purely informational in nature, offering no particular use in documenting the actual software API, array('keyword' => tagname, 'data' => description). Access in the same manner as {$tags}
{$utags} array - Unknown tags found in the DocBlock, array('keyword' => tagname, 'data' => description). Access in the same manner as {$tags}
{$line_number} integer - The line number in the source code that this element appears
{$id} string - EXCEPT for include, all elements have a unique ID. This should be used to create a document anchor that will allow hyperlinking to that element's documentation.
The Converter::ConvertPage() method sets up several important variables that are used by the other conversion methods. These are:
Converter::$page_data - the Smarty template that contains all procedural page contents
Converter::$path - the full path to the procedural page
Converter::$page - the converter-safe name of the procedural page, can be used to uniquely name output
Converter::$curpage - the parserPage representation of the current procedural page
There are many template variables assigned to the procedural page template:
{$name} string - the name of the file "file.php"
{$source_location} string - the relative path of the file, needed for an include statement
{$classes} array - an array of classes defined in the file, see Converter::getClassesOnPage()
{$tutorial} string|false - a link to the tutorial associated with this page, or false if none
{$sdesc} string - summary of the procedural page from the Page-level DocBlock
{$desc} string - long description of the procedural page from the Page-level DocBlock
{$tags} array - array of all tags, array('keyword' => tagname, 'data' => description)
{$utags} array - array of all unknown tags, array('keyword' => tagname, 'data' => description). This variable is unused in the templates packaged with phpDocumentor, and should be accessed in exactly the same manner that {$tags} is accessed.
functions, includes, defines, globals array - these arrays contain all of the procedural elements defined in the file
The function and method template variables are nearly identical. The only template variable that functions use that methods do not is {$function_conflicts}, as methods cannot have conflicts. The function template variables are:
{$function_name} string - simple name of the function
{$params} array - Function parameters, array('var' => parameter name, 'datatype' => parameter type, 'data' => parameter description). The last two items are pulled from a @var tag.
{$function_return} string - data type that the function returns
{$function_conflicts} array - array('conflicttype' => 'function', 'conflicts' => array(link to docs of conflicting function 1, ...))
{$function_call} string - pre-formatted function declaration, use as is
{$ifunction_call} array - special unformatted function declaration, use to customize for special purposes. All of the templates distributed with phpDocumentor use this template variable. Writing template code for this variable is complex. It may be best to copy over code from existing templates and modify it as needed.
All functions are appended to the {$functions} template variable of the procedural page that contains them. In version 2.0, there will be greater flexibility possible with locating template variables.
Global variables templates are pretty simple. They contain the standard element template variables plus:
{$global_name} string - Name of the global variable
{$global_type} string - Data type of the global variable
{$global_value} string- Initial value of the global variable as parsed from the source, if any
{$global_conflicts} array|false - array('conflicttype' => 'global variables', 'conflicts' => array(link to docs of conflicting global variable 1, ...))
All global variables are appended to the {$globals} template variable of the procedural page that contains them. In version 2.0, there will be greater flexibility possible with locating template variables.
Define constant templates are also pretty simple. They contain the standard element template variables plus:
{$define_name} string- Name of the constant
{$define_value} string- Value of the constant as parsed from the source
{$define_conflicts} array|false - array('conflicttype' => 'defines', 'conflicts' => array(link to docs of conflicting define 1, ...))
All define constants are appended to the {$defines} template variable of the procedural page that contains them. In version 2.0, there will be greater flexibility possible with locating template variables.
Include statement templates are the simplest of all. They contain the standard element template variables plus:
{$include_name} string - the kind of include (include/require/include_once/require_once)
{$include_value} string - The file included. If the file is parsed, a link to its documentation will be passed instead of just the name of the file.
All include statements are appended to the {$includes} template variable of the procedural page that contains them. In version 2.0, there will be greater flexibility possible with locating template variables.
Like ConvertPage(), the Converter::ConvertClass() method sets up a few important variables that are used by the other conversion methods. These are:
Converter::$class_data - the Smarty template that contains all class contents for this class
Converter::$class - the name of the current class
There are many template variables assigned to the procedural page template aside from the standard element template variables:
{$class_name} string - the name of the class
{$package} string - the package of the class
{$source_location} string - the include path to the file that contains this class
{$children} array - array(array('link' => link to class that extends this class, 'sdesc' => summary of child class), ...)
{$class_tree} string - fully-formatted class tree (Converter-specific). Use unmodified.
{$conflict} array - array('conflicttype' => 'classes', 'conflicts' => array(link to docs of conflicting class 1, ...))
{$ivars} array - complex array of all inherited variables, see Converter::getFormattedInheritedVars()
{$imethods} array - complex array of all inherited variables, see Converter::getFormattedInheritedMethods()
vars, methods array - these template variables will contain each of the class variables and method template variables.
The Class variable template variables are:
{$var_name} string - simple name of the class variable
{$var_default} string - Default value of the class variable, if any
{$var_type} string - data type of the variable, from the @var tag.
{$var_overrides} array - array('link' => link to documentation for overridden class variable, 'sdesc' => summary of overridden class variable)
All class variables are appended to the {$vars} template variable of the class that contains them. In version 2.0, there will be greater flexibility possible with locating template variables.
The function and method template variables are nearly identical. See Function template variables for details. The template variables that methods use and functions do not use are:
{$constructor} boolean - true/false, true if the method is a constructor
{$descmethod} array - array(array('link'=>link to documentation for overriding method, 'sdesc'=> summary of the overriding method),...)
{$method_overrides} array - array('link'=>link to documentation for overridden method, 'sdesc'=> summary of the overridden method)
All methods are appended to the {$methods} template variable of the class that contains them. In version 2.0, there will be greater flexibility possible with locating template variables.
{$contents} string - Converted contents of the tutorial
{$title} string - Title of the tutorial
{$nav} string - true/false, Whether any navigation links to other tutorials exist
{$up} string - link to the parent tutorial of this tutorial
{$uptitle} string - title of the parent tutorial
{$prev} string - link to the previous tutorial in the tutorial hierarchy
{$prevtitle} string - title of the previous tutorial
{$next} string - link to the next tutorial in the tutorial hierarchy
{$nexttitle} string - title of the next tutorial
| Previous | Up | Next |
| Writing a New Converter | Writing a New Converter | Writing a Converter, Methods |
Documentation generated on Mon, 05 Dec 2011 21:18:47 -0600 by phpDocumentor 1.4.4