README

NAME

    Minima - Efficient web framework built with modern core classes


SYNOPSIS

    app.psgi

        use Minima;
        Minima::init;

    For a "hello, world":

        $ minima run    # or plackup app.psgi, as you prefer

    And that's it, you've got a functional app. To set up routes, edit
    etc/routes.map:

        GET     /           :Main   home
        POST    /login      :Login  process_login
        @       not_found   :Main   not_found

    Controllers:

        class Controller::Main :isa(Minima::Controller);

        method home {
            $view->set_template('home');
            $self->render($view, { name => 'world' });
        }

    Templates:

        %% if name
        <h1>hello, [% name %]</h1>
        %% end


DESCRIPTION

    Minima is a framework for PSGI web applications built with Perl's
    new native object-oriented features (perlclass). It is designed to
    be simple and minimal, connecting only what is necessary without
    getting in the way. Consequently, it's lightweight and fast.

    Although designed in a typical MVC fashion, no restrictions are
    imposed on design patterns. Controller classes have access to Plack
    request and response objects and can interact with them directly.
    Minima also provides a class for rendering HTML with ease with
    Template Toolkit, but you are free to use your own solution.

    To understand the basic principles of how it works, see the
    following section in this document. For more about the running
    process, check Minima::App. You may also want to visit
    Minima::Manual::Customizing to learn how to customize everything
    according to your needs.


HOW IT WORKS

    A typical web application using Minima operates as follows:

    1.  Minima::Setup is loaded. It will read a configuration file (if
        any, see "Config File" in Minima::Setup) and provides a "init"
        subroutine that is passed to Plack as the entry point for
        receiving requests.

    2.  A Minima::App is created and initialized with the supplied
        configuration.

    3.  Minima::App passes a routes file (where all application routes
        are defined) to Minima::Router to be read and parsed.

    4.  The request URL is matched to a route. Minima::App then calls
        the appropriate controller and method, setting them up and
        passing along the relevant information such as request and route
        data.

    5.  The controller handles the necessary logic, calling models (if
        required) and using views (if desired) to produce content.
        Content is then assigned to the response and finalized.


GETTING STARTED

    To begin a project, the Minima package provides a subroutine
    (described below) to help you get started with the process mentioned
    above.

    You can also interact directly with Minima::Setup for full control
    over the setup process.

  init

    sub init ($config = undef)

    A convenience subroutine that calls Minima::Setup::prepare to
    prepare the main app object and returns a reference to
    Minima::Setup::init.

    The optional argument allows you to specify the location of the
    configuration file.

    For a detailed explanation of behavior and options, refer to the
    documentation for Minima::Setup.


EXAMPLE

    Minima's repository contains an example application under eg/. To
    run it (from the root of the repository), use:

        $ cd eg
        $ plackup minima.psgi   # configure plackup or your server as needed


MANAGING A PROJECT

    Included with the distribution you'll find a helper program to
    manage projects. See minima for full details.

    One of its main features is creating a project from scratch, using
    templates with the recommended structure.

        $ minima new app


HISTORY

    While speaking with Paul Evans about the implementation of class in
    Perl's core, he remarked, "You should write a blog post about it."
    This led to *Problem #1*: I don't have a blog. Solving that seemed
    easy enough, but then came *Problem #2*: there wasn't a web
    framework that used the class feature. Naturally, I decided to
    tackle *Problem #2* first.


SEE ALSO

    perlclass, Minima::App, Minima::Manual::Customizing,
    Minima::Manual::FAQ.


AUTHOR

    Cesar Tessarin, <cesar@tessarin.com.br>.

    Written in September 2024.