[pLog-svn] r1663 - in plog/trunk/class: . template template/menu
template/smarty template/templatesets
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Thu Mar 31 07:38:12 GMT 2005
Author: oscar
Date: 2005-03-31 07:38:12 +0000 (Thu, 31 Mar 2005)
New Revision: 1663
Modified:
plog/trunk/class/Doxyfile
plog/trunk/class/template/cachecontrol.class.php
plog/trunk/class/template/cachedtemplate.class.php
plog/trunk/class/template/menu/menu.class.php
plog/trunk/class/template/menu/menuentry.class.php
plog/trunk/class/template/menu/menurenderer.class.php
plog/trunk/class/template/smarty/Smarty.class.php
plog/trunk/class/template/smarty/Smarty_Compiler.class.php
plog/trunk/class/template/template.class.php
plog/trunk/class/template/templatesandbox.class.php
plog/trunk/class/template/templateservice.class.php
plog/trunk/class/template/templatesets/templatefinder.class.php
plog/trunk/class/template/templatesets/templateset.class.php
plog/trunk/class/template/templatesets/templatesets.class.php
plog/trunk/class/template/templatesets/templatesetstorage.class.php
plog/trunk/class/template/templateutils.class.php
Log:
documented the template/ folder, only action/ to go!!
Modified: plog/trunk/class/Doxyfile
===================================================================
--- plog/trunk/class/Doxyfile 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/Doxyfile 2005-03-31 07:38:12 UTC (rev 1663)
@@ -416,7 +416,7 @@
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/ data/ view/ plugin/
+INPUT = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/ data/ view/ plugin/ template/
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
Modified: plog/trunk/class/template/cachecontrol.class.php
===================================================================
--- plog/trunk/class/template/cachecontrol.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/cachecontrol.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -7,7 +7,9 @@
/**
* \ingroup Template
*
- * Allows to control Smarty's caches in an easier way
+ * Allows to control Smarty's caches in an easier way. You can call any of these methods
+ * whenever you need to clear the contents of the whole site, the summary or just a single
+ * blog.
*/
class CacheControl extends Object
{
Modified: plog/trunk/class/template/cachedtemplate.class.php
===================================================================
--- plog/trunk/class/template/cachedtemplate.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/cachedtemplate.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -1,24 +1,28 @@
<?php
- /**
- * @package template
- */
-
-
include_once( PLOG_CLASS_PATH."class/template/template.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
/**
- * Implements templates with support for caching
+ * \ingroup Template
*
+ * Extends the Template class to provide support for cached templated. This class adds
+ * two additional methods that are not available in Template:
+ *
+ * - CachedTemplate::isCached() to know whether the current CachedTemplate is working on cached contents
+ * - CachedTemplate::clearCache() to clear the current cached contents of this template
+ * - CachedTemplate::getCreationTimestamp() to determine when the current cached version was created
+ *
+ * @see TemplateService
* @see Template
*/
class CachedTemplate extends Template
{
/**
- * @param templateFile
- * @param cacheLifetime
+ * Constructor.
+ *
+ * @param cacheLifeTime How many seconds we would like to cache the template
*/
function CachedTemplate( $templateFile, $cacheLifetime = 300 )
{
Modified: plog/trunk/class/template/menu/menu.class.php
===================================================================
--- plog/trunk/class/template/menu/menu.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/menu/menu.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -7,7 +7,20 @@
define( "DEFAULT_MENU_FILE", "/admin/menus.xml" );
/**
- * Implements support for dealing with xml tree-based menus
+ * \ingroup Template
+ *
+ * Implements support for dealing with xml tree-based menus.
+ *
+ * There is more information about the menu API and how to use it here:
+ * http://wiki.plogworld.net/index.php/PLog_1.0/The_Menu_API
+ *
+ * If you need to get the global instance of the menu, use the Menu::getMenu() singleton method.
+ *
+ * New entries can be dynamically added to the menu via the Menu::addEntry() method, and the whole
+ * menu can be rendered by using the MenuRenderer class.
+ *
+ * @see MenuEntry
+ * @see MenuRenderer
*/
class Menu extends XML_Tree
{
Modified: plog/trunk/class/template/menu/menuentry.class.php
===================================================================
--- plog/trunk/class/template/menu/menuentry.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/menu/menuentry.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -3,8 +3,10 @@
include_once( PLOG_CLASS_PATH."class/xml/tree/Node.php" );
/**
+ * \ingroup Template
+ *
* Wraps around an XML_Tree_Node object to represent a node from the
- * menu/tree
+ * menu tree
*/
class MenuEntry extends XML_Tree_Node
{
@@ -12,8 +14,9 @@
/**
* constructor
*
- * @param entryId
- * @param entryAttrs
+ * @param entryId The name of the node/menu entry
+ * @param entryAttrs an array containing the attributes of the menu entry (locale id,
+ * use bread&crumbs, etc)
*/
function MenuEntry( $entryId, $entryAttrs = Array())
{
Modified: plog/trunk/class/template/menu/menurenderer.class.php
===================================================================
--- plog/trunk/class/template/menu/menurenderer.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/menu/menurenderer.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -8,8 +8,16 @@
include_once( PLOG_CLASS_PATH."class/locale/locales.class.php" );
/**
- * dumps the contents of the menu in a tree-fashion way
- * using unordered html lists
+ * \ingroup Template
+ *
+ * dumps the contents of the menu in a tree-fashion way using unordered html lists. It is necessary
+ * to use some additional CSS styling to give some formatting to the menu.
+ *
+ * This class is only used at the presentation layer of pLog to generate the menu structure,
+ * and class users should never need to create an instance of this class.
+ *
+ * See the "Menu API reference" document in the wiki for more information:
+ * http://wiki.plogworld.net/index.php/PLog_1.0/The_Menu_API
*/
class MenuRenderer extends Object
{
@@ -17,6 +25,16 @@
var $_blogInfo;
var $_userInfo;
+ /**
+ * Initializes the renderer
+ *
+ * @param menu A vaid Menu object
+ * @param blogInfo A reference to a BlogInfo object containing information of the blog for whom
+ * we are going to render this menu tree.
+ * @param userInfo A reference to a UserInfo object containing information of the user for whom
+ * we are going to render this menu tree, because we need to know which options he/she is allowed
+ * to see and which not.
+ */
function MenuRenderer( $menu, $blogInfo, $userInfo )
{
$this->Object();
@@ -38,6 +56,8 @@
/**
* renders the contents of the menu
+ *
+ * @param depth How many depth levels we should generate.
*/
function generate( $depth = 99 )
{
@@ -46,6 +66,9 @@
}
/**
+ * Generates a tree starting from another node which can be different than the
+ * root node
+ *
* @param nodeId
* @param depth
* @param activeOpt
@@ -129,7 +152,7 @@
/**
* simple version of a "breadcrumbs" feature
*
- * @param node
+ * @param entryId
*/
function breadCrumbs( $entryId )
{
Modified: plog/trunk/class/template/smarty/Smarty.class.php
===================================================================
--- plog/trunk/class/template/smarty/Smarty.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/smarty/Smarty.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -61,7 +61,7 @@
define('SMARTY_PHP_ALLOW', 3);
/**
- * @package Smarty
+ * \ingroup Template
*/
class Smarty
{
Modified: plog/trunk/class/template/smarty/Smarty_Compiler.class.php
===================================================================
--- plog/trunk/class/template/smarty/Smarty_Compiler.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/smarty/Smarty_Compiler.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -30,7 +30,7 @@
/**
* Template compiling class
- * @package Smarty
+ * \ingroup Template
*/
class Smarty_Compiler extends Smarty {
Modified: plog/trunk/class/template/template.class.php
===================================================================
--- plog/trunk/class/template/template.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/template.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -1,22 +1,41 @@
<?php
- /**
- * @package template
- */
+ /**
+ * \defgroup Template
+ *
+ * The Template module provides classes for dealing with templates, which are built on
+ * top of Smarty.
+ *
+ * It also provides method for managing the cache, template validation sandboxes and for
+ * dealing with template sets.
+ *
+ * @see TemplateService
+ * @see Template
+ * @see TemplateSets
+ * @see Menu
+ * @see MenuRenderer
+ */
-
include_once( PLOG_CLASS_PATH.'class/template/smarty/Smarty.class.php' );
include_once( PLOG_CLASS_PATH.'class/config/config.class.php' );
include_once( PLOG_CLASS_PATH.'class/logger/loggermanager.class.php' );
/**
+ * \ingroup Template
+ *
* Wrapper around the Smarty class, inspired by the article
* http://zend.com/zend/tut/tutorial-stump.php
*
- * Provides additional security settings that by default are not enabled in the
- * original Smarty class.
+ * This class provides additional methods and initial values for the original Smarty
+ * class, and reimplements the methods Smarty::fetch() and Smarty::display() so that they do
+ * not need an extra parameter.
*
- * It is recommended to use the TemplateService class to create the Template objects.
+ * It is not recommended to create instances of this class directly but instead, use the factory
+ * TemplateService which is able to generate different types of Template objects with some pre-set
+ * values. The TemplateService class can also deal with cached and non-cached templates.
+ *
+ * @see TemplateService
+ * @see CachedTemplate
*/
class Template extends Smarty
{
@@ -27,13 +46,9 @@
var $log;
/**
- * Constructor. By default, activates the security mode of Smarty,
- * disabling for example any kind of PHP code embedded in the Smarty templates.
+ * Constructor.
*
* @param templateFile Complete path to the template file we are going to render
- * @param cache By default set to true and specifies wether we should cache the
- * contents or not.
- * @param cacheLifeTime How many seconds we would like to cache the objects
*/
function Template( $templateFile )
{
Modified: plog/trunk/class/template/templatesandbox.class.php
===================================================================
--- plog/trunk/class/template/templatesandbox.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templatesandbox.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package template
- */
-
-
include_once( PLOG_CLASS_PATH.'class/object/object.class.php' );
include_once( PLOG_CLASS_PATH.'class/config/config.class.php' );
include_once( PLOG_CLASS_PATH.'class/data/validator/templatevalidator.class.php' );
@@ -15,6 +10,8 @@
define( 'TEMPLATE_SANDBOX_ERROR_CREATING_WORKING_FOLDER', -102 );
/**
+ * \ingroup Template
+ *
* This class checks that a file that is going to be added to a template, or
* a packed file with a template set has the right contents.
*
@@ -22,6 +19,8 @@
* trying to upload an executable file (.php, etc) as part of the template. Sandboxed
* means that everything happens in a random temporary folder and that in case of
* error, everything is removed from disk.
+ *
+ * @see TemplateValidator
*/
class TemplateSandbox extends Object
{
@@ -120,6 +119,10 @@
/**
* Once we have a folder with some template files, we make sure that what's
* inside is fine (no forbidden files, etc)
+ *
+ * @param templateName
+ * @param templateFolder
+ * @return
*/
function checkTemplateFolder( $templateName, $templateFolder )
{
Modified: plog/trunk/class/template/templateservice.class.php
===================================================================
--- plog/trunk/class/template/templateservice.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templateservice.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -18,7 +18,9 @@
define( 'DEFAULT_TEMPLATE_TEMP_FOLDER_PERMISSIONS', 0775 );
/**
- * Generic template rendering service that takes care of providing the Template objects
+ * \ingroup Template
+ *
+ * Factory class that takes care of providing Template or CachedTemplate objects
* whenever requested.
*
* The advantage of using this TemplateService class is that we can delegate on it things
@@ -32,6 +34,17 @@
* <li>User agent of the client</li> (<b>NOTE: </b>will not be implemented yet)
* <li>The default template specified in the server-wide configuration file</li>
* </ul>
+ *
+ * TemplateService is the preferred way to generate instances of the Template class:
+ *
+ * <pre>
+ * $ts = new TemplateService();
+ * // it's enough with "main", there is no need to specify "main.template" as the template name
+ * $template = $ts->Template( "main", $blogInfo->getBlogTemplate(), $blogInfo );
+ * $template->assign( "string", "This is a sample string" );
+ * ...
+ * print($template->display());
+ * </pre>
*/
class TemplateService extends Object
{
@@ -48,11 +61,13 @@
* Generates a Template object for the given template name. This fuction does <b>not</b>
* require the full path to the file!!
*
- * @param templateName The name of the template we would like to get
- * @param layout A predefined layout style
+ * @param templateName The name of the template, it is not necessary to provide
+ * the .template extension.
+ * @param layout A predefined layout style, which corresponds with the name of a
+ * folder under the templates/ folder so 'blueish' would mean templates/blueish/
* @param blogInfo If this parameter is not null, then it will be used to locate
* a blog-specific template. Otherwise, we will only look for the template
- * in the "global" folders.
+ * in the "global" folders. This parameter defaults to 'null'.
* @return A Template object representing the template file we asked for.
*/
function Template( $templateName, $layout, $blogInfo = null )
@@ -78,9 +93,14 @@
}
/**
- * @param templateName
- * @param layout
- * @param cached
+ * Returns a Template or CachedTemplate object pointing to a custom template.
+ *
+ * @param templateName The name of the template, it is not necessary to provide
+ * the .template extension.
+ * @param layout A predefined layout style, which corresponds with the name of a
+ * folder under the templates/ folder so 'blueish' would mean templates/blueish/
+ * @param cached Whether the custom template should be cached or not (this will affect
+ * the kind of the returned object)
* @return a Template or CachedTemplate object, depending on whether
* $cached is 'true' or 'false'
*/
@@ -111,11 +131,13 @@
/**
* returns a template from the admin folder. It still uses TemplateService::Template but
- * exports additional information to the template
+ * exports additional information to the template such as the base template path so that
+ * we can use {$admintemplatepath} from Smarty to get the right path, etc.
*
- * @param templateName
+ * @param templateName The name of the template, it is not necessary to provide
+ * the .template extension.
* @param blogInfo
- * @return A Template object
+ * @return A Template object pointing to a template from the templates/admin/ folder
*/
function AdminTemplate( $templateName, $blogInfo = null )
{
@@ -126,12 +148,18 @@
}
/**
- * returns a CachedTemplate object
+ * returns a CachedTemplate object, which works in exactly the same way as a Template
+ * object but its contents will be cached as soon as they are generated. The lifetime
+ * of cached contents is controlled via the 'template_cache_lifetime' configuration
+ * parameter, but contents will be regenerated automatically as soon as
+ * CacheControll::resetBlogCache() is called.
*
- * @param templateName
- * @param layout
+ * @param templateName The name of the template, it is not necessary to provide
+ * the .template extension.
+ * @param layout A predefined layout style, which corresponds with the name of a
+ * folder under the templates/ folder so 'blueish' would mean templates/blueish/
* @param blogInfo
- * @return a CachedTemplate object
+ * @return a CachedTemplate object pointing to the right .template file in disk
*/
function CachedTemplate( $templateName, $layout, $blogInfo = null )
{
@@ -197,8 +225,12 @@
* Plugins are different in the sense that they store their templates in the
* plugins/xxx/templates, where 'xxx' is the plugin identifier
*
- * @param pluginId
- * @param templateName
+ * @param pluginId The id of the plugin, which matches the name of a folder
+ * under the plugins/ folder.
+ * @param templateName Name of the template, without the .template extension
+ * @param blogInfo
+ * @return a Template object
+ * @see PluginCachedTemplate
*/
function PluginTemplate( $pluginId, $templateName, $blogInfo = null )
{
@@ -219,8 +251,15 @@
}
/**
- * cached version of templates for plugins
+ * Returns a CachedTemplate object loaded from a plugin template
+ * Plugins are different in the sense that they store their templates in the
+ * plugins/xxx/templates, where 'xxx' is the plugin identifier
*
+ * @param pluginId The id of the plugin, which matches the name of a folder
+ * under the plugins/ folder.
+ * @param templateName Name of the template, without the .template extension
+ * @param blogInfo
+ * @return a CachedTemplate object
*/
function PluginCachedTemplate( $pluginId, $templateName, $blogInfo = null )
{
Modified: plog/trunk/class/template/templatesets/templatefinder.class.php
===================================================================
--- plog/trunk/class/template/templatesets/templatefinder.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templatesets/templatefinder.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -5,6 +5,11 @@
include_once( PLOG_CLASS_PATH.'class/template/templatesets/templatesets.class.php' );
/**
+ * \ingroup Template
+ *
+ * This class looks for new templates, be it new blog-specifc templates or global templates. It
+ * will just scan the contents of a given folder and add any new templates it can find.
+ *
* @see FileFinder
*/
class TemplateFinder extends FileFinder
Modified: plog/trunk/class/template/templatesets/templateset.class.php
===================================================================
--- plog/trunk/class/template/templatesets/templateset.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templatesets/templateset.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -7,6 +7,8 @@
define( "TEMPLATE_SET_BLOG_SPECIFIC", 2 );
/**
+ * \ingroup Template
+ *
* abstraction for a template set
*/
class TemplateSet extends Object
Modified: plog/trunk/class/template/templatesets/templatesets.class.php
===================================================================
--- plog/trunk/class/template/templatesets/templatesets.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templatesets/templatesets.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -7,7 +7,11 @@
include_once( PLOG_CLASS_PATH."class/dao/blogs.class.php" );
/**
- * takes care of retrieving information about template sets.
+ * \ingroup Template
+ *
+ * Takes care of retrieving information about template sets. By using this class
+ * we can know which template sets are globally available, or which blog-specific templates
+ * a blog has.
*
* The relation between this class, TemplateService and TemplateSetStorage is that TemplateService
* takes care of generating the right object (CachedTemplate, PluginTemplate, Template) when
@@ -24,10 +28,12 @@
}
/**
+ * Returns all the template sets that are available for a given blog, including global
+ * templates by default.
*
- *
- * @param blogId
- * @param includeGlobal
+ * @param blogId The id of the blog
+ * @param includeGlobal Whether global templates should be included, or else only
+ * blog-specific templates will be returned.
* @return An array of TemplateSet objects
*/
function getBlogTemplateSets( $blogId, $includeGlobal = true )
@@ -49,8 +55,8 @@
}
/**
+ * Returns all the global template sets that are available to all blogs
*
- *
* @return returns an array of TemplateSet objects with all the global templates
*/
function getGlobalTemplateSets()
@@ -73,7 +79,7 @@
* Returns an array that contains the name of all the 'global' templates
* available.
*
- * @return Returns an array of strings
+ * @return Returns an array of strings with the name of the template sets
*/
function getGlobalTemplates()
{
Modified: plog/trunk/class/template/templatesets/templatesetstorage.class.php
===================================================================
--- plog/trunk/class/template/templatesets/templatesetstorage.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templatesets/templatesetstorage.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -9,16 +9,23 @@
define( "BLOG_BASE_TEMPLATE_FOLDER", "blog_" );
/**
+ * \ingroup Template
+ *
* deals with template sets files in disk. The relation between this class,
* TemplateService and TemplateSets is that TemplateService takes care of generating
* the right object (CachedTemplate, PluginTemplate, Template) when needed for rendering
* template pages. TemplateSets deals with the logical information (does it have an
* screenshot? Is it a local template?) and TemplateStorage deals with adding
* templates, removing them from disk, etc.
+ *
+ * Class and API users should not need to use this class directly.
*/
class TemplateSetStorage extends Object
{
+ /**
+ * Constructor
+ */
function TemplateSetStorage()
{
$this->Object();
Modified: plog/trunk/class/template/templateutils.class.php
===================================================================
--- plog/trunk/class/template/templateutils.class.php 2005-03-31 01:59:49 UTC (rev 1662)
+++ plog/trunk/class/template/templateutils.class.php 2005-03-31 07:38:12 UTC (rev 1663)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package template
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/dao/article.class.php" );
include_once( PLOG_CLASS_PATH."class/net/requestgenerator.class.php" );
@@ -14,15 +9,10 @@
include_once( PLOG_CLASS_PATH."class/net/http/httpvars.class.php" );
/**
- * This class provides methods to easily carry out some operations while inside the templates.
- * For example, it is quite painful to generate some of the urls that are used by pLog, so this
- * class provides methods to easily generate those. If, say, we want to get the permalink url for
- * a post, we do not have to know the format ourselves but rather, call the postPermalink function
- * that will generate it for us. This gives us the chance to change the format of these urls
- * in the future without -hopefully- having to modifiy the templates.
- * <br>
- * Of course the use of this class is optional but doing so, we will ensure future compatibility and
- * also readibility of our templates.
+ * @deprecated
+ * @see StringUtils
+ *
+ * \ingroup Template
*/
class TemplateUtils extends Object
{
More information about the pLog-svn
mailing list