====== Date/Time Extension for Command Plugin ======

---- plugin ----
description: Standardize date/time formats.
author     : Spider Joe
email      : http://www.spiderjoe.com
type       : syntax
lastupdate : 2005-09-03
compatible : 
depends    : command
conflicts  : 
similar    : 
tags       : extension, command, date, time
----

===== Overview =====

The **Date/Time Command** formats either a provided date/time or the current date/time to a pre-configured format.  It is an extension to the [[plugin:command|Command Plugin]], requiring that plugin and implementing a command of that plugin.  However, this particular command is part of the Command Plugin installation and so does not need to be installed separately.

This command allows you to do a few helpful things:

  * Centrally standardize how various date/times are displayed throughout the site.
  * Change the format of all date/times just by changing the configuration file.
  * Have the server determine the day of the week or some other auto-calculated value.
  * Quickly enter brief date/time representations in places that you actually want lengthier representations to appear.

===== Modification History =====

  * 2005/8/25 --- Created. [[http://www.spiderjoe.com|Spider Joe]]
  * 2005/9/3 --- Fixed RSS feed by changing hsc() to htmlspecialchars(). [[http://www.spiderjoe.com|Spider Joe]]

===== Syntax =====

The Date/Time command conforms to the [[plugin:command|Command Plugin]] syntax.  In particular, it takes one of the following forms:

  * ''%dt()%''
  * ''%dt(your date/time)%''
  * ''%dt?format_name()%''
  * ''%dt?format_name(your date/time)%''

As described in the [[plugin:command|Command Plugin]], the command name 'dt' is not case sensitive, and the above syntax embeds the date/time in a paragraph (the current paragraph), while ''#dt()#'' notation, replacing ''%'' with ''#'', places the date/time outside of paragraphs.  In the case of the 'dt' command, ''#dt()#'' notation results in the date/time being wrapped in an HTML div.  The ''%'' notation is called //inline embedding// and the ''#'' notation is called //block embedding//.

==== Command Name ====

Each extension of the [[plugin:command|Command Plugin]] has a unique command name.  This command takes the name **''DT''**.

==== Parameters ====

The values that may follow the ''?'' in a [[plugin:command|Command Plugin]] command are called parameters.  This command accepts one optional parameter:

  * ''<format_name>'' (optional): Name of the date/time format to use. The format is expected to appear in the configuration variable ''dtformat_<format_name>''.  This format name is case-sensitive.


==== Content ====

The text that the user inserts between the opening ''('' and closing '')'' parentheses of a [[plugin:command|Command Plugin]] is called the //content//.  For example, in ''%dt(8/25/05)%'', the content is ''8/25/05''.

If no content is provided, as in ''%dt()%'', the command formats the current date/time.  If content is provided, the command interprets the content as a date/time and formats it.  In this case the content must have a form that the PHP function ''strtotime()'' will read.  However, regardless of what content is provided, if no format has been specified for the command, the command is replaced with exactly its content, without formatting.

===== Description ======

The Date/Time command uses configuration variables to format the indicated date/time.  These variables are assigned in either ''/conf/dokuwiki.php'' or ''/conf/local.php''.  If no ''<format_name>'' is provided to the ''dt'' command, the command looks for the variable 'dtformat'.  If a ''<format_name>'' is provided, the command looks for the variable 'dtformat_<format_name>'.

For example, in the command ''%dt?cal(8/25/05)%'', the configuration variable is 'dtformat_cal'.  If the following line occurs in the configuration file, this command would be replaced with ''August 25, 2005'':

<code>
    $conf['dtformat_cal'] = 'F j, Y';
</code>

The configuration variable can be formatted in one of two ways:

  * ''<format>''
  * ''<css_class>|<format>''

''<format>'' is the format in which to rewrite the date/time.  It is a string that conforms to the format that PHP's ''date()'' function accepts.

''<css_class>'' optionally precedes ''<format>'', separated from it by a vertical bar.  When present, the rewritten date/time of an inline embedding (''%'' notation) will be ''<span class='css_class'>datetime</span>'', while that of a block embedding (''#'' notation) will be ''<div class='css_class'>datetime</div>''.  The configuration variable specifies the particular CSS class.

If the appropriate configuration variable does not exist, the command just outputs the content unchanged.  If the command was a block embedding, this content is first wrapped in ''<div>...</div>''.

===== Installation =====

The Date/Time command comes with the basic [[plugin:command|Command Plugin]] installation and is immediately available once the plugin is installed.  However, you will need to add formats to the configuration file.

Should you delete the command and wish to reinstall it, all you need to do is to save the [[#source]] file with filename ''dt.php'' in the following directory:

<code>
/lib/plugins/command/ext/
</code>

After installing the command, don't forget to add any formats you might need to the configuration file, as described in the [[#description]] of this command.


===== Source (dt.php) =====

<code php><?php
/**
 * Date/time Command: Formats a date/time to a pre-configured format.
 *
 * For a full description of this Command Plugin command, see:
 *   http://www.splitbrain.org/plugin:date-time
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Joe Lapp <http://www.spiderjoe.com>
 */
 
class CommandPluginExtension_dt extends CommandPluginExtension
{
    function getCachedData($embedding, $params, $paramHash, $content,
                             &$errorMessage) // STATIC
    {
        global $conf;

        // Determine the name of the configuration variable.

        $configName = 'dtformat';
        if(sizeof($params) == 1 && is_string($params[0]))
            $configName .= '_'.$params[0];
        else if(sizeof($params) != 0)
        {
            $errorMessage = "_INVALID_DT_PARAMETERS_";
            return null; // return value doesn't matter in this case
        }

        // Load the css class and the date format from the variable.
    
        $cssClass = null;
        $format = null;

        $configVal = null;
        $configVal = @$conf[$configName];
        
        if($configVal != null)
        {
            $barPos = strpos($configVal, '|');
            if($barPos === false)
                $format = $configVal;
            else
            {
                $cssClass = substr($configVal, 0, $barPos);
                // next line works even if there is no format
                $format = substr($configVal, $barPos + 1);
            }
        }
        
        // Format the date/time.
        
        if(!empty($format))
        {
            if(trim($content) == '')
                $newDT = date($format);
            else
                $newDT = date($format, strtotime($content));
        }
        else
            $newDT = $content;
        
        $newDT = htmlspecialchars($newDT);

        // Return the newly formatted date/time.

        if($embedding == 'block')
        {
            if($cssClass)
                return '<div class=\''.$cssClass.'\'>'.$newDT.'</div>';
            return '<div>'.$newDT.'</div>';
        }
        else if($cssClass)
            return '<span class=\''.$cssClass.'\'>'.$newDT.'</span>';
        return $newDT;
    }
}
?>
</code>

===== Examples =====

  * Suppose ''$conf['dtformat']'' is not set.  Then:

<code>
  %dt()% ==> (empty string)
  %dt(8/25/05)% ==> 8/25/05
  %DT(8/25/05)% ==> 8/25/05 (case does not matter)
  #dt(8/25/05)# ==> <div>8/25/05</div>
</code>

  * The given configuration produces the indicated replacements:

<code>
  $conf['dtformat'] = 'F j, Y';
</code>

<code>
  %dt()% ==> August 25, 2005 (or whatever the day's date happens to be)
  %dt(8/25/05)% ==> August 25, 2005
  #dt(25 Aug 2005)# ==> <div>August 25, 2005</div>
</code>

  * The given configuration produces the indicated replacements:

<code>
  $conf['dtformat'] = 'prettydt|D j M Y';
</code>

<code>
  %dt(8/25/05)% ==> <span class='prettydt'>Thu 25 Aug 2005</span>
  #dt(8/25/05)# ==> <div class='prettydt'>Thu 25 Aug 2005</div>
</code>

  * Suppose ''$conf['dtformat_cal']'' is not set.  Then:

<code>
  %dt?cal(8/25/05 9:52)% ==> 8/25/05 9:52
  #dt?cal(8/25/05 9:52)# ==> <div>8/25/05 9:52</div>
</code>

  * The given configuration produces the indicated replacements:

<code>
  $conf['dtformat_cal'] = 'j M y H:i';
</code>

<code>
  %dt?cal()% ==> 25 Aug 05 08:01 (or whatever the day's date happens to be)
  %dt?cal(8/25/05 9:52)% ==> 25 Aug 05 09:52
  #dt?cal(8/25/05 9:52)# ==> <div>25 Aug 05 09:52</div>
</code>

  * The given configuration produces the indicated replacements:

<code>
  $conf['dtformat_cal'] = 'calendardt|D g:i a';
</code>

<code>
  %dt?cal(8/25/05 9:52)% ==> <span class='calendardt'>Thu 9:52 am</span>
  #dt?cal(8/25/05 9:52)# ==> <div class='calendardt'>Thu 9:52 am</div>
</code>

===== Copy Notice =====

When creating your own commands, it will be helpful for you to start by copying this command and its documentation.  Feel free to copy and modify as you please -- subject to the GPL 2 license, of course.  I'm encouraging it.

===== Discussion =====

Should I provide a default date/time format for ''%dt()%''?  If so, what should the default format be?  Right now, if no ''dtformat'' configuration variable is specified, the command is simply removed (replaced by an empty string).  [[http://www.spiderjoe.com|Spider Joe]]

> I tend to think it would be better if rather than asking the user to modify ''conf/local.php'' the plugin had its own settings file.  You may want to check out the "in development" [[devel:Admin Plugins]]((if this page is still missing, see the [[http://wiki.jalakai.co.uk/dokuwiki/doku.php/tutorials/admin_plugins|development docs]])) to provide a mechanism for the DokuWiki administrator to update the plugins settings.

>>I'll let someone else add that feature.  I personally prefer to work with text files --- that's why I'm using [[:DokuWiki]].  And I like having all my configuration in one place.  Besides, I'm trying to do the least amount of coding that does the job. --- [[http://www.spiderjoe.com|Spider Joe]]