NAME

       Lemonldap::NG::Common::PSGI - Base library for PSGI modules of Lemonldap::NG.  Use
       Lemonldap::NG::Common::PSGI::Router for REST API.

SYNOPSIS

         package My::PSGI;

         use base Lemonldap::NG::Common::PSGI;

         sub init {
           my ($self,$args) = @_;
           # Will be called 1 time during startup

           # Store debug level
           $self->logLevel('info');
           # Can use syslog for user actions
           $self->syslog('daemon');

           # Return a boolean. If false, then error message has to be stored in
           # $self->error
           return 1;
         }

         sub handler {
           my ( $self, $req ) = @_;
           # Do something and return a PSGI response
           # NB: $req is a Lemonldap::NG::Common::PSGI::Request object

           return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Body lines' ] ];
         }

       This package could then be called as a CGI, using FastCGI,...

         #!/usr/bin/env perl

         use My::PSGI;
         use Plack::Handler::FCGI; # or Plack::Handler::CGI

         Plack::Handler::FCGI->new->run( My::PSGI->run() );

DESCRIPTION

       This package provides base class for Lemonldap::NG web interfaces but could be used
       regardless.

METHODS

   Running methods
       run ( $args )

       Main method that will manage requests. It can be called using class or already created
       object:

       Class->run($args):
           launch new($args), init(), then manage requests (using private _run() method

       $object->run():
           manage directly requests. Initialization must have be done earlier.

   Logging
       lmLog ( $msg, $level)

       Print on STDERR messages if level > $self->{logLevel}. Defined log levels are: debug,
       info, notice, warn, error.

       userLog ($msg, $level)

       If $self->syslog is configured, store message with it, else called simply lmLog().
       $self->syslog must be empty or contain syslog facility

       userError() userNotice() userInfo()

       Alias for userLog(level).

   Content sending
       Note that $req, the first argument of these functions, is a
       Lemonldap::NG::Common::PSGI::Request. See the corresponding documentation.

       sendHtml ( $req, $template )

       This method build HTML response using HTML::Template and the template $template.
       $template file must be in $self->templateDir directory.  HTML template will receive 5
       variables:

       SCRIPT_NAME: the path to the (F)CGI
       STATIC_PREFIX: content of $self->staticPrefix
       AVAILABLE_LANGUAGES: content of $self->languages
       LINKS: JSON stringification of $self->links
       VERSION: Lemonldap::NG version

       The response is always send with a 200 code.

       sendJSONresponse ( $req, $json, %args )

       Stringify $json object and send it to the client. $req is the
       Lemonldap::NG::Common::PSGI::Request object; %args can define the HTTP error code (200 by
       default) or headers to add.

       If client is not json compatible (`Accept` header), response is send in XML.

       Examples:

         $self->sendJSONresponse ( $req, { result => 0 }, code => 400 );

         $self->sendJSONresponse ( $req, { result => 1 } );

         $self->sendJSONresponse ( $req, { result => 1 }, headers => [ X => Z ] );

       sendError ( $req, $msg, $code )

       Call sendJSONresponse with `{ error => $msg }` and code (default to 500) and call lmLog()
       to duplicate error in logs

       abort ( $msg )

       When an error is detected during startup (init() sub), you must not call sendError() but
       call abort(). Each request received later will receive the error (abort uses sendError()
       behind the scene).

   Accessors
       error

       String error. Used if init() fails or if sendError is called without argument.

       languages

       String containing list of languages (ie "fr, en'). Used by sendHtml().

       logLevel

       See lmLog().

       staticPrefix

       String indicating the path of static content (js, css,...). Used by sendHtml().

       templateDir

       Directory containing template files.

       links

       Array of links to display by sendHtml(). Each element has the form:

        { target => 'http://target', title => 'string to display' }

       syslog

       Syslog facility. If empty, STDERR will be used for logging

SEE ALSO

       <http://lemonldap-ng.org/>, Lemonldap::NG::Portal, Lemonldap::NG::Handler, Plack, PSGI,
       Lemonldap::NG::Common::PSGI::Router, Lemonldap::NG::Common::PSGI::Request, HTML::Template,

AUTHORS

       Clement Oudot, <clem.oudot@gmail.com>
       François-Xavier Deltombe, <fxdeltombe@gmail.com.>
       Xavier Guimard, <x.guimard@free.fr>
       Thomas Chemineau, <thomas.chemineau@gmail.com>

BUG REPORT

       Use OW2 system to report bug or ask for features:
       <https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues>

DOWNLOAD

       Lemonldap::NG is available at
       <http://forge.objectweb.org/project/showfiles.php?group_id=274>

COPYRIGHT AND LICENSE

       Copyright (C) 2015-2016 by Xavier Guimard, <x.guimard@free.fr>
       Copyright (C) 2015-2016 by Clément Oudot, <clem.oudot@gmail.com>

       This library is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program.
       If not, see <http://www.gnu.org/licenses/>.