view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    the browser, or to files, or you may even build your own medium
    backend. You may also define your own serializing options, although
    `Storable' is natively supported. See the
    CGI::MxScreen::Session::Medium manpage for the medium interface and
    the CGI::MxScreen::Serializer manpage for the serialization
    interface.

*   It handles the state machine for you. You define the various screen
    objects, and then specify, for each submit button, which state the
    application should go. The target state can be specified statically,
    or computed dynamically by the application. Action routines can be
    attached to the button, to run some processing during the state
    change. See the CGI::MxScreen::Form::Button manpage for more
    information.

*   It has an object-oriented design. Each screen is an object inheriting
    from `CGI::MxScreen::Screen' and redefining the `display' routine,
    at least. There are also `enter' and `leave' hooks for each screen.
    Each created screen object is made persistent accross the whole
    session. See the CGI::MxScreen::Screen manpage for the full
    interface.

*   Any script output done before the screen's `display' routine is called
    will be trapped and discarded (with logging showing the place where
    such a violation occurs). This architecturally enforces proper
    application behaviour. Furthermore, by default, the whole output is
    buffered until it is time to save the context, thereby protecting
    against further submits with a partially received form on the
    browser side, and also strengthening the protection when the
    application uses bounce exceptions to jump into another state.

*   Each CGI parameter (form control) can be given an explicit storage
    indication (i.e. how the application should dispose of the value), a
    validation routine, and an on-the-fly patching routines (to
    normalize values, for instance). Each parameter may also be given a
    mandatory status, causing an error when it is not filled. See the
    CGI::MxScreen::Form::Field manpage for more information.

*   There is a global hash that is made available to all screens and which
    is made persistent accross the whole session. By default, every key
    access to that hash is checked to prevent typos, and reading an
    unknown key is a fatal error (at run-time, unfortunately).

*   There are layout hooks allowing the generation of a common preamble and
    postamble section, common to a group of scripts. See the
    CGI::MxScreen::Layout manpage for details.

*   The framework can be configured by loading a configuration Perl script,
    allowing easy sharing of the settings among a set of scripts, with
    possible local superseding on a script basis. See the
    CGI::MxScreen::Config manpage for details.

*   All error logging is done via `Log::Agent', and application logging is
    done via `Log::Agent::Logger', which ensures the maximum
    flexibility. Logfile rotation is also supported via
    `Log::Agent::Rotate'. Configuration of the various logging
    parameters is done via the `CGI::MxScreen::Config' interface.

*   `CGI::MxScreen' uses `Carp::Datum' internally. If you have chosen to
    install a non-stripped version, you may trace parts of the module to
    better understand what is going on with the various callbacks you
    register.

Here is a high-level description of the processing flow when issuing
requests to a `CGI::MxScreen' script:

*   An initial log tracing the user (if HTTP authentication is used), the
    time since the session started, the elapsed time since the previous
    display, and the CGI query string is emitted.

*   The session context is retrieved if any, otherwise a new one is created.
    The context holds the various screen objects, the submit buttons and
    other form fields descriptions, plus all the other data stored
    within the persistent global hash.

*   Input parameters are processed, following the directives held within the
    session to validate and optionally store them in some place. If an
    error is detected, the application remains in the same state and the
    previous screen is redisplayed.

*   If no error occurred during parameter processing, the target state is
    computed based on the descriptions attached to the button that was
    pressed. The state can be given statically, or computed by a
    routine. The determined target state is composed of a screen object,
    plus some optional arguments that are to be given to its `display'
    routine. Any processing action attached to the button is also run at
    that point.

*   The transition is logged, tracing the pressed button, the previous state
    and the new one.

*   If a screen change occurs (i.e. the new screen to display is not the
    same as the previously displayed one), the `leave' routine is called
    on the old screen and `enter' is called on the new one.

*   The enclosing form setting is emitted, and the screen's `display'
    routine is called to actually generate the form's content. Before
    they output anything, screens are allowed to request the bouncing to
    some other state, based on some local information (but if output
    buffering is configured, any spurious output from the old screen
    will be cleanly discarded). Any other exception that can occur
    during `display' is trapped and cleanly logged, before displaying an
    internal error message.

*   The application context is saved, the form is closed, and buffered
    output is emitted. A final log tracing the total time spent is
    emitted.

CGI::MxScreen's foundation were greatly inspired by Tom Christiansen's
MxScreen program.  We would like to deeply thank Tom for having released
his code in the first place.  We believe we have improved what Tom had
informally expressed, both in terms of functionality and in terms of
reusability, but that's what open-source is about.  Learn, and then give
back.

We're happy to give back that framework to the Perl community.

-- Raphael Manfredi && Christophe Dehaudt