NAME

       Mason::Component - Mason Component base class

DESCRIPTION

       Every Mason component corresponds to a unique class that inherits, directly or indirectly,
       from this base class.

       A new instance of the component class is created whenever a component is called - whether
       via a top level request, "<& &>" tags, or an << $m->comp >> call. A component instance is
       only valid for the Mason request in which it was created.

       We leave this class as devoid of built-in methods as possible, allowing you to create
       methods in your own components without worrying about name clashes.

STRUCTURAL METHODS

       This is the standard call chain for the page component (the initial component of a
       request).

           handle -> render -> wrap -> main

       In many cases only "main" will actually do anything.

       handle
           This is the top-most method called on the page component. Its job is to decide how to
           handle the request, e.g.

           •   throw an error (e.g. permission denied)

           •   take some action and redirect (e.g. if handling a form in a web environment)

           •   defer to another component via "$m->go"

           •   render the page

           It should not output any content itself. By default, it simply calls render.

       render
           This method is invoked from handle on the page component. Its job is to output the
           full content of the page. By default, it simply calls wrap.

       wrap
           This method is invoked from render on the page component.  By convention, "wrap" is an
           augmented method, with each superclass calling the next subclass.  This is useful for
           cascading templates in which the top-most superclass generates the surrounding
           content.

               <%augment wrap>
                 <h3>Subtitle section</h3>
                 <div class="main">
                   <% inner() %>
                 </div>
               </%augment>

           By default, "wrap" simply calls "inner()" to go to the next subclass, and then main at
           the bottom subclass.

           To override a component's parent wrapper, a component can define its own "wrap" using
           "method" instead of "augment":

               <%method wrap>
                 <h3>Parent wrapper will be ignored</h3>
                 <% inner() %>
               </%method>

           To do no wrapping at all, call the component class method "no_wrap":

               <%class>
               CLASS->no_wrap;
               </%class>

       main
           This method is invoked when a non-page component is called, and from the default wrap
           method as well. It consists of the code and output in the main part of the component
           that is not inside a "<%method>" or "<%class>" tag.

CLASS METHODS

       no_wrap
           A convenience method that redefines render to call main instead of wrap, thus skipping
           any content wrapper inherited from parent.

               <%class>
               CLASS->no_wrap;
               </%class>

       allow_path_info
           This method is called when the request path has a path_info portion, to determine
           whether the path_info is allowed. Default is false. See
           Mason::Manual::RequestDispatch.

               <%class>
               method allow_path_info { 1 }
               </%class>

OTHER METHODS

       args
           Returns the hashref of arguments passed to this component's constructor, e.g.  the
           arguments passed in a component call.

       cmeta
           Returns the Mason::Component::ClassMeta object associated with this component class,
           containing information such as the component's path and source file.

               my $path = $self->cmeta->path;

       m   Returns the current request. This is also available via $m inside Mason components.

SEE ALSO

       Mason

AUTHOR

       Jonathan Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by Jonathan Swartz.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.