/ 
Egg-Release-1.17
River stage two • 17 direct dependents • 17 total dependents
/ Egg

NAME

Egg - WEB application framework.

SYNOPSIS

First of all, the helper script is generated.

#> perl -MEgg::Helper::Script -e "Egg::Helper::Script->out" > /path/to/bin/egg_helper.pl

And, the project is generated.

#> cd /path/to/work_dir
#> /path/to/bin/egg_helper.pl project -p MYPROJECT

It moves to the generated directory.

#> cd MYPROJECT
#> ls -la
drwxr-xr-x  ... bin
-rw-r--r--  ... Build.PL
drwxr-xr-x  ... cache
-rw-r--r--  ... Changes
..
....

Trigger.cgi in bin is moved and it tests.

#> cd bin
#> ./trigger.cgi  or  perl trigger.cgi

# << MYPROJECT v0.01 start. --------------
# + request-path : /
..
....
......

If trigger.cgi doesn't output the error, the installation of the project is a success.

DESCRIPTION

Egg imitated and developed Catalyst.

It is WEB application framework of a simple composition.

The plugin is compatible with Catalyst. However, it is complete and not interchangeable. Some should be likely to be corrected.

In addition, please see the document of Egg::Release about detailed use.

Please see the document of Egg::Dispatch::Runmode about the notation of dispatch.

Egg::Release-1.00 reviewed at the time of beginning and rewrote the code. Therefore, the content has changed fairly with the version before. In the plugin etc. , the up-grade might be needed.

It is the main change point as follows.

  • Treatment of root by configuration.

    The route of the project was shown. * It was a route of the template before.

    And, the treatment and the name changed to some items.

    Please look at the chapter of CONFIGURATION in detail.

  • Exclusion of encode.

    All the encode method systems were excluded and it made it to the plugin.

    Please use Egg::Plugin::Encode.

  • Addition of standard plugin.

    DBI::*
Dispatch::AnyCall
Encode
FillInForm
FormValidator::Simple
Pod::HTML
Redirect::Page
Upload

    The above was added to a standard plugin.

  • Some Hook are excluded.

    $e->action and $e->compress were excluded.

    * The function of $e->action has changed.

  • Making of engine subclass.

    It is also easy to build in the engine of original development. How to treat MODEL and VIEW can be customized.

  • The treatment of the global variable severely

    The superscription of the key that has been defined is observed. However, it also has the loophole.

  • Change in dispatch.

    It was made to dispatch like CGI::Application. And, the function is enhanced by Tie::RefHash.

    Please see Egg::Dispatch::Runmode in detail.

  • The helper rewriting.

    The helper script moves like the framework. As a result, I think that it can easily make the supplementation functions of Model, View, and Plugin, etc.

    Egg::Helper::PerlModuleMaker is made a standard as Egg::Helper::O::MakeMaker.

  • VIEW corresponding to HTML::Mason was enclosed.

    HTML::Mason is a very high performance template engine.

    * Template ToolKit can be used by introducing Egg::View::TT.

OPTIONS

The start option is given to Egg and the plugin and the flag are set.

package MYPROJECT;
use strict;
use Egg qw{ -Debug Filter Upload };

* The one that - adheres to the head is treated as a flag. The set value can be referred to with $e->flag('FLAG_NAME').

use Egg qw{ -hoge };

if ($e->flag('hoge')) { "hoge flag is true." }

* The continuing name is treated when + has adhered to the head and package name of the plugin is treated.

use Egg qw{ +Catalyst::Plugin::FormValidator };

* It treats as a plugin of the package name modified by 'Egg::Plugin::' usually.

use Egg qw{ Filter::EUC_JP };

As for this, Egg::Plugin::Filter::EUC_JP is read.

CONFIGURATION

The setting can be treated by the YAML form in using the YAML plugin.

package MYPROJECT;
use strict;
use Egg qw{ YAML };

my $config= __PACKAGE__->yaml_load('/path/to/MYPROJECT/etc/MYPROJECT.yaml');
__PACKAGE__->__egg_setup( $config );

* The setting of the YAML form can be output by using the helper script.

#> /path/to/MYPROJECT/bin/yaml_generator.pl

root

Directory that becomes root of project.

* How to treat is different from the version before '1.00'.

Default is none. * Indispensability.

static

Directory that arranges static contents like image data etc.

Please specify it by the relative path from 'root' or the absolute path.

Default is 'htdocs'.

static_uri

URL passing when 'static' is seen with WEB. (Absolute path without fail)

Default is '/'.

title

Title name of project.

Default is '[MYPROJECT_NAME]'.

template_default_name

Name of template used in index.

* The extension is not included.

Default is 'index'.

template_extention

Extension of template.

Default is '.tt'.

accessor_names

To make the accessor to $e->stash, the name is enumerated by the ARRAY reference.

Default is 'template'.

character_in

Character code used by internal processing.

* When Egg::Plugin::Encode is used, it is necessary.

Default is 'euc'.

content_language

Contents languages.

Default is 'jp'.

content_type

Default of contents headers

Default is 'text/html'.

max_snip_deep

Maximum of depth of request URL PATH. * When this is exceeded, it is 403 FORBIDDEN is returned.

Default is '5'.

OK  => http://domain/A/B/C/D/E/
NG  => http://domain/A/B/C/D/E/F/

engine_class

When you want to use an original engine class.

Default is 'Egg::Engine::V1'.

request_class

When you want to use an original request class.

Default is 'Egg::Request::( CGI or Apache )'.

response_class

When you want to use an original response class.

Default is 'Egg::Response'.

dispatch_class

When you want to use original Dispatch.

Default is 'Egg::Dispatch::Runmode'.

MODEL

It sets it by the ARRAY reference concerning the MODEL.

* The first setting of ARRAY is treated most as a model of default.

Setting example:

MODEL=> [
  [ 'MODEL1_NAME' => {
      config_param1=> '...',
      config_param2=> '...',
      ...
      },
    ],
  [ 'MODEL2_NAME' => {
      config_param1=> '...',
      config_param2=> '...',
      ...
      },
    ],
  ],

VIEW

The setting made a VIEW is done by the ARRAY reference.

* The first setting of ARRAY is treated most as a model of default.

* The setting becomes the same form as MODEL.

plugin_[PLUGIN_NAME]

Setting read from plugin.

* The naming convention is not compelling it. According to circumstances, it might be a quite different name.

* Please see the document of the plugin used in detail.

METHODS

new

After the request and the response object are made, the Egg object is returned.

Nothing is done excluding this. This is convenient to operate with the trigger excluding WEB such as cron.

my $e= MYPROJECT->new;

# Some components might not function if prepare is not called.
$e->prepare_component;

... Freely now ...

__egg_setup ([CONFIGURATION])

Egg is set, and when starting, it sets it up.

Please call it from the control file of the project.

use MYPROJECT;
use MYPROJECT::Config;
__PACKAGE__->__egg_setup( MYPROJECT::Config->out );

__warning_setup ([CODE_REFERENCE])

The output format etc. of warn can be customized.

__PACKAGE__->__warning_setup;

namespace

The class name of the started project is returned.

snip ([NUM])

The value in which the request passing is delimited by / is returned by the ARRAY reference.

Request URL => http://domain/A/B/C/

print $e->snip->[0];  => A
print $e->snip->[1];  => B
print $e->snip->[2];  => C

The dead letter character is returned when a specified value is undefined when [NUM] is given.

$e->snip(1) eq 'B' ? 'OK': 'NG';

* Because it is not necessary to check a specified value whether is 11 undefinitions and exists, it is convenient.

stash

The value to share between components of Egg can be put.

$e->stash->{hoge}= 'foo';

dispatch or d

The dispatch object is returned.

When setting it up, the dispatch of specification is read.

* The dispatch used by 'Dispatch_class' of environment variable '[PROJECT_NAME]_DISPATCHER' or the setting can be specified. The class name is modified by 'Egg::Dispatch'.

* The dispatch used by environment variable '[PROJECT_NAME]_CUSTOM_DISPATCHER' can be specified. As for the class name, the specified name is used as it is.

* Dispatch to which require is not done by environment variable '[PROJECT_NAME]_UNLOAD_DISPATCHER' can be specified. As for the class name, the specified name is used as it is.

Default is 'Egg::Dispatch::Runmode'.

request or req

The request object is returned.

When setting it up, an appropriate request class has been decided.

An original class can be set in 'Request_class' of the setting or environment variable '[PROJECT_NAME]_REQUEST'.

package MYPROJECT;
...
$ENV{MYPROJECT_REQUEST}= 'ORIGN::CUSTOM::Request';

Default is 'Egg::Request::CGI'.

response or res

The response object is returned.

An original class can be set in 'Response_class' of the setting or environment variable '[PROJECT_NAME]_RESPONSE'.

Default is 'Egg::Response'.

dispatch

After the object is generated with Egg::Engine::* it, the Dipatti object is returned.

debug

The value of the debugging flag is returned. It is the same as $e->flag->('debug').

if ($e->debug) { 'debug mode !!' }

dispatch_class

The read dispatch class name is returned.

request_class

The read request class name is returned.

response_class

The read response class name is returned.

config

The setting is returned.

The content is a global value. It doesn't return to former value until the server is reactivated when the content is changed in mod_perl etc.

$e->config->{config_name};

global

The HASH reference where a global value is preserved is returned.

Because the I/O of this HASH is observed by Egg::GlobalHash, the overwrited thing cannot be done the key that already exists. However, it is only a key to one hierarchy that is observed. It is possible to input and output freely concerning the second key.

Moreover, the key is always a capital letter of the alphabet.

In addition, please see the document of Egg::GlobalHash in detail.

# It enters without trouble if FUU_VALUE is undefined.
$e->global->{FUU_VALUE}= 'boo';

# The error has already occurred in this because FUU_VALUE has defined it.
$e->global->{FUU_VALUE}= 'zuu';

flag ([FLAG_NAME])

The value of the flag given to the start option of Egg can be referred to.

* The key is sure to become an alphabetic small letter. Moreover, the value is not put.

head2 path ([CONFIG_KEY], [PATH])

Passing that combines a set value and the given passing is returned.

print $e->path(qw{ temp hoo/zuu });  => /path/to/MYPROJECT/tmp/hoo/zuu

action

Passing information on the place in the request place actually processed returns by the ARRAY reference.

* The value of this method expects the thing set by dispatch. When dispatch doesn't set the value, undef is returned.

For instance, each request starts in Egg::Dispatch::Runmode as follows.

* If it is .. run_modes( home=> { _default=> sub { ... } } )

http://domain/home/  => [ 'home', 'index' ]

The part of 'Index' is supplemented with the value of 'Template_default_name' of the setting.

* run_modes( home=> { qr/ABC\d+/=> sub { ... } } )

http://domain/home/ABC123/ => [ 'home', 'ABC123' ]

* Perhaps, this cannot specify the template.

plugins

The list of the name of the read plugin is returned.

plugin_class

The name of the read plug-in is returned and the key and the package name return HASH of the value.

BUGS

The error occurs when Class::Accessor::Fast is succeeded to by the plugin module. Measures against this are not made yet.

This can be evaded by the thing assumed the $e->mk_accessors(...) with setup.

However, it is not a complete solution because there might be a demand from another plug-in that was previously called. There is a hand that substitutes Class::Data::Inheritable to deal with this.

package MY_PLUGIN;
sub setup {
  my($e)= @_;
  $e->mk_accessors(...);
}

or

package MY_PLUGIN;
use base qw{ Class::Data::Inheritable };
__PACKAGE__->mk_classdata($_) for qw{ .... };

SEE ALSO

Egg::Release, Egg::Engine, Egg::Engine::V1, Egg::Model, Egg::View, Egg::Request, Egg::Response, Egg::Dispatch::Runmode, Egg::Exception,

AUTHOR

Masatoshi Mizuno, <lushe@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 Bee Flag, Corp. <http://egg.bomcity.com/>, All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.