view release on metacpan or  search on metacpan

lib/HTML/Mason/Devel.pod  view on Meta::CPAN

    <%once>
    my $dbh;      # declare but don't assign
    ...
    </%once>

    <%init>
    $dbh ||= DBI::connect ...
    ...
    </%init>

In addition, using C<$m> or C<$r> in this section will not work in a
preloaded component, because neither of those variable exist when a
component is preloaded.

=head2 <%shared>

As with C<< <%once> >>, lexical (C<my>) variables declared in this
section can be seen in all the rest of a component's code: the main
body, subcomponents, and methods.  However, unlike C<< <%once> >>, the
code runs once per request (whenever the component is used) and its
variables last only until the end of the request.

A C<< <%shared> >> section is useful for initializing variables needed in, say, the
main body and one more subcomponents or methods. See L<Object-Oriented
Techniques|"Object-Oriented Techniques"> for an example of usage.

It's important to realize that you do not have access to the C<%ARGS>
hash or variables created via an C<< <%args> >> block inside a shared
section.  However, you can access arguments via
L<$m-E<gt>request_args|HTML::Mason::Request/item_request_args>.

Additionally, you cannot call a components' own methods or
subcomponents from inside a C<< <%shared> >>, though you can call
other components.

Avoid using C<< <%shared> >> for side-effect code that needs to run at a
predictable time during page generation. You may assume only that
C<< <%shared> >> runs just before the first code that needs it and runs at
most once per request.

In the current implementation, the scope sharing is done with
closures, so variables will only be shared if they are visible at
compile-time in the other parts of the component.  In addition, you
can't rely on the specific destruction time of the shared variables,
because they may not be destroyed until the first time the C<<
<%shared> >> section executes in a future request.  C<< <%init> >>
offers a more predictable execution and destruction time.

Currently any component with a C<< <%shared> >> section incurs an
extra performance penalty, because Mason must recreate its
anonymous subroutines the first time each new request uses the
component.  The exact penalty varies between systems and for most
applications will be unnoticeable. However, one should avoid using
C<< <%shared> >> when patently unnecessary, e.g. when an C<< <%init> >>
would work just as well.

Do not attempt to C<return()> from a C<< <%shared> >> section; the
current compiler cannot properly handle it.

=head1 EMBEDDED COMPONENTS

=head2 <%def I<name>>

Each instance of this section creates a I<subcomponent> embedded
inside the current component. Inside you may place anything that a
regular component contains, with the exception of C<< <%def> >>, C<< <%method> >>,
C<< <%once> >>, and C<< <%shared> >> tags.

The I<name> consists of characters in the set C<[\w._-]>. To
call a subcomponent simply use its name in <& &> or C<< $m->comp >>. A
subcomponent can only be seen from the surrounding component.

If you define a subcomponent with the same name as a file-based
component in the current directory, the subcomponent takes
precedence. You would need to use an absolute path to call the
file-based component. To avoid this situation and for general clarity,
we recommend that you pick a unique way to name all of your
subcomponents that is unlikely to interfere with file-based
components. A commonly accepted practice is to start subcomponent
names with ".".

While inside a subcomponent, you may use absolute or relative paths to
call file-based components and also call any of your "sibling"
subcomponents.

The lexical scope of a subcomponent is separate from the main
component.  However a subcomponent can declare its own C<< <%args> >> section
and have relevant values passed in.  You can also use a C<< <%shared> >>
section to declare variables visible from both scopes.

In the following example, we create a ".link" subcomponent to produce a
standardized hyperlink:

    <%def .link>
    <a href="http://www.<% $site %>.com"><% $label %></a>

    <%args>
    $site
    $label=>ucfirst($site)
    </%args>
    </%def>

    Visit these sites:
    <ul>
     <li><& .link, site=>'yahoo' &></li>
     <li><& .link, site=>'cmp', label=>'CMP Media' &></li>
     <li><& .link, site=>'excite' &></li>
    </ul>

=head2 <%method I<name>>

Each instance of this section creates a I<method> embedded inside
the current component. Methods resemble subcomponents in terms of
naming, contents, and scope. However, while subcomponents can only be
seen from the parent component, methods are meant to be called from
other components.

There are two ways to call a method. First, via a path of the form
"comp:method":