DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:date_time

Date/Time Extension for Command Plugin

Compatible with DokuWiki

No compatibility info given!

plugin Standardize date/time formats.

Last updated on
2005-09-03
Provides
Syntax
Requires
command

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Extension name contains underscore, will not generate popularity points.

Tagged with command, date, extension, 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 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. Spider Joe
  • 2005/9/3 — Fixed RSS feed by changing hsc() to htmlspecialchars(). Spider Joe

Syntax

The Date/Time command conforms to the 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 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 Command Plugin has a unique command name. This command takes the name DT.

Parameters

The values that may follow the ? in a 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 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:

    $conf['dtformat_cal'] = 'F j, Y';

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 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:

/lib/plugins/command/ext/

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)

<?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;
    }
}
?>

Examples

  • Suppose $conf['dtformat'] is not set. Then:
  %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>
  • The given configuration produces the indicated replacements:
  $conf['dtformat'] = 'F j, Y';
  %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>
  • The given configuration produces the indicated replacements:
  $conf['dtformat'] = 'prettydt|D j M Y';
  %dt(8/25/05)% ==> <span class='prettydt'>Thu 25 Aug 2005</span>
  #dt(8/25/05)# ==> <div class='prettydt'>Thu 25 Aug 2005</div>
  • Suppose $conf['dtformat_cal'] is not set. Then:
  %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>
  • The given configuration produces the indicated replacements:
  $conf['dtformat_cal'] = 'j M y H:i';
  %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>
  • The given configuration produces the indicated replacements:
  $conf['dtformat_cal'] = 'calendardt|D g:i a';
  %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>

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). 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” Admin Plugins1) 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. — Spider Joe
1)
if this page is still missing, see the development docs
plugin/date_time.txt · Last modified: 2015-06-24 21:22 by Klap-in