Developer Customization

The ZineMachine supports handlers for customizing presentation beyond what basic CSS allows for. The supported handlers are:

• ZineAbout
• ZineAbstract
• ZineAttachment(@attachments)
• ZineAuthor
• ZineBody
• ZineFooter
• ZineHeader
• ZineIndex(%opt)
• ZinePicture($img)
• ZineRSS
• ZineShow
• ZineShowArticle
• ZineShowInfo
• ZineShowTeaser
• ZineShowRow($data,@columns)
• ZineShowFull
• ZineTopView
• ZineThumb

If you register a handler under any of these names, that handler will be called to generate the given item of content. (For example, the "ZineAbout" handler can be used to generate the "ZineAbout" section.) If the handler returns undef, then the ZineMachine will fall back on its default rules, so your handler can run conditionally.

You can define and register your handlers in myConfig.pm. All handlers will be executed under the Zine class, as if they belonged to the Zine framework.

See the Kernel developers guide for more information on handler programming.

Example: Poster Mini-Profiles

Some forum systems like to display a mini profile of the poster next to the comment. This may include information about their membership, location, posting history, and even a small thumbnail.

The HTML structure of comments allows meta-information about the post to be placed in an "about" block, which has a CSS class of "ZineAbout". By default this block contains the author name and posting date.

To customize the contents of the about block, you can define a handler that provides the contents of this block. The handler is dynamically scoped into the Zine class, so it has access to the internals of the Zine object (the Zine::Article object, in particular) from which it was called. It returns an HTML string that is used to populate the about block.

Handlers should be registered and defined in the myConfig.pm file.

Code

# in myConfig.pm

sub my_handlers {
    my $this = shift;

    # register our special handler
    $this->handler("ZineAbout",\&myZineAbout);
}

# now define our handler

sub myZineAbout {
    my $this = shift;     # $this is dynamically scoped into the Zine classes

    # get the UID of the owner of the post
    my $uid = $this->{article}{owner};

    if ($uid) {
       # ... a bunch of code here to fetch the relevant user info to display
       # ... more code to build an HTML snippet to display this info
       return $user_html;
    }
    else {
       # no UID - likely an anonymous or public posting
       # we return undef, which will default back to the generic about block
       return undef;
    }
}