More doc (#595)

lemonldap-ng-common/lemonldap-ng.ini

@@ -215,6 +215,11 @@ localStorageOptions={                             \
 ; Set to 0 to disable error on XSS attack detection
 ;checkXSS = 0
 
+; CUSTOM PLUGINS
+; If you want to add custom plugins, set list here (comma separated)
+; Read Lemonldap::NG::Portal::Main::Plugin(3pm) man page.
+;customPlugins = My::Package1, My::Package2
+
 [handler]
 
 ; Handler cache configuration

lemonldap-ng-portal/lib/Lemonldap/NG/Portal.pm

@@ -30,7 +30,7 @@ Use any of Plack launcher. Example:
   
   use Lemonldap::NG::Portal;
   
-  # This must be the last instruction ! See PSGI for more
+  # This must be the last instruction! See PSGI for more
   Lemonldap::NG::Portal->run($opts);
 
 =head1 DESCRIPTION
@@ -72,14 +72,11 @@ During configuration reload, every enabled components are loaded as plugins:
 init() is called for each plugin. If one plugin initialization fails (init()
 returns 0), the portal responds a 500 status code for each request.
 
-Plugins can declare unauthRoutes/authRoutes during this initialization (=
-/path/info). Methods declared in this way must be declared in the plugin class.
-They will be called this the $req argument: the HTTP request
-(L<Lemonldap::NG::Portal::Main::Request>).
+See L<Lemonldap::NG::Portal::Main::Plugin> to see how to write modules.
 
 =head2 Main route
 
-The "/" route is declared in L<Lemonldap::NG::Portal::Main::Init> it points to
+The "/" route is declared in L<Lemonldap::NG::Portal::Main::Init>. It points to
 different methods in L<Lemonldap::NG::Portal::Main::Run>. Theses methods choose
 methods to call in the process and call do().
 
@@ -110,7 +107,7 @@ Whole configuration is always available. It is stored in $self->conf. It must
 not be modified by anyone even during initialization or receiving request
 (during initialization, copy the value in the plugin namespace instead).
 
-All plugins can dial with the portal methods using $self->p whoch points to
+All plugins can dial with the portal methods using $self->p which points to
 portal main object. Some main methods are mapped to the plugin namespace:
 
 =over
@@ -121,10 +118,12 @@ portal main object. Some main methods are mapped to the plugin namespace:
 
 =back
 
-=head2 OTHER POD FILES
+=head1 SEE ALSO
 
 Most of the documentation is available on the website
-L<http://lemonldap-ng.org>.
+L<http://lemonldap-ng.org>
+
+=head2 OTHER POD FILES
 
 =over
 
@@ -140,10 +139,6 @@ L<http://lemonldap-ng.org>.
 
 =back
 
-=head1 SEE ALSO
-
-L<http://lemonldap-ng.org>
-
 =head1 AUTHORS
 
 =over

lemonldap-ng-portal/lib/Lemonldap/NG/Portal/Main/Plugin.pm

@@ -51,3 +51,171 @@ sub _addRoute {
 }
 
 1;
+__END__
+
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+Lemonldap::NG::Portal::Main::Plugin - Base class for
+L<Lemonldap::NG::Portal> modules I<(plugins, authentication modules,...)>.
+
+=head1 SYNOPSIS
+
+  package Lemonldap::NG::Portal::My::Plugin;
+  use Mouse;
+  extends 'Lemonldap::NG::Portal::Main::Plugin';
+  
+  use constant beforeAuth => 'verifyIP';
+  
+  sub init {
+      my ($self) = @_;
+      $self->addUnauthRoute( mypath => 'hello', [ 'GET', 'PUT' ] );
+      $self->addAuthRoute( mypath => 'wellcome', [ 'GET', 'PUT' ] );
+      return 1;
+  }
+  sub verifyIP {
+      my ($self, $req) = @_;
+      return PE_ERROR if($req->address !~ /^10/);
+      return PE_OK;
+  }
+  sub hello {
+      my ($self, $req) = @_;
+      ...
+      return $self->p->sendJSONresponse($req, { hello => 1 });
+  }
+  sub wellcome {
+      my ($self, $req) = @_;
+      ...
+      return $self->p->sendHtml($req, 'template', params => { WELLCOME => 1 });
+  }
+
+=head1 DESCRIPTION
+
+Lemonldap::NG::Portal::Main::Plugin provides many methods to write easily
+Lemonldap::NG addons.
+
+init() is called for each plugin. If one plugin initialization fails (init()
+returns 0), the portal responds a 500 status code for each request.
+
+=head1 Writing plugins
+
+Custom plugins can be inserted in portal by declaring them in
+C<lemonldap-ng.ini> file, section C<[portal]>, key C<customPlugins>:
+
+  [portal]
+  customPlugins = My::Plugin1, My::Plugin2
+
+Plugins must be valid packages well found in C<@INC>.
+
+=head2 Plugin entry points
+
+=head3 Entry point based on PATH_INFO
+
+Plugins can declare unauthRoutes/authRoutes during this initialization (=
+/path/info). Methods declared in this way must be declared in the plugin class.
+They will be called this the $req argument: the HTTP request
+(L<Lemonldap::NG::Portal::Main::Request>). These methods must return a valid
+L<PSGI> response. You can also use sendJSONresponse() or sendHtml() methods
+(see L<Lemonldap::NG::Common::PSGI>).
+
+Example:
+
+  sub init {
+      my ($self) = @_;
+      $self->addUnauthRoute( mypath => 'hello', [ 'GET', 'PUT' ] );
+      $self->addAuthRoute( mypath => 'wellcome', [ 'GET', 'PUT' ] );
+      return 1;
+  }
+  sub hello {
+      my ($self, $req) = @_;
+      ...
+      return $self->p->sendJSONresponse($req, { hello => 1 });
+  }
+  sub wellcome {
+      my ($self, $req) = @_;
+      ...
+      return $self->p->sendHtml($req, 'template', params => { WELLCOME => 1 });
+  }
+
+=head3 Entry point in auth process
+
+A plugin which wants to be inserted in authentication process has to declare
+constants containing the name of the method to run. The following entry points
+are available.
+
+=over
+
+=item C<beforeAuth>: method called before authentication process
+
+=item C<betweenAuthAndDatas>: method called after authentication and before
+setting C<sessionInfo> provisionning
+
+=item C<afterDatas>: method called after C<sessionInfo> provisionning
+I<(macros, groups,...)>
+
+=item C<forAuthUser>: method called for already authenticated users
+
+=item C<beforeLogout>: method called before logout
+
+=back
+
+B<Note>: methods inserted so must return a PE_* constant. See
+Lemonldap::NG::Portal::Main::Constants.
+
+=head1 SEE ALSO
+
+L<http://lemonldap-ng.org>
+
+=head2 OTHER POD FILES
+
+=over
+
+=item Writing an authentication module: L<Lemonldap::NG::Portal::Auth::Base>
+
+=item Writing an issuer module: L<Lemonldap::NG::Portal::Main::Issuer>
+
+=item Request object: L<Lemonldap::NG::Portal::Main::Request>
+
+=item Adding parameters in the manager: L<Lemonldap::NG::Manager::Build>
+
+=back
+
+=head1 AUTHORS
+
+=over
+
+=item LemonLDAP::NG team L<http://lemonldap-ng.org/team>
+
+=back
+
+=head1 BUG REPORT
+
+Use OW2 system to report bug or ask for features:
+L<http://jira.ow2.org>
+
+=head1 DOWNLOAD
+
+Lemonldap::NG is available at
+L<http://forge.objectweb.org/project/showfiles.php?group_id=274>
+
+=head1 COPYRIGHT AND LICENSE
+
+See COPYING file for details.
+
+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 L<http://www.gnu.org/licenses/>.
+
+=cut

lemonldap-ng-portal/lib/Lemonldap/NG/Portal/Main/Plugins.pm

@@ -76,9 +76,9 @@ sub enabledPlugins {
 
     # Check if custom plugins are required
     # TODO: change this name
-    if ( $self->conf->{plugins} ) {
-        $self->lmLog( 'Custom plugins: ' . $self->conf->{plugins}, 'debug' );
-        push @res, grep ( /\w/, split( /,\s*/, $self->conf->{plugins} ) );
+    if ( $self->conf->{customPlugins} ) {
+        $self->lmLog( 'Custom plugins: ' . $self->conf->{customPlugins}, 'debug' );
+        push @res, grep ( /\w/, split( /,\s*/, $self->conf->{customPlugins} ) );
     }
     return @res;
 }