O'Reilly logo

Embedding Perl in HTML with Mason by Ken Williams, Dave Rolsky

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Component Object API

Objects that you will deal with in this class actually fall into three categories. The majority will be objects of the HTML::Mason::Component::FileBased class, which is used for components generated from component source files. The next most common will be HTML::Mason::Component::Subcomponent objects, which represent subcomponents and methods. Finally, anonymous components created via the HTML::Mason::Interp->make_component( ) method (covered in Chapter 5 and Chapter 6) will simply be of the HTML::Mason::Component class.

For the most part, these objects all share the same interface.

Component objects are returned from a number of Request object methods as well as the interpreter object’s make_component( ) method.

These first methods are the ones you most likely want to use:

attr(name)

Looks for the specified attribute in the component and its parents, returning the first value found. If the attribute is not found, this method throws an exception. Attributes are declared in <%attr> blocks, as covered in “<%flags> and <%attr> blocks” in Chapter 2.

attr_if_exists(name)

Works just like the attr( ) method except that it simply returns undef if the specified attribute does not exist.

Of course, this makes it impossible to distinguish between an attribute with undef as its value and an attribute that is not found. To make that distinction, use the attr( ) method and wrap it in an eval {} block, or use this method in conjunction with the attr_exists( ) method.

attr_exists(name)

Returns true if the specified attribute exists in the component or its parents.

call_method(name, arguments)

Calls the specified method with the given arguments. If the method is not present in the component or any of its parents, an exception is thrown.

scall_method(name, arguments)

This is analogous to the scomp( ) method for the Request object. This method calls the named method with the given arguments and returns the output as a string. If the method is not present in the component or any of its parents, an exception is thrown.

method_exists(name)

Returns true if the specified method exists in the component or its parents.

Much of the component API is interesting only for introspection, though we’re sure creative developers can think of ways to work strange magic with this API.

comp_id

Returns a unique ID for this component. This ID may be in the form of a component path, though this is not guaranteed.

load_time

Returns the Unix epoch time when this object was created.

declared_args

Returns a hash reference containing an entry for each argument declared in the component’s <%args> section. These keys include the variable prefix, so they are strings like $foo or %bar. Each key’s value is itself a hash reference, which contains a single key, default, the value of which is the string given as the argument’s default value, or undef if no default was given.

For example, the following <%args> section:

<%args>
 $foo
 @bar => (1, 2, 3)
 %baz => ( ) # an empty hash
 $undefined => undef
</%args>

would cause the following to be returned from the declared_args( ) method:

{
 '$foo' => { default => undef },
 '@bar' => { default => ' (1, 2, 3)' },
 '%baz' => { default => ' ( ) # an empty hash' },
 '$undefined' => { default => ' undef' }
}

Note the difference between an argument with no default value and an argument with a default value of undef. Also, as you can see, the default value for each argument is returned as a string, not a data structure. This is because Mason does not actually parse these values as Perl does, but rather simply drops them into the code it generates in one piece.

dir_path

Returns the component’s notion of the current directory, relative to the component root. For file-based components, this is the full component path minus the filename. For subcomponents and methods, this will be the same as its parent component. For anonymous components, this will be undef.

This path is like a URL path and always uses forward slashes (/) as separators.

To get the filesystem path and filename for file-based components, see the source_dir( ) and source_file( ) methods.

flag(name)

Returns the value of the specified flag. Flags are declared in <%flags> blocks, as covered in “<%flags> and <%attr> blocks” in Chapter 2.

is_subcomp

Returns true if the specified component is a subcomponent or a method.

is_file_based

Returns true if the given component is file-based.

name

Returns the name of the component. For file-based components, this is the component filename without any path information. For subcomponents and methods, it is the name given in the <%def> or <%method> tag. For anonymous components, this method returns the same value as comp_id( ).

owner

For subcomponents and methods, returns the component in which the component was defined.

parent

Returns the parent component object, if one exists. The way a parent component is determined was discussed in Chapter 3.

path

Returns the component path for file-based components. This path starts from the component root, not the filesystem root. In other words, this is an absolute path that could be used to call this component from another component. For a subcomponent object, this returns a string containing its parent object’s path and its own name, separated by a c olon (:).

As with dir_path( ), the path returned here is a URL-style path and uses the forward slash (/) as its separator.

subcomps

With no arguments, returns a hash reference containing all the subcomponents defined in the component. The keys of this hash reference are component names, while the values are the component objects themselves.

If an argument is given, it returns the subcomponent of that particular name, or undef if there is no such subcomponent.

methods

Operates exactly like the subcomps( ) method but for methods instead of subcomponents.

title

Returns a printable string identifying this component. It is intended to uniquely identify a component within a given interpreter although this is not 100% guaranteed.

For file-based components, this is the component’s path. If you have multiple component roots, this path will also be supplemented by a string indicating which component root the component was found in.

For subcomponents, this is its owner’s title plus its own name, as returned by the name( ) method.

For anonymous components, this is the same as comp_id( ).

Methods for File-based Components

A few additional methods are available only for file-based components.

source_file

Returns the full absolute path to the file that contains the original component source. This is given in the native dialect of the filesystem, so its directory separators will be / on Unix, : on Mac OS, and who knows what on VMS.

source_dir

Returns the full path to the source component’s directory on the filesystem. As with source_file( ), the path is given in the native dialect of the filesystem.

object_file

Returns the object filename for the component if the component is file-based, otherwise undef.

The object file is the file that contains the code Mason generates from the component’s source file.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required