Rose::HTML::Object(3) User Contributed Perl DocumentationRose::HTML::Object(3)



NAME
       Rose::HTML::Object - HTML object base class.

SYNOPSIS
         #
         # Generic HTML construction
         #

         $o = Rose::HTML::Object->new('p');
         $o->push_child('Hi');

         print $o->html; # <p>hi</p>

         $br = Rose::HTML::Object->new(element => 'br', is_self_closing => 1);

         print $br->html;  # <br>
         print $br->xhtml; # <br />

         $o->unshift_children($br, ' '); # add two children

         print $o->html; # <p><br> Hi</p>

         $b = Rose::HTML::Object->new('body', children => $o);

         print $b->html; # <body><p><br> Hi</p></body>

         foreach my $object ($b->descendants)
         {
           ...
         }

         $d = Rose::HTML::Object->new('div', class => 'x');

         $b->child(0)->parent($d); # re-parent: $o now belongs to $d

         print $b->html; # <body></body>
         print $d->html; # <div class="x"><p><br> Hi</p></div>

         #
         # Subclass to add strictures
         #

         package MyTag;

         use base 'Rose::HTML::Object';

         __PACKAGE__->add_valid_html_attrs
         (
           'foo',
           'bar',
           'baz',
           ...
         );

         __PACKAGE__->add_required_html_attrs(
         {
           foo => 5,  # with default value
           goo => '', # required implies valid
         });

         __PACKAGE__->add_boolean_html_attrs
         (
           'selected', # boolean implies valid
         );

         sub html_element  { 'mytag' }
         sub xhtml_element { 'mytag' }

         ...

         my $o = MyTag->new(bar => 'hello', selected => 1);

         # prints: bar="hello" foo="5" goo="" selected
         print $o->html_attrs_string;

         # prints: bar="hello" foo="5" goo="" selected="selected"
         print $o->xhtml_attrs_string;

         $o->html_attr(selected => 0);

         print "Has bar\n"  if($o->html_attr_exists('bar'));
         $o->delete_html_attr('bar');

         $o->is_self_closing(1);

         print $o->html_tag;  # <mytag foo="5" goo="">
         print $o->xhtml_tag; # <mytag foo="5" goo="" />
         ...

DESCRIPTION
       Rose::HTML::Object is the base class for HTML objects.  It defines the
       HTML element name, provides methods for specifying, manipulating, and
       validating HTML attributes, and can serialize itself as either HTML or
       XHTML.

       This class inherits from, and follows the conventions of, Rose::Object.
       See the Rose::Object documentation for more information.

HIERARCHY
       Each Rose::HTML::Object may have zero or more children, each of which
       is another Rose::HTML::Object (or Rose::HTML::Object-derived) object.
       The html produced for an object will include the HTML for all of its
       descendants.

VALIDATION
       Although several methods, data structures, and policies exist to aid
       the creation of valid HTML, they are in no way a replacement for real
       markup validation.

       This class and those that inherit from it try to support a superset of
       the elements and attributes specified in the HTML 4.01 and XHTML 1.x
       specifications.  As a result, these classes will tend to be more
       permissive than actual validation.  The support of these standards is
       not exhaustive, and will inevitably expand.  Also remember that there
       are several variant DTDs that make up XHTML 1.x.  By trying to support
       a superset of these standards, this class can't correctly enforce the
       rules of any individual standard.

       So I say again: these classes are not a replacement for real markup
       validation. Use an external validator.

       Going forward, the compatibility policy of these classes is that
       attribute specifications may be added in the future, but existing
       attribute specifications will never be removed (unless they originally
       existed in error, i.e., were never part of any HTML 4.01 or XHTML 1.x
       standard).

       This support policy is pragmatic rather than ideological.  There is
       enough default validation to catch most typos or other unintentional
       errors, but not so much that the entire class hierarchy is weighed down
       by language lawyering and bookkeeping.

       If the runtime overhead of validating every HTML attribute is deemed
       too onerous, it can be turned off on a per-object basis with the
       validate_html_attrs method.   Subclasses can set this attribute during
       object construction to make the effect class-wide.  (You will also want
       to look at the autoload_html_attr_methods class attribute.)

       There are also methods for adding and removing valid, required, and
       boolean HTML attributes for a class.

       Finally, all element and attribute names are case-sensitive and
       lowercase in order to comply with XHTML (and to be easy to type).

CLASS METHODS
       These class methods can be called with a class name or an object as the
       invocant.  Either way, remember that the data structures and attributes
       affected are part of the class as a whole, not any individual object.
       For example, adding a valid HTML attribute makes it valid for all
       objects of the class, including any objects that already exist.

       Many of the class methods manipulate "inheritable sets," "inherited
       sets," or "inherited hashes."  See the Rose::Class::MakeMethods::Set
       and Rose::Class::MakeMethods::Generic documentation for an explanation
       of these method types.

       The sets of valid and boolean HTML attributes are "inherited sets."
       The set of required HTML attributes is an "inheritable set."  The
       object_type_classes map is an "inherited hash."

       The inheritance behavior of these sets is noted here in order to
       facilitate subclassing.  But it is an implementation detail, not a part
       of the public API.  The requirements of the APIs themselves do not
       include any particular inheritance behavior.

       add_boolean_html_attr NAME
           Adds a value to the list of boolean HTML attributes for this class.
           Boolean HTML attributes appear without values in HTML tags, (e.g.,
           <dl compact>) or with fixed values in XHTML tags (e.g., <dl
           compact="compact">)

       add_boolean_html_attrs NAME1, NAME2, ...
           Adds one or more values to the list of boolean HTML attributes for
           this class. Boolean HTML attributes appear without values in HTML
           tags, (e.g., <dl compact>) or with fixed values in XHTML tags
           (e.g., <dl compact="compact">)

       add_object_type_classes [MAP]
           Add entries to the object_type_classes hash that maps object type
           strings to the names of the Rose::HTML::Object-derived classes.
           Example:

               My::HTML::Form->add_object_type_classes
               (
                 blockquote => 'My::HTML::Blockquote',
                 abbr       => 'My::HTML::Abbr',
                 ...
               );

       add_required_html_attr NAME [, DEFAULT]
           Adds a value to the list of required HTML attributes for this
           class. Required HTML attributes will always appear in the HTML tag,
           with or without a non-empty value. You can set the default value
           for a required HTML attribute using the required_html_attr_value
           method or by passing the DEFAULT parameter to this method.

       add_required_html_attrs NAME1, NAME2, ... | HASHREF
           Adds one or more values to the list of required HTML attributes for
           this class. Required HTML attributes will always appear in the HTML
           tag, with or without a non-empty value.  You can set the default
           value for a required HTML attribute using the
           required_html_attr_value method or by passing a reference to a hash
           containing name/default pairs.

       add_valid_html_attr NAME
           Adds a value to the list of valid HTML attributes for this class.
           If the object property "validate_html_attrs" is true, then only
           valid attributes can be added to an object of this class.

       add_valid_html_attrs NAME1, NAME2, ...
           Adds one or more values to the list of valid HTML attributes for
           this class. If the object property "validate_html_attrs" is true,
           then only valid attributes can be added to an object of this class.

       autoload_html_attr_methods [BOOL]
           Get or set the boolean flag that determines whether or not any
           valid HTML attribute can be used as a method call of the same name.
           The default is true, and the value is inherited by subclasses
           unless overridden.

           In the case of a name conflict, the existing method is called and a
           new method is not auto-created for the HTML attribute of the same
           name.

           Examples:

               MyTag->add_valid_html_attrs('foo', 'bar', 'error');

               $o = MyTag->new;

               # Auto-created method, equivalent to $o->html_attr(foo => 5)
               $o->foo(5);

               # Fatal error: invalid HTML attribute and not an existing method
               print $o->blah;

               MyTag->autoload_html_attr_methods(0); # stop autoloading

               # Fatal error: method does not exist and was never auto-created
               print $o->bar;

               # This still works: once the method is auto-created, it stays
               print $o->foo; # prints "5"

               # Calls the existing error() object method; does not affect
               # the HTML attribute named "error"
               $o->error(99);

           Yes, the existence of this capability means that adding a method to
           a future version of a Rose::HTML::Object-derived class that has the
           same name as a valid HTML attribute may cause older code that calls
           the auto-created method of the same name to break.

           To avoid this, you can choose not to use any auto-created methods,
           opting instead to use the html_attr method everywhere (and you can
           set "autoload_html_attr_methods" to false to make sure that you
           don't accidentally use such a method).

       boolean_html_attrs
           Returns a reference to a sorted list of boolean HTML attributes in
           scalar context, or a sorted list of boolean HTML attributes in list
           context. The default set of boolean HTML attributes is empty.

           See the introduction to the "CLASS METHODS" section for more
           information about the "inherited set" implementation used by the
           set of boolean HTML attributes.

       default_html_attr_value NAME [, VALUE]
           Returns the default value for the HTML attribute NAME.

           If passed both an attribute NAME and a VALUE, it adds NAME to the
           set of required HTML attributes and sets its default value to
           VALUE.

       default_locale [LOCALE]
           Get or set the default locale for this class.  The default value
           "en".

       default_localizer [LOCALIZER]
           Get or set the default
           Rose::HTML::Object::Message::Localizer-derived localizer object.
           Defaults to a new Rose::HTML::Object::Message::Localizer-derived
           object.

       delete_boolean_html_attr NAME
           Removes the HTML attribute NAME from the set of boolean HTML
           attributes.

       delete_object_type_class TYPE
           Delete the type/class mapping entry for the object type TYPE.

       delete_required_html_attr NAME
           Removes the HTML attribute NAME from the set of required HTML
           attributes.

       delete_valid_html_attr NAME
           Removes the HTML attribute NAME from the set of valid HTML
           attributes. The attribute is also removed from the set of required
           and boolean HTML attributes, if it existed in either set.

       html_attr_is_boolean NAME
           Returns a boolean value indicating whether or not the attribute
           NAME is a boolean HTML attribute.  A boolean attribute must also be
           a valid attribute.

       html_attr_is_required NAME
           Returns a boolean value indicating whether or not the attribute
           NAME is a required HTML attribute.  A required attribute must also
           be a valid attribute.

       html_attr_is_valid NAME
           Returns a boolean value indicating whether or not the attribute
           NAME is a valid HTML attribute.

       load_all_messages
           Ask the localizer to load_all_messages from this class.

       locale [LOCALE]
           This method may be called as a class method or an object method.

           When called as a class method and a LOCALE is passed, then the
           default_locale is set.  When called as an object method and a
           LOCALE is passed, then the locale of this object is set.

           If no locale is set for this class (when called as a class method)
           then the localizer's locale is returned, if it is set.  Otherwise,
           the default_locale is returned.

           If no locale is set for this object (when called as an object
           method), then the the first defined locale from the object's
           parent_group, parent_field, parent_form, or generic parent is
           returned.  If none of those locales are defined, then the
           localizer's locale is returned, if it is set.  Otherwise, the
           default_locale is returned.

       object_type_class TYPE [, CLASS]
           Given the object type string TYPE, return the name of the
           Rose::HTML::Object-derived class mapped to that name.  If a CLASS
           is passed, the object type TYPE is mapped to CLASS.

           This map of type names to classes is an inherited hash representing
           the union of the hashes of all superclasses, minus any keys that
           are explicitly deleted in the current class.

       object_type_classes [MAP]
           Get or set the hash that maps object type strings to the names of
           the Rose::HTML::Object-derived classes.

           If passed MAP (a list of type/class pairs or a reference to a hash
           of the same) then MAP replaces the current object type mapping.
           Returns a list of type/class pairs (in list context) or a reference
           to a hash of type/class mappings (in scalar context).

           This map of type names to classes is an inherited hash representing
           the union of the hashes of all superclasses, minus any keys that
           are explicitly deleted in the current class.

           The default mapping of type names to class names is:

             'image'              => Rose::HTML::Image
             'label'              => Rose::HTML::Label
             'link'               => Rose::HTML::Link
             'script'             => Rose::HTML::Script
             'literal text'       => Rose::HTML::Text

             'form'               => Rose::HTML::Form
             'repeatable form'    => Rose::HTML::Form::Repeatable

             'text'               => Rose::HTML::Form::Field::Text
             'scalar'             => Rose::HTML::Form::Field::Text
             'char'               => Rose::HTML::Form::Field::Text
             'character'          => Rose::HTML::Form::Field::Text
             'varchar'            => Rose::HTML::Form::Field::Text
             'string'             => Rose::HTML::Form::Field::Text

             'text area'          => Rose::HTML::Form::Field::TextArea
             'textarea'           => Rose::HTML::Form::Field::TextArea
             'blob'               => Rose::HTML::Form::Field::TextArea

             'option'             => Rose::HTML::Form::Field::Option
             'option group'       => Rose::HTML::Form::Field::OptionGroup

             'checkbox'           => Rose::HTML::Form::Field::Checkbox
             'check'              => Rose::HTML::Form::Field::Checkbox

             'radio button'       => Rose::HTML::Form::Field::RadioButton
             'radio'              => Rose::HTML::Form::Field::RadioButton

             'checkboxes'         => Rose::HTML::Form::Field::CheckboxGroup
             'checks'             => Rose::HTML::Form::Field::CheckboxGroup
             'checkbox group'     => Rose::HTML::Form::Field::CheckboxGroup
             'check group'        => Rose::HTML::Form::Field::CheckboxGroup

             'radio buttons'      => Rose::HTML::Form::Field::RadioButtonGroup
             'radios'             => Rose::HTML::Form::Field::RadioButtonGroup
             'radio button group' => Rose::HTML::Form::Field::RadioButtonGroup
             'radio group'        => Rose::HTML::Form::Field::RadioButtonGroup

             'pop-up menu'        => Rose::HTML::Form::Field::PopUpMenu
             'popup menu'         => Rose::HTML::Form::Field::PopUpMenu
             'menu'               => Rose::HTML::Form::Field::PopUpMenu

             'select box'         => Rose::HTML::Form::Field::SelectBox
             'selectbox'          => Rose::HTML::Form::Field::SelectBox
             'select'             => Rose::HTML::Form::Field::SelectBox

             'submit'             => Rose::HTML::Form::Field::Submit
             'submit button'      => Rose::HTML::Form::Field::Submit

             'reset'              => Rose::HTML::Form::Field::Reset
             'reset button'       => Rose::HTML::Form::Field::Reset

             'file'               => Rose::HTML::Form::Field::File
             'upload'             => Rose::HTML::Form::Field::File

             'password'           => Rose::HTML::Form::Field::Password

             'hidden'             => Rose::HTML::Form::Field::Hidden

             'num'                => Rose::HTML::Form::Field::Numeric
             'number'             => Rose::HTML::Form::Field::Numeric
             'numeric'            => Rose::HTML::Form::Field::Numeric

             'int'                => Rose::HTML::Form::Field::Integer
             'integer'            => Rose::HTML::Form::Field::Integer

             'email'              => Rose::HTML::Form::Field::Email

             'phone'              => Rose::HTML::Form::Field::PhoneNumber::US
             'phone us'           => Rose::HTML::Form::Field::PhoneNumber::US

             'phone us split' =>
               Rose::HTML::Form::Field::PhoneNumber::US::Split

             'set'  => Rose::HTML::Form::Field::Set

             'time' => Rose::HTML::Form::Field::Time

             'time split hms' =>
               Rose::HTML::Form::Field::Time::Split::HourMinuteSecond

             'time hours'       => Rose::HTML::Form::Field::Time::Hours
             'time minutes'     => Rose::HTML::Form::Field::Time::Minutes
             'time seconds'     => Rose::HTML::Form::Field::Time::Seconds

             'date'             => Rose::HTML::Form::Field::Date
             'datetime'         => Rose::HTML::Form::Field::DateTime

             'datetime range'   => Rose::HTML::Form::Field::DateTime::Range

             'datetime start'   => Rose::HTML::Form::Field::DateTime::StartDate
             'datetime end'     => Rose::HTML::Form::Field::DateTime::EndDate

             'datetime split mdy' =>
               Rose::HTML::Form::Field::DateTime::Split::MonthDayYear

             'datetime split mdyhms' =>
               Rose::HTML::Form::Field::DateTime::Split::MDYHMS

       required_html_attrs
           Returns a reference to a sorted list of required HTML attributes in
           scalar context, or a sorted list of required HTML attributes in
           list context. The default set of required HTML attributes is empty.

           Required HTML attributes are included in the strings generated by
           the html_attrs_string and xhtml_attrs_string methods, even if they
           have been deleted using the delete_html_attr method or one of its
           variants.  If a required HTML attribute does not have a default
           value, its value defaults to an empty string or, if the attribute
           is also boolean, the name of the attribute.

           See the introduction to the "CLASS METHODS" section for more
           information about the "inheritable set" implementation used by the
           set of boolean HTML attributes.

       required_html_attr_value ATTR [, VALUE]
           Get or set the default value of the required HTML attrbute ATTR.
           If both ATTR and VALUE are passed, the value is set.  The current
           value is returned.

       valid_html_attrs
           Returns a reference to a sorted list of valid HTML attributes in
           scalar context, or a sorted list of valid HTML attributes in list
           context.  The default set is:

               id
               class
               style
               title
               lang
               xml:lang
               dir
               onclick
               ondblclick
               onmousedown
               onmouseup
               onmouseover
               onmousemove
               onmouseout
               onkeypress
               onkeydown
               onkeyup

           See the "VALIDATION" section for more on the philosophy and policy
           of validation.  See the introduction to the "CLASS METHODS" section
           for more information about the "inherited set" implementation used
           by the set of valid HTML attributes.

       xhtml_element [NAME]
           Get or set the name of the XHTML element.  The XHTML element is the
           name of the tag, e.g. "img", "p", "a", "select", "textarea", etc.

           This attribute may be read-only in subclasses, but is read/write
           here for increased flexibility.  The value is inherited by
           subclasses.

CONSTRUCTOR
       new [ PARAMS | ELEMENT, PARAMS ]
           Constructs a new Rose::HTML::Object object.  If an odd number of
           arguments is passed, the first argument is taken as the value for
           the element parameter.  Otherwise an even number of PARAMS
           name/value pairs are expected.  Any object method is a valid
           parameter name.

OBJECT METHODS
       add_child OBJECT
           This is an alias for the push_child method.

       add_children OBJECTS
           This is an alias for the push_children method.

       child INT
           Returns the child at the index specified by INT.  The first child
           is at index zero (0).

       children [LIST]
           Get or set the list of Rose::HTML::Object-derived objects that are
           contained within, or otherwise "children of" this object.  Any
           plain scalar in LIST is converted to a Rose::HTML::Text object,
           with the scalar used as the value of the text attribute.

           Returns a list (in list context) or a reference to an array (in
           scalar context) of Rose::HTML::Object-derived objects.  The array
           reference return value should be treated as read-only.  The
           individual items may be treated as read/write provided that you
           understand that you're modifying the actual children, not copies.

       clear_all_html_attrs
           Clears all the HTML attributes by settings their values to undef.

       clear_html_attr NAME
           Clears the HTML attribute NAME by settings its value to undef.

       clear_html_attrs NAME1, NAME2, ...
           Clears the HTML attributes specified by NAME1, NAME2, etc. by
           settings their values to undef.

       delete_all_html_attrs
           Deletes all the HTML attributes.

       delete_child [ INDEX | OBJECT ]
           Delete the child at INDEX (starting from zero) or the exact child
           OBJECT.

       delete_children
           Deletes all children.

       delete_html_attr NAME
           Deletes the HTML attribute NAME.

       delete_html_attrs NAME1, NAME2, ...
           Deletes the HTML attributes specified by NAME1, NAME2, etc.

       descendants
           Returns a list of the children of this object, plus all their
           children, and so on.

       element [NAME]
           If passed a NAME, sets both html_element and xhtml_element to NAME.
           Returns html_element.

       error [TEXT]
           Get or set an error string.

       error_id [ID [, ARGS]]
           Get or set an integer error id.  When setting the error id, an
           optional ARGS hash reference should be passed if the localized text
           for the corresponding message contains any placeholders.  Example:

             # Set error id, passing args for the label and value placeholders
             $obj->error_id(NUM_ABOVE_MAX, { label => $l, => value => $v });

       escape_html [BOOL]
           This flag may be used by other methods to decide whether or not to
           escape HTML.  It is set to true by default.  The only method in
           Rose::HTML::Object that references it is html_error.  All other
           HTML is escaped as appropriate regardless of the escape_html
           setting (e.g. the text returned by "html_attrs_string" always has
           its attribute values escaped).  Subclasses may consult this flag
           for similar purposes (which they must document, of course).

       has_child OBJECT
           Returns true if OBJECT is a child of this object, false otherwise.

       has_children
           Returns true if there are any children, false otherwise.

       has_parent
           Returns true if this object is the child of another object, false
           otherwise.

       has_error
           Returns true if an error is set, false otherwise.

       html
           A synonym for the html_tag method.

       html_attr NAME [, VALUE]
           Get or set the HTML attribute NAME.  If just NAME is passed, it
           returns the value of the HTML attribute specified by NAME, or undef
           if there is no such attribute.

           If both NAME and VALUE are passed, it sets the HTML attribute NAME
           to VALUE.

           If NAME is not a valid attribute, a fatal error is thrown.

           Examples:

               $o->html_attr(color => 'red');   # set color to red
               $color = $o->html_attr('color'); # get color

       html_attrs [ATTRS]
           If called with an argument, this method sets and/or adds the HTML
           attributes specified by ATTRS, where ATTRS is a series of
           name/value pairs or a reference to a hash of name/value pairs.

           Returns all of the existing HTML attributes as a hash (in list
           context) or a reference to a hash (in scalar context).

           Note that the reference returned in scalar context is a reference
           to the object's actual hash of attributes; modifying it will change
           the state of the object!  I recommend that you treat the contents
           of the referenced hash as read-only, and I cannot promise that I
           will not find a way to force it to be read-only in the future.

           The order of the attributes in the return value is indeterminate.

           Examples:

               # Set/add attributes
               $o->html_attrs(color => 'red', age => 5); # name/value pairs
               $o->html_attrs({ style => fancy });       # hashref

               %h = $o->html_attrs; # get all three attributes as a hash
               $h = $o->html_attrs; # get all three attributes as a hash ref

       html_attrs_string
           If there are any HTML attributes, it returns a sorted list of HTML
           attributes and their values in a string suitable for use in an HTML
           tag.  The string includes a leading space.

           If there are no HTML attributes, an empty string is returned.

           Examples:

               MyTag->add_valid_html_attrs('color', 'age');
               MyTag->add_boolean_html_attr('happy');

               $o = MyTag->new;

               $o->html_attrs(color => 'red<', age => 5, happy => 12345);

               $s = $o->html_attrs_string; # ' age="5" color="red&lt;" happy'

       html_attr_hook NAME [, CODE]
           If called with two arguments, it sets the hook method for the
           attribute NAME to the code reference CODE.

           If called with one or two arguments, it returns the hook method for
           the HTML attribute NAME as a code reference, or undef if there is
           no hook method.

           Hook methods are called whenever their corresponding HTML attribute
           is set or retrieved.  When the attribute is set, the hook method
           gets the proposed value of the attribute as an argument.  The
           return value of the hook method is then used as the actual value of
           the attribute.

           When an attribute is retrieved, the hook method is called with no
           arguments, and its return value is what is actually returned to the
           caller.

           In both cases, the default variable $_ is localized and then set to
           the new or existing value of the attribute before the hook method
           is called.

           Examples:

               # Set hook for 'color' attribute
               $o->html_attr_hook(color => sub
               {
                 my($self) = shift;

                 if(@_) # attribute is being set
                 {
                   return uc shift; # make it uppercase
                 }

                 # attribute being retrieved:
                 return $_; # return the existing attribute value as-is
               });

               $o->html_attr(color => 'red');   # color set to 'RED'
               $color = $o->html_attr('color'); # $color = 'RED'

       html_element [NAME]
           Get or set the name of the HTML element.  The HTML element is the
           name of the tag, e.g. "img", "p", "a", "select", "textarea", etc.

           This attribute may be read-only in subclasses.

       html_error
           Returns the error text, if any, as a snippet of HTML that looks
           like this:

               <span class="error">Error text goes here</span>

           If the escape_html flag is set to true (the default), then the
           error text has any HTML in it escaped.

       html_tag
           Serializes the object as an HTML tag.  In other words, it is the
           concatenation of the strings returned by the html_element and
           html_attrs_string methods, wrapped with the appropriate angled
           brackets.

       is_self_closing [BOOL]
           Get or set a boolean attribute that determines whether or not the
           HTML for this object requires a separate closing tag.  If set to
           true, then an empty "foo" tag would look like this:

                HTML: <foo>
               XHTML: <foo />

           If false, then the tags above would look like this instead:

                HTML: <foo></foo>
               XHTML: <foo></foo>

           The default value is false.  This attribute may be read-only in
           subclasses.

       locale [LOCALE]
           This method may be called as a class method or an object method.

           When called as an object method and a LOCALE is passed, then the
           locale of this object is set.  When called as a class method and a
           LOCALE is passed, then the default_locale is set.

           If no locale is set for this object (when called as an object
           method), then the the first defined locale from the object's
           parent_group, parent_field, parent_form, or generic parent is
           returned.  If none of those locales are defined, then the
           localizer's locale is returned, if it is set.  Otherwise, the
           default_locale is returned.

           If no locale is set for this class (when called as a class method)
           then the localizer's locale is returned, if it is set.  Otherwise,
           the default_locale is returned.

       localizer [LOCALIZER]
           Get or set the Rose::HTML::Object::Message::Localizer-derived
           object used to localize message text on behalf of this object.  If
           no localizer is set then the default_localizer is returned.

       message_for_error_id [PARAMS]
           Given an error id, return the corresponding message object.  The
           default implementation simply looks for a message with the same
           integer id as the error.  Valid PARAMS name/value pairs are:

           error_id ID
               The integer error id.  This parameter is required.

           args HASHREF
               A reference to a hash of name/value pairs to be used as the
               message arguments.

       parent [OBJECT]
           Get or set the parent object.

       pop_child [INT]
           Remove an object from the end of the list of children and return
           it.

       pop_children [INT]
           Remove INT objects from the end of the list of children and return
           them.  If INT is ommitted, it defaults to 1.

       push_child OBJECT
           Add OBJECT to the end of the list of children.  The object must be
           of or derived from the Rose::HTML::Object class, or a plain scalar.
           If it's a plain scalar, it will be converted to a Rose::HTML::Text
           object, with the scalar used as the value of the text attribute.

       push_children OBJECT1 [, OBJECT2, ...]
           Add objects on to the end of the list of children.  Each object
           must be of or derived from the Rose::HTML::Object class, or a plain
           scalar.  All plain scalars will be converted to Rose::HTML::Text
           objects, with the scalar used as the value of the text attribute.

       set_error
           Set the error to a defined but "invisible" (zero-length) value.
           This value will not be displayed by the html_error or xhtml_error
           methods.  Use this method when you want to flag a field as having
           an error, but don't want a visible error message.

       shift_child [INT]
           Remove an object from the start of the list of children and return
           it.

       shift_children [INT]
           Remove INT objects from the start of the list of children and
           return them.  If INT is ommitted, it defaults to 1.

       unshift_child OBJECT
           Add OBJECT to the start of the list of children.  The object must
           be of or derived from the Rose::HTML::Object class, or a plain
           scalar.  If it's a plain scalar, it will be converted to a
           Rose::HTML::Text object, with the scalar used as the value of the
           text attribute.

       unshift_children OBJECT1 [, OBJECT2, ...]
           Add objects to the start of the list of children.  Each object must
           be of or derived from the Rose::HTML::Object class, or a plain
           scalar.  All plain scalars will be converted to Rose::HTML::Text
           objects, with the scalar used as the value of the text attribute.

       unset_error
           Set the error to a undef.

       validate_html_attrs BOOL
           If set to true, HTML attribute arguments to "html_attr" and
           "html_attr_hook" will be validated by calling
           "html_attr_is_valid(ATTR)", where ATTR is the name of the attribute
           being set or read.  The default value is true for any class derived
           from Rose::HTML::Object, but false for objects whose class is
           Rose::HTML::Object.

       xhtml
           A synonym for the xhtml_tag method.

       xhtml_element [NAME]
           Get or set the name of the XHTML element.  The XHTML element is the
           name of the tag, e.g. "img", "p", "a", "select", "textarea", etc.

           This attribute may be read-only in subclasses.

       xhtml_error
           Returns the error text, if any, as a snippet of XHTML that looks
           like this:

               <span class="error">Error text goes here</span>

           If the escape_html flag is set to true (the default), then the
           error text has any HTML in it escaped.

       xhtml_tag
           Serializes the object as an XHTML tag.  In other words, it is the
           concatenation of the strings returned by the xhtml_element and
           xhtml_attrs_string methods, wrapped with the appropriate angled
           brackets and forward slash character.

       xhtml_attrs_string
           If there are any HTML attributes, it returns a sorted list of HTML
           attributes and their values in a string suitable for use in an
           XHTML tag.  The string includes a leading space.

           If there are no HTML attributes, an empty string is returned.

           Examples:

               MyTag->add_valid_html_attrs('color', 'age');
               MyTag->add_boolean_html_attr('happy');

               $o = MyTag->new;

               $o->html_attrs(color => 'red<', age => 5, happy => 12345);

               # ' age="5" color="red&lt;" happy="happy"'
               $s = $o->xhtml_attrs_string;

SUPPORT
       Any Rose::HTML::Objects questions or problems can be posted to the
       Rose::HTML::Objects mailing list.  To subscribe to the list or search
       the archives, go here:

       http://groups.google.com/group/rose-html-objects
       <http://groups.google.com/group/rose-html-objects>

       Although the mailing list is the preferred support mechanism, you can
       also email the author (see below) or file bugs using the CPAN bug
       tracking system:

       http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-HTML-Objects
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-HTML-Objects>

       There's also a wiki and other resources linked from the Rose project
       home page:

       <http://rose.googlecode.com>

AUTHOR
       John C. Siracusa (siracusa@gmail.com)

LICENSE
       Copyright (c) 2009 by John C. Siracusa.  All rights reserved.  This
       program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.



perl v5.16.3                      2009-11-09             Rose::HTML::Object(3)
