NAME

Jedi - Web App Framework

VERSION

version 1.007

DESCRIPTION

Jedi is a web framework, easy to understand, without DSL !

In a galaxy, far far away, a mysterious force is operating. Come on young Padawan, let me show you how to use that power wisely !

SYNOPSIS

An Jedi App is simple as a package in perl. You can initialize the app with the jedi launcher and a config file.

When you include Jedi::App, it will automatically import Moo and the Jedi::Role::App in your package.

In MyApps.pm :

package MyApps;
use Jedi::App;

sub jedi_app {
 my ($app) = @_;
 $app->get('/', $app->can('index'));
 $app->get('/config', $app->can('show_config'));
 $app->get(qr{/env/.+}, $app->can('env'));
}

sub index {
 my ($app, $request, $response) = @_;
 $response->status(200);
 $response->body('Hello World !');
 return 1;
}

sub env {
 my ($app, $request, $response) = @_;
 # path return always a "/" at the end
 # so /env/QUERY_STRING?a=1 => path = /env/QUERY_STRING/
 my $env = substr($request->path, length("/env/"), -1); 
 $response->status(200);
 $response->body(
     "The env : <$env>, has the value <" .
     ($request->env->{$env} // "") . 
   ">");
 return 1;
}

sub show_config {
 my ($app, $request, $response) = @_;
 $response->status(200);
 $response->body($app->jedi_config->{MyApps}{foo});
 return 1;
}

1;

In MyAdmin.pm :

package MyAdmin;
use Jedi::App;

sub jedi_app {
  my ($app) = @_;
  $app->get('/', $app->can('index_admin'));
}

sub index_admin {
 my ($app, $request, $response) = @_;
 $response->status(200);
 $response->body('Admin !');
}
1

The you can create a lauching config app.yml :

Jedi:
  Roads:
    MyApps: "/"
    MyAdmin: "/admin"
Plack:
  env: production
  server: Starman
Starman:
  workers: 2
  port: 9999
MyApps:
  foo: bar

To start your app :

perl-jedi -c app.yml

And if you want to test your app with your package inside the 'lib' directory :

perl-jedi -Ilib -c app.yml

You can try requests :

curl http://localhost:9999/
# Hello World !

curl http://localhost:9999/config
# bar

curl http://localhost:9999/admin
# Admin !

curl http://localhost:9999/env/QUERY_STRING?a=1
# The env : <QUERY_STRING>, has the value <a=1>

HOW TO LAUNCH YOUR APPS

The Jedi engine is a simple perl module that will handle the request and dispatch them to all your apps.

A Jedi::App is plugged into the Jedi engine by using the Jedi::Launcher and a launch config file, or directly by using Jedi with Plack.

WITH THE Jedi::Launcher

This is the recommended method, because it will load you config files, merge them, init the Jedi engine and start Plack::Runner with your config.

The launcher name is 'perl-jedi', and it take your configs as parameter :

perl-jedi -c myGlobalConf.yml -c myConfForPlack.yml -c myEnvProd.yml

All this config will be merge together to create a simple HASH.

The config is composed of different parts, some of them for Jedi, some of them for Plack::Runner and others for your apps.

The part for Jedi

Jedi:
  Roads:
    Jedi::App::Blog: '/'
    Jedi::App::BlogAlt: '/'
    Jedi::App::Admin::Blog: '/admin'

It will load Jedi::App::Blog and Jedi::App::BlogAlt, and mount it into "/". And also load Jedi::App::Admin::Blog, and mount it into "/admin"

You can push severals roads here, and many modules can be used with the same road. If one app doesn't take the path, it could be handle by the next app.

The part for Plack::Runner

Plack:
  env: production
  server: Starman
Starman:
  workers: 2
  port: 9999

The config is take in that order : Plack, then read Plack / server and read the section for the server, here it is Starman.

Then all the config is converted for Plack::Runner as arguments. You can take a look to plackup for all possible options.

The part for your app

You will receive all the config, like a simple HASH into all your apps. And this will be exactly the same data. So technically you can create the config you want.

But I advice for sharing purpose (if you release that on cpan), to use as a base key for your app, the name of your package :

Jedi::App::Blog:
  template_dir: /var/www/blog
Jedi::App::BlogAlt:
  template_dir: /var/www/blog/alt
Jedi::App::Admin::Blog:
  defaultAdmin:
    user: admin
    password: admin

So app can read and change the config of other apps on the fly. Also you can create plugin that can do that...

For example, the Jedi::Plugin::Template, will create a key PACKAGE/template_dir when it is used. So you can override that value to use another template.

WITH Jedi AND plackup

The above example is equivalent to :

plackup --env production --server Starman --workers 2 --port 9999 app.psgi

And the app.psgi contain :

use Jedi;
my $jedi = Jedi->new(config => {%configToLoadYourSelfHere});
$jedi->road('/' => 'Jedi::App::Blog');
$jedi->road('/' => 'Jedi::App::BlogAlt');
$jedi->road('/admin' => 'Jedi::App::Admin::Blog');
$jedi->start;

MANUALS

• Jedi::Launcher

  You have a good overview of the jedi launcher here. You can run :

  perl-jedi --help
  perl-jedi --man
  

• Jedi::App

  An Jedi::App is a Moo package that will be load by Jedi.

  Each app declare a method 'jedi_app'. This method is called directly by Jedi to initialize your app.

  This is the good place to declare your routes, and initialize your databases and any stuff you need.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/celogeek/perl-jedi/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

celogeek me@celogeek.com

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by celogeek me@celogeek.com.

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