NAME

Dancer2::Plugin::LiteBlog::Blog - Blog widget for Liteblog.

DESCRIPTION

This module is responsible for handling the core blog functionalities within the Dancer2::Plugin::LiteBlog system. It extends from the 'Widget' class and provides features to retrieve and display blog articles or pages as well as category pages and a landing page widget used to display blog post cards.

SYNOPSIS

A Blog object is based on a root directory that must hold a blog-meta.yml file, describing all specific details of the blog. In this directory, pages and articles are located, represented by Dancer2::Plugin::LiteBlog::Article objects.

ATTRIBUTES

meta

Read-only attribute that retrieves and returns the meta information for the blog from the 'blog-meta.yml' file. If this file is not found, an exception will be thrown.

mount

Read-only attribute that set where the blog resources should be accessible from, in the site's URL.

elements

Read-only attribute that contains a list of featured posts to show on the home page widget section.

If no_widget is set, return nothing (no widget will be rendered on the home page).

If a featured_post entry is found in the blog-meta file of the widget, use this. If not, returns the last 3 posts published. Each post is represented as an instance of the Dancer2::Plugin::LiteBlog::Article class.

select_articles (%params)

Lookup the article repository (root) for articles that match the criteria.

Articles are always returned in descending chronological order (using their published_date attibute).

TODO : Should recursively find articles in all category as well as top-level pages.

params

  • limit: (default: 1), number of article to retreive (max: 20).

  • category: if specified, limit the lookup to articles of that category

find_article (%params)

Searches and returns an article based on the provided path. Optionally, you can specify a category as well. Cache the resulting object in-memory for future calls with same params.

  • path: The path to the article. This is mandatory.

  • category: The category of the article. This is optional. If given, the path will be prefixed with the category.

If the article is found, it returns an instance of Dancer2::Plugin::LiteBlog::Article corresponding to the article. Otherwise, it returns undef.

Examples:

    # Find an article in the 'tech' category with path 'new-tech'
    my $article = $blog->find_article(category => 'tech', path => 'new-tech');

    # Find an article with path 'about-me'
    my $article = $blog->find_article(path => 'about-me');

Note: The method will croak if the path parameter is not provided or if an invalid category is provided.

LITEBLOG WIDGET INTERFACE

This class implements the Dancer2::Plugin::LiteBlog::Widget interface. It declares routes.

has_routes

Returns a true value as routes are declared by this Widget.

declare_routes

This method declares routes for the Dancer2 application.

GET /$mount/:cat/:slug

Retrieves and displays a specific article based on its category (:cat) and permalink (:slug). If the article is not found, it will return a 404 status. The rendering is done with the liteblog/single-page template.

The prefix ($mount) is taken from the mount attriute of the instance and defaults to /blog.

Examples:

  /blog/tech/new-tech
  /blog/lifestyle/my-journey

GET /blog/:category/:slug/:asset

If the :asset is a readable file in the article's directory, this route sends it back to the client. This is useful for hosting local files like images, PDF, etc in the article's folder.

Example:

    /blog/tech/some-article/featured.jpg

GET /:page

This is a catch-all route for retrieving and displaying any article based on its page path. If the article is not found, it will pass, this might be a category page.

Examples:

  /about-me
  /contact

GET /blog/:category/

Displays a landing page for a specific category. If the category is not found or invalid, it will return a 404 status. The rendering is done with the 'liteblog/single-page' template.

Examples:

  /blog/tech/
  /blog/lifestyle/

GET /blog/rss/

GET /blog/category/rss/