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

NAME

Egg - MVC Framework.

DESCRIPTION

Egg is WEB application framework with the control facilit of Model/View/Controller.

The specification changed with v2.x system and a former version. Therefore, interchangeability is not secured.

HELPER

The helper script is first generated to use Egg, and the project file complete set is generated with the script.

And, the application is constructed with the change of the setting of the project and the addition of the module.

Generation of helper script.

% perl -MEgg::Helper -e 'Egg::Helper->helper_script' > egg_helper.pl

When Egg::Helper is as mentioned above started, the helper script is generated to the current directory.

It is convenient for the generated script to copy onto the place that manages easily and to set the execution attribute.

% cp ./egg_helper.pl /usr/bin
% chmod 755 /usr/bin/egg_helper.pl

Making of project.

% egg_helper.pl project MyApp

It becomes a project name that the part of MyApp newly generates.

However, please do not include ':' in the name by the form that is sure to be permitted as a module name of perl.

Please specify passing putting '-o' option when you want to specify the output destination.

% egg_helper.pl project MyApp -o/path/to

It generates it to the current directory at the unspecification.

Moreover, when the same directory as the project name already exists at the output destination, generation is discontinued.

Confirmation such as generation files.

I think the project to have been made in the directory of/path/to/MyApp in this example. Please confirm the generation file.

% cd /path/to/MyApp
% ls -la
drwxr-xr-x  *** .
drwxr-xr-x  *** ..
drwxr-xr-x  *** bin
-rw-r--r--  *** Build.PL
drwxr-xr-x  *** cache
-rw-r--r--  *** Changes
drwxr-xr-x  *** comp
drwxr-xr-x  *** etc
drwxr-xr-x  *** htdocs
drwxr-xr-x  *** lib
-rw-r--r--  *** Makefile.PL
-rw-r--r--  *** MANIFEST
-rw-r--r--  *** MANIFEST.SKIP
-rw-r--r--  *** README
drwxr-xr-x  *** root
drwxr-xr-x  *** t
drwxr-xr-x  *** tmp

It deletes if it is unnecessary and it doesn't care though Build.PL, Changes, Makefile.PL, MANIFEST, MANIFEST.SKIP, README, and t are files among these needed when the project file complete set is assumed to be perl module and the packaging is done.

  • bin

    There is a script that seems to be necessary to treat the project it.

  • cache

    For accumulation of cash data. The authority is set when using it.

  • comp

    It is a directory that assumes the common part of the template is arranged.

  • etc

    It is a configuration file and others, and a place to use it multipurpose.

  • htdocs

    It is a place where static contents are set up. It is good to make here 'DocumentRoot' of the WEB server.

  • lib

    It becomes a library passing for the project project that includes the controller, the configuration, and the dispatch, etc. of the project beforehand.

  • root

    It is a place to arrange the template. There is index.tt of the sample.

  • tmp

    Please use it temporarily as a place where the work file is put.

Confirming the operation of project.

Please confirm whether to operate normally first of all in the state of default when the project is generable.

% cd bin
% ./trigger.cgi

'trigger.cgi' is a script when operating as usual CGI.

I think that default operates normally if this script outputs the HTML source.

Egg demonstrates the highest performance of origins such as mod_perl and FastCGI. A practicable performance is not obtained by usual CGI.

Please use 'trigger.cgi' when using it from Apache::Registry and Apache::PerlRun.

'dispatch.fcgi' is used when using it with FastCGI.

Moreover, it is necessary to set 'mod_rewrite'. It explains in detail at the following.

Construction of application.

The method of constructing the application makes it omit in this document. It takes up and it explains an easy example in Egg::Release.

It explains the role etc. of the system configuration and 'Egg.pm' of Egg in this document.

SYSTEM

The main of the system of Egg is a project module. The file is /path/to/MyApp/lib/MyApp.pm.

In a word, it becomes a controller to whom this file sets loading the configuration and the plugin etc.

Egg is started from this controller. And, the configuration is taken by initial operation. Afterwards, it registers in @ISA of the project after the plug-in is loaded one by one, and it registers in end @ISA.

As a result, it comes to be able to call the method of all modules by way of the object of the project at what time. Moreover, the plug-in module can add original processing picking up the hook that Egg calls at what time.

The model and the view are registered with this @ISA Cdacdacata. And, those modules are treated with more peculiar @ISA Cdacdacata to the handler object of the model and the view though the model and the view can treat two or more modules at the same time.

It is a system that treats the object that masses by the @ISA base like this and outputs contents.

METHOD CALL

Egg does the following calls and outputs contents.

  • _setup

    It is a call only when starting being called from 'import' of Egg.

  • _prepare

    It is a call for the preparation starting processing. Any Egg is not done.

  • _dispatch

    If $e->finished has defined it, nothing has already been done though whether $e->dispatch->_start is done and what action you do are decided.

  • _action_start

    If $e->finished or $e->response->body has defined it, nothing has already been done though $e->dispatch->_action is done and the decided action is processed.

  • _action_end

    If $e->finished has defined it, nothing has already been done though the processing of dispatch is completed by $e->dispatch->_finish.

  • _finalize

    It is a call for the processing end. Any Egg is not done.

  • _output

    Contents are output.

  • _finish

    It is a call to complete all processing. Any Egg is not done.

  • _finalize_error

    When some errors occur, 'finish' is called. The content of the error can be acquired in 'errstr' method.

  • _result

    It is a call to return the return value of run. Even whenever the exception is generated, it is called. Please confirm whether $e->is_exception is confirmed and the exception was generated when you process the hook by this.

* Egg doesn't define $e->finished. Please note that $e->finished always returns undefined as long as not defined on the application side etc.

METHODS

This module is Egg::Util, Egg::Component, Egg::Base. It succeeds to.

new

Constructor. This is usually called from the 'handler' method.

use MyApp;
my $e= MyApp->new;

handler

It is a handler for processing to the WEB request to begin.

Egg is generated an appropriate handler by the composition at that time and stands by.

This method succeeds processing to the 'run' method. A series of processing concerning the request is done by this.

use MyApp;
MyApp->handler;

run

This method is usually called from the handler method and does a series of processing to the request.

egg_startup ([CONFIGURATION])

To start the project, it sets it up.

finished ([HTTP_RESPONSE_STATYS])

When processing is ended, it sets it.

When finished returns true, Egg cancels some processing.

The argument is sent to $e->response->status as it is. In a word, the HTTP response status is given when setting it. see Egg::Response.

'0' However, when Azca is gotten, it is initialized with $e->response->status.

# Forbidden is returned and it ends.
$e->finished(403);

# finished A is canceled.
$e->finished(0);

Please note that Egg doesn't set 'finished'.

dispatch

If 'dispatch' is called when the 'dispatch' method is not built into the project, the exception is generated.

see Egg::Dispatch::Standard, Egg::Dispatch::Fast

project_name

The project name returns.

This method is an alias to the method of 'namespace' of Egg::Component.

is_exception

When the exception is generated, true is restored.

request

The object of Egg::Request is returned.

my $req= $e->request;

Alias: req

see Egg::Request,

response

The object of Egg::Response is returned.

my $res= $e->response;

Alias: res

see Egg::Response

model_manager

Egg::Manager::Model is returned.

view_manager

Egg::Manager::View is returned.

debug_out ([MESSAGE_STRING])

The debugging message is output while operating by debug mode. It is $e->log->notes to actually output.

It is replaced with the method of not doing anything when debug mode is invalid.

bench ([LABEL_STRING])

It is a method for the bench mark.

It is replaced with the method of not doing anything when debug mode is invalid.

see Egg::Util::BenchMark.

PLUGIN

The module name when the plugin of Egg is loaded only has to specify only the part of Egg::Plugin::PLUGIN_NAME in PLUGIN_NAME.

# This specified Egg::Plugin::PluginAny.
use Egg qw/ PluginAny /;

It specifies it by the full name putting '+' on the head to load an original plugin.

use Egg qw/
  .......
  +Hoge::Plugin
  /;

About the method of making the plugin.

'use strict' is applied applying the package name to the plugin without fail.

package Egg::Plugin::Any;
use strict;

Moreover, without forgetting $VERSION

our $VERSION = '0.01';

This $VERSION must be referred to when you the plugin load debug mode.

Please add the code as liked now.

sub mymethod {
   my($e)= @_;
   .....
   .....  The code of the plug-in is written here.
   .....
   $e;
}

It comes to be able to call it with $e->mymethod when making it to such feeling.

However, it is already a thing that the method of the definition is not overwrited that wants you to note it.

If the plugin that puts interrupt on the call of the method of Egg is made, it is necessary to have it by using $e->next::method over the following.

sub _prepare {
   my($e)= @_;
   .....
   .....  The code of the plug-in is written here.
   .....
   $e->next::method;
}

The order of interrupt is done in order that the plugin is loaded. The plugin to want to interrupt at the end makes it loaded as much as possible at the end as much as possible.

If it wants to process the plugin produced with oneself from which plugin at the end, the thing written as follows can be done.

sub _prepare {
  my($e)= shift->next::method;
   .....
   .....  The code of the plugin is written here.
   .....
   $e;
}

However, I think that there is a thing that comes for the user not to use it easily thus.

Processing in which the default value etc. beforehand are defined putting interrupt on '_setup' is recommended. Every time, you can not check the configuration when putting it thus.

sub _setup {
   my($e)= @_;
   my $c= $e->config->{plugin_any} ||= {};
   $c->{hoge} ||= 'default1';
   $c->{foo}  ||= 'default2';
   $e->next::method;
}

Interrupt can be put on the call of all the methods of Egg by such feeling.

Plugin list of standard appending.

Recommendation module not included in standard.

WEB SERVER

It is necessary to move it under mod_perl and the FastCGI environment to obtain the best response speed in Egg.

To our regret, a practicable response speed is not obtained by usual CGI.

Apache::Registry or Apache::PerlRun

'trigger.cgi' that exists in the 'bin' directory of the project is moved to a suitable place and the execution attribute is given. And, mod_rewite is set by the following feeling.

RewriteEngine On
# RewriteLogLevel 5
# RewriteLog /var/log/httpd/rewrite.log
RewriteRule ^/trigger\.cgi  /  [R,L]
RewriteRule ^/([^\.]+)?([\?\#].*)?$  /trigger.cgi/$1$2  [L]

It is assumed to arrange 'trigger.cgi' in the document route. URI that doesn't contain the dot in this regular expression is treated as dynamic contents. When the dot is contained, everything is not matched to the pattern as static contents. Please change this regular expression when you want to change the evaluation.

The setting of Apache::Registry and Apache::PerlRun is omitted.

Apache Handler

The setting by the Apache handler has a set sample in the etc directory and refer to that, please.

% less etc/mod_perl2.conf.example

The sample is for 'mod_perl2'.

FastCGI

A set sample is in the etc directory and refer, please. The sample targeted lighttpd.

% less etc/lighttpd+fastcgi.conf.example

Please arrange 'dispatch.fcgi' that exists in the bin directory in a suitable place. It is a setting that assumes the document route in the sample.

And, the execution attribute is given.

Please add the setting of the sample to the setting of lighttpd when the above- mentioned work ends.

PersistentPerl (SpeedyCGI)

'speedy.cgi' of the 'bin' directory is moved to a suitable place and the execution attribute is given. And, 'mod_rewrite' like Apache::Registry is set. Please do not forget to set for CGI to operate by the WEB server.

DEBUG

It operates by debug mode in setting the Debug flag when Egg is loaded.

use Egg qw/
 -Debug
 /;

Moreover, it is possible to use it even by other usages because it is treated as a flag when '-' is applied to the head regardless of the flag for debugging.

When the flag is invalidated, it is not necessary to delete it. If another '-' is added, the flag becomes undefined.

use Egg qw/
 --Debug
 /;

Improvement of development efficiency.

If the change in the module basically loaded doesn't reactivate the WEB server, Egg is not reflected.

Moreover, the WEB server for development is not included. Therefore, it will do to the development of the application by the thing moved on WEB servers such as 'Apache' or 'lighttpd'.

However, if Egg doesn't reactivate the WEB server at the change in the module, the change is not reflected. With this, because the development efficiency is very bad, I think that the following devices are indispensable.

When PersistentPerl is used, the introduction of Module::Refresh is very effective. 'speedy.cgi' is changed as follows when using it.

#!/usr/bin/perperl
use Module::Refresh;
use MyApp;
Module::Refresh->refresh();
MyApp->handler;

The change in the module comes to be reflected by this immediately.

However, neither the dynamic function definition that 'Import' and '_setup' method do nor the change of a set value are reflected. It seem not to be about the one related to these symbol tables though it does very. Please do 'speedy.cgi' in touch in such a case.

% touch /path/to/MyApp/htdocs/speedy.cgi

Module::Refresh seems not to work well in FastCGI. Please try Egg::Plugin::Debug::Bar when you use FastCGI.

SEE ALSO

Egg::Release, Egg::Request, Egg::Response, Egg::Manager::Model, Egg::Manager::View, Egg::Component, Egg::Util, Egg::Util::Debug, Egg::Util::DebugScreen, Egg::Log::STDERR, Egg::Exception

AUTHOR

Masatoshi Mizuno <lushe@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 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.