NAME

Dancer2::Plugin::LiteBlog::Widget - Base class for LiteBlog widgets

SYNOPSIS

This is an abstract class and should be subclassed.

USAGE

package MyWidget;
use Moo;
extends 'Dancer2::Plugin::LiteBlog::Widget';

sub elements {
    # Implement the elements method
    # $element = []; ...
    return $elements;
}

DESCRIPTION

This is a base class (interface) for widgets used in LiteBlog, a Dancer2 plugin. Widgets that extends that interface are expected to implement certain methods to be functional.

Widgets in LiteBlog are used to render some UI elements in the site and can provide their own views and CSS.

ATTRIBUTES

root

The root attribute specifies the root directory for the widget. It's a required attribute and must be a valid directory, or an error will be thrown.

This directory is the base directory of the widget, where resources will be looked for such as YAML or Markdown files, depending on the implementation of the widget.

dancer

Optional read-only attribute.

The dancer attribute is a handle over the Dancer2::Core::DSL instance of Liteblog. This is useful for logging to the Dancer App.

Example:

$self->dancer->info("Some debugging info from the widget");

METHODS

info ($message)

If a dancer attribute is set, issue a info call with the given message, properly prefixed by the Widget's name. If no dancer is defined, returns undef and does nothing.

error ($message)

If a dancer attribute is set, issue a error call with the given message, properly prefixed by the Widget's name. If no dancer is defined, returns undef and does nothing.

elements

This method must be implemented by any class inheriting from this module. It must return a list of objects that will be iterated over in the widget's template for rendering. The objects themselves depend on the widget and should be coherent with the associated view.

See Dancer2::LiteBlog::Widget::Activities for a simple example.

has_routes

If the widget adds route to the Dancer2 application, it should override this method to return a true value.

has_rss

Returns true if the widget is supposed to expose a RSS feed. Defaults to false. If set to true in the child class, attribute mount must be defined as well to construct the feed URL, and a mount/rss/ route must be declared.

declare_routes($self, $plugin, $config)

Any widget intending to declare its own routes should implement this method. The method is passed the Dancer2::Plugin $plugin object associated with LiteBlog (which provides handlers to the DSL and other Dancer2's internal APIs, and the Widget's config section.

sub declare_routes {
    my ($self, $plugin, $config) = @_;
    $plugin->app->add_route(
        ...
    );
}

cache ($key[, $val])

$widget->cache($key, $value);  # set
my $value = $widget->cache($key);  # get

Provides a simple caching interface within a widget, storing values in a private singleton hash. Cache keys are constructed uniquely for each calling class and the provided key to avoid collisions, formatted as "ClassName[$key]". When called with a single argument, it acts as a getter, returning the value for the given key if present. With two arguments, it stores the value under the specified key, acting as a setter.

SEE ALSO

Dancer2::Plugin::LiteBlog, Dancer2, Moo

AUTHOR

Alexis Sukrieh, sukria@gmail.com

COPYRIGHT AND LICENSE

Copyright 2023 by Alexis Sukrieh.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Dancer2::Plugin::LiteBlog

perl -MCPAN -e shell
install Dancer2::Plugin::LiteBlog