# NAME

Jedi - Web App Framework

# VERSION

version 1.004

# 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](https://metacpan.org/pod/Jedi::App), it will automatically import [Moo](https://metacpan.org/pod/Moo) and the [Jedi::Role::App](https://metacpan.org/pod/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](https://metacpan.org/pod/Jedi) engine is a simple perl module that will handle the request and dispatch them to all your apps.

A [Jedi::App](https://metacpan.org/pod/Jedi::App) is plugged into the [Jedi](https://metacpan.org/pod/Jedi) engine by using the [Jedi::Launcher](https://metacpan.org/pod/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](https://metacpan.org/pod/Jedi) engine and start [Plack::Runner](https://metacpan.org/pod/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](https://metacpan.org/pod/Jedi), some of them for [Plack::Runner](https://metacpan.org/pod/Plack::Runner) and others for your apps.

### The part for [Jedi](https://metacpan.org/pod/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](https://metacpan.org/pod/Plack::Runner)

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

The config is take in that order : [Plack](https://metacpan.org/pod/Plack), then read Plack / server and read the section for the server, here it is [Starman](https://metacpan.org/pod/Starman).

Then all the config is converted for [Plack::Runner](https://metacpan.org/pod/Plack::Runner) as arguments. You can take a look to [plackup](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/Jedi::Launcher)

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

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

- [Jedi::App](https://metacpan.org/pod/Jedi::App)

    An [Jedi::App](https://metacpan.org/pod/Jedi::App) is a [Moo](https://metacpan.org/pod/Moo) package that will be load by [Jedi](https://metacpan.org/pod/Jedi).

    Each app declare a method 'jedi\_app'. This method is called directly by [Jedi](https://metacpan.org/pod/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.
