File Coverage

blib/lib/Articulate.pm

Criterion	Covered	Total	%
statement	15	21	71.4
branch			n/a
condition			n/a
subroutine	5	6	83.3
pod	1	1	100.0
total	21	28	75.0

package Articulate;
use strict;
use warnings;

use Moo;
with 'MooX::Singleton';

use Articulate::Service;
use Module::Load ();
our $VERSION = '0.003';

=head1 NAME

Articulate - A lightweight Perl CMS Framework

=head1 WARNING

This is very much in alpha. Things will change. Feel free to build things and have fun, but don't hook up anything business-critical just yet!

=head1 SYNOPSIS

	# (in bin/app.pl)
	use Dancer;
	use Dancer::Plugin::Articulate;
	articulate_app->enable;
	dance;

B provides a content management service for your web app. It's lightweight, i.e. it places minimal demands on your app while maximising 'whipuptitude': it gives you a single interface in code to a framework that's totally modular underneath, and it won't claim any URL endpoints for itself.

You don't need to redesign your app around Articulate, it's a service that you call on when you need it, and all the 'moving parts' can be switched out if you want to do things your way.

It's written in Perl, the fast, reliable 'glue language' that's perfect for agile web development projects, and currently runs on the L and L web frameworks.

=head1 GETTING STARTED

Don't forget to install Articulate - remember, it's a library, not an app.

	# From source:
	perl Makefile.PL
	make
	make test
	make install

Check out the examples in the C folder of the distribution.

To add Articulate to your own app, you'll need to:

=over

=item * add it to your C or similar (see example above) using either L or L.

=item * edit your C to configure the components you want (check each of the components for a description of their config options - or just borrow a config from one of the examples)

=item * write any custom code you want if you don't like what's there, and just swap it out in the config.

=item * polish off your front-end, all the backend is taken care of!

=back

Curious about how it all fits together? Read on...

=head1 DESCRIPTION

Articulate is a set of components that work together to provide a content management service that will sit alongside an existing Dancer app or form the basis of a new one.

If you want to see one in action, grab the source and run:

	# If you have Dancer and Dancer::Plugin::Articulate installed:
	cd examples/plain-speaking
	perl bin/app.pl -e dancer1

	# Or, if you have Dancer2 and Dancer2::Plugin::Articulate installed:
	cd examples/plain-speaking
	perl bin/app.psgi

You can see how it's configured by looking at

	examples/plain-speaking/config.yml

Notice that C doesn't directly load anything but the Articulate plugin (which loads config into this module). Everything you need is in C, and you can replace components with ones you've written if your app needs to do different things.

=head2 Request/Response lifecycle summary

In a B, you parse user input and pick the parameters you want to send to the B. Have a look at L for some examples. The intention is that routes are as 'thin' as possible: business logic should all be done by some part of the service and not in the route handler. The route handler maps endpoints (URLs) to service requests; structured responses are passed back as return values and are picked up by the B.

B pass B to B. A B contains a B (like C) and B (like the B you want to create it at and the B you want to place there). See L for more details.

The B is responsible for handling requests for managed content. L B to a service B, asking each in turn if they are willing to handle the request (normally the provider will dertermine this based on the request verb). A provider typically checks a user has suitable permission, then interacts with the content storage system.

B is controlled by L. It delegates to a storage class which is configured for actions like C and C.

Content is stored in a structure called an B (see L), which has a C (see L), the B (which could be a binary blob like an image, plain text, markdown, XML, etc.) and the associated B or B (which is a hashref).

Before items can be placed in storage, the service should take care to run them through B. L delegates this to validators, and if there are any applicable validators, they will check if the content is valid. The content may also be B, i.e. further metadata added, like the time at which the request was made (consult L for details).

After items are retrieved from storage, there is the opportunity to B them, for instance by including relevant content from elsewhere which belongs in the response. See L for details on this.

If at any time uncaught errors are thrown, including recognised L objects, they are caught and handled by L. L should therefore always return an L object.

Once the request finds it back to the Route it will typically be B immediately (see L), and the resulting response passed back to the user.

=head2 Components

The following classes are persistent, configurable B of the system:

=over

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=back

=head2 Data Classes

The following classes are used for passing request data between components:

=over

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=item * L

=back

=head2 Other modules of interest

=over

=item * L

=item * L

=item * L

=item * L

=item * L

=back

=head2 Instantiation

Articulate provides a very handy way of creating (or B) objects through your config. The following config, for instance, assignes to the providers attribute (on some other object), an arrayref of four objects, the first created without no arguments, two created with arguments, and a final one created without arguments but using an unusual constructor.

	providers:
		- MyProvider::Simple
		- class: MyProvider::Congfigurable
			args:
				verbose: 1
		- MyProvider::Congfigurable:
				lax: 1
				verbose: 1
		- class: MyProvider::Idiosyncratic
			constuctor: tada

For more details, see L.

=head2 Delegation

A key part of the flexibility of Articulate is that objects often B functions to other objects (the B)

Typically, one class delegates to a series of providers, which are each passed the same arguments in turn. L is a good example of this. Sometimes the response from one provider will halt the delegation - see L for an example of this.

Occasionally, only one provider is possible, for instance L. In this case there is a substitution rather than a delegation.

=cut

=head1 METHOD

=head3 enable

Sets up the routes. This does not happen at construction so you can control the point at which routes are declared.

=head1 ATTRIBUTES

=head3 enabled

Please do not set this directly, use C instead.

=head3 routes

The packages which provide routes for Articulate. See L and L for more details.

=head3 components

The different working pieces of the Articulate app. Components all have access to each other indirectly and they provide features across Articulate; see L for more details.

=cut

sub enable {
	my $self = shift;
	foreach my $route (@{ $self->routes }){
		$route->app($self);
		$route->enable;
	}
	$self->enabled(1);
}

has enabled =>
	is      => 'rw',
	default => sub { 0 };

has routes => (
	is      => 'rw',
	default => sub { [] },
	coerce  => sub { Module::Load::load('Articulate::Syntax'); Articulate::Syntax::instantiate_array ( @_ ) },
	trigger => sub {
		my $self = shift;
		my $orig = shift;
		$_->app($self) foreach @$orig;
	},
);

has components => (
	is      => 'rw',
	default => sub { {} },
	coerce  => sub {
		my $orig = shift;
		Module::Load::load('Articulate::Syntax');
		Articulate::Syntax::instantiate_selection ( $orig );

	},
	trigger => sub {
		my $self = shift;
		my $orig = shift;
		$orig->{$_}->app($self) foreach keys %$orig;
	},
);

=head1 BUGS

Bugs should be reported to the L. Pull Requests welcome!

=head1 COPYRIGHT

Articulate is Copyright 2014-2015 Daniel Perrett. You are free to use it subject to the same terms as perl: see the LICENSE file included in this distribution for what this means.

Currently Articulate is bundled with versions of other software whose license information you can access from the LICENSE file.

=cut

1;