NAME

Dotiac::DTL::Addon - Manages Dotiac::DTL-addons.

DESCRIPTION

How to write your own addons

Addons are just perl modules living in the Dotiac::DTL::Addon namespace;

They can be called in two ways, as shown here with the example the Dotiac::DTL::Addon::foobar addon.

In a template file:

        {% load foobar %}

In a perl skript:

        use Dotiac::DTL::Addon::foobar; #not require, USE.

When loaded in a template file, the addon stays loaded until the next template calls string(), print() or ... .

When used with "use Dotiac::DTL::Addon::..." the addon is loaded always, this may be sometimes what you disire, but not always:

Take a locale addon for example. One page might need the default english locale and another one will need the german one. If you load the german locale via use ..., it will result in all pages having it.

How it works.

Both {% load x %} and use Dotiac::DTL::Addon::x; call the class-method Dotiac::DTL::Addon::x-import()> when run. This import method makes all the neccessary adjustments to Dotiac::DTL.

When called by {% load x %} the next call to string(),print() or similar will call the Dotiac::DTL::Addon::x-unimport()> method. That method must clean up all the changes done to Dotiac::DTL.

The unload order is the same as the load order, so the addons can just save the values they overwrite (if any).

If you are just adding a tag or a filter, you can just provide empty import() and unimport() methods, but see the warning below.

Example for a locale addon

This adds a german loacle as "german_locale":

        package Dotiac::DTL::Addon::german_locale;
        require Dotiac::DTL::Filter;
        use strict;
        use warnings;
        #Save the old values
        our @datemonths;
        our @datemonthl;
        our @datemontha;
        our @weekdays;
        our @weekdayl;
        our @timeampm;
        our @timespotnames;
        our @datesuffixes;
        our @filesizeformat;
        our $pluralizedefault;
        our $floatformatlocale;
        our @timenames;
        our $TIME_FORMAT;
        our $DATE_FORMAT;
        our $DATETIME_FORMAT;

        sub import {
                #Save values
                @datemonths=@Dotiac::DTL::Filter::datemonths;
                @datemonthl=@Dotiac::DTL::Filter::datemonthl;
                @datemontha=@Dotiac::DTL::Filter::datemontha;
                @weekdays=@Dotiac::DTL::Filter::weekdays;
                @weekdayl=@Dotiac::DTL::Filter::weekdayl;
                @timeampm=@Dotiac::DTL::Filter::timeampm;
                @timespotnames=@Dotiac::DTL::Filter::timespotnames;
                @datesuffixes=@Dotiac::DTL::Filter::datesuffixes;
                @filesizeformat=@Dotiac::DTL::Filter::filesizeformat;
                $pluralizedefault=$Dotiac::DTL::Filter::pluralizedefault;
                $floatformatlocale=$Dotiac::DTL::Filter::floatformatlocale;
                @timenames=@Dotiac::DTL::Filter::timenames;
                #Set new values
                @Dotiac::DTL::Filter::datemonths=qw( Jan Feb M&aum;r Apr Mai Jun Jul Aug Sep Okt Nov Dez );
                @Dotiac::DTL::Filter::datemonthl=qw( Januar Februar März April Mai Juni Juli August September Oktober November Dezember );
                @Dotiac::DTL::Filter::datemontha=qw( Jan. Feb. März April Mai Juni Juli Aug. Sep. Okt. Nov. Dez. );
                @Dotiac::DTL::Filter::weekdays=qw/So Mo Di Mi Do Fr Sa/;
                @Dotiac::DTL::Filter::weekdayl=qw/Sonntag Montag Dienstag Mittwock Donnerstag Freitag Samstag/;
                @Dotiac::DTL::Filter::timeampm=qw/a.m. p.m. AM PM/;
                @Dotiac::DTL::Filter::timespotnames=qw/Mitternacht Mittag/;
                @Dotiac::DTL::Filter::datesuffixes=qw/te/;
                @Dotiac::DTL::Filter::filesizeformat=qw/Bytes Kb Mb Gb Tb Eb Pb vielebytes vielebytes vielebytes vielebytes/;
                $Dotiac::DTL::Filter::floatformatlocale=sub {my $v=shift;$v=~s/\./,/g;return $v;};
                $Dotiac::DTL::Filter::pluralizedefault="n";
                @Dotiac::DTL::Filter::timenames=qw/Jahr Jahren Monat Monaten Woche Wochen Tag Tagen Stunde Stunden Minute Minuten/;
                #Time format
                $TIME_FORMAT=$Dotiac::DTL::TIME_FORMAT;
                $DATE_FORMAT=$Dotiac::DTL::DATE_FORMAT;
                $DATETIME_FORMAT=$Dotiac::DTL::DATETIME_FORMAT;
                $Dotiac::DTL::TIME_FORMAT="H:i";
                $Dotiac::DTL::DATE_FORMAT="d. M. Y";
                $Dotiac::DTL::DATETIME_FORMAT="d. M. Y, H:i";
        }
        sub unimport {
                #Restore values
                @Dotiac::DTL::Filter::datemonths=@datemonths;
                @Dotiac::DTL::Filter::datemonthl=@datemonthl;
                @Dotiac::DTL::Filter::datemontha=@datemontha;
                @Dotiac::DTL::Filter::weekdays=@weekdays;
                @Dotiac::DTL::Filter::weekdayl=@weekdayl;
                @Dotiac::DTL::Filter::timeampm=@timeampm;
                @Dotiac::DTL::Filter::timespotnames=@timespotnames;
                @Dotiac::DTL::Filter::datesuffixes=@datesuffixes;
                @Dotiac::DTL::Filter::filesizeformat=@filesizeformat;
                $Dotiac::DTL::Filter::pluralizedefault=$pluralizedefault;
                $Dotiac::DTL::Filter::floatformatlocale=$floatformatlocale;
                @Dotiac::DTL::Filter::timenames=@timenames;
                $Dotiac::DTL::TIME_FORMAT=$TIME_FORMAT;
                $Dotiac::DTL::DATE_FORMAT=$DATE_FORMAT;
                $Dotiac::DTL::DATETIME_FORMAT=$DATETIME_FORMAT;
        }
        1;

Example for a filter addon

        package Dotiac::DTL::Addon::myfilters;
        sub import {
                #No need to do anything here, filters can stay loaded all the time, but see the warning below.
        }
        sub unimport {
        }
        package Dotiac::DTL::Filters;
        #Not very useful filters, they should just serve as an example:
        # don't forget: Filters get and return Dotiac::DTL::Value objects.
        sub foobar {
                return Dotiac::DTL::Value->safe("Foobar")
        }
        sub helloworld {
                return Dotiac::DTL::Value->safe("Hello, World")
        }
        1;

Warning:

Using the above way to write a filter addon, will result in undefined behavior when two filters share the same name. This is because unimport() does nothing. A better way would be: Let import overwrite the function via modifying the symbol table and let unimport reverse it again.

Any tag addon

Tags can't share the same name, because they would be in the same file. (Unless you make it the wrong file, but that's not my problem then)

        package Dotiac::DTL::Addon::mytagcollection;
        require Dotiac::DTL::Tag::mytag1;
        require Dotiac::DTL::Tag::mytag2;
        #...
        sub import {
        }
        sub unimport {
        }
        1;

Internal stuff of Dotiac::DTL::Addons

These should not be used from anybody else than Dotiac::DTL::Core.

restore

Calls unimport on all methodes loaded by {% load %}

@Dotiac::DTL::Addons::loaded

Stores the loaded module names;

%Dotiac::DTL::Addons::NOCOMPILE

Modules that shouldn't be included into compiled template (by {% load %}) should register themselves here.

These are mostly:

Parser changing modules.

The Parser is not needed in compiled templates

Tag adding modules.

Since the Tags are compiled down to Perl-code, their source is not needed anymore

Modules that add filters have to stay

BUGS

If you find a bug, please report it.

SEE ALSO

http://www.djangoproject.com, Dotiac::DTL

LEGAL

Dotiac::DTL was built according to http://docs.djangoproject.com/en/dev/ref/templates/builtins/.

AUTHOR

Marc-Sebastian Lucksch

perl@marc-s.de

cpanm Dotiac::DTL

perl -MCPAN -e shell
install Dotiac::DTL