NAME

Mojo::DOM::Role::AttrAccessors - Attribute accessors for Mojo::DOM

SYNOPSIS

use Mojo::DOM;

my $dom = Mojo::DOM->with_roles('+AttrAccessors')
                   ->new('<a href="https://example.com">Example</a>')
                   ->at('a');

# Read an attribute
my $href = $dom->href;

# Write an attribute
$dom->href('https://mojolicious.org');

# Chain
$dom->href('https://mojolicious.org')->id('main-link');

# Structured data via data-* attributes
$dom->data('config', { foo => 1 });
my $config = $dom->data('config');    # returns hashref

# Plain strings pass through untouched
$dom->data('label', 'hello');
my $label = $dom->data('label');      # returns "hello"

DESCRIPTION

Mojo::DOM::Role::AttrAccessors is a Mojo::Role that adds autoloaded attribute accessors to Mojo::DOM nodes. Any HTML attribute can be read or written as a method call directly on the node, without going through "attr" in Mojo::DOM.

The role also provides a "data" method for ergonomic access to data-* attributes, with automatic JSON serialisation for reference values.

METHODS

Mojo::DOM::Role::AttrAccessors implements the following methods.

data

my $val = $dom->data('key');
$dom->data('key', 'plain string');
$dom->data('key', { structured => 'data' });
$dom->data('key', [1, 2, 3]);

Read or write a data-* attribute on the node. The following encoding rules apply:

Inbound

If the value is a reference it is JSON-encoded before storing. Plain scalars are stored as-is.

Outbound

If the stored value is valid JSON and decodes to a reference, the reference is returned. Otherwise the raw string is returned. This means plain strings and bare JSON scalars (42, true) are always returned as strings.

CAVEAT

JSON boolean values (true, false) are returned as Mojo::JSON boolean objects, which evaluate correctly in boolean context. Note that storing \1 or \0 will round-trip as these boolean objects rather than the original scalar references.

AUTOLOAD

my $val = $dom->href;
$dom->href('https://mojolicious.org');

Any method call not defined by this role or Mojo::DOM is intercepted and treated as an attribute accessor. The method name is used directly as the attribute name.

Note that HTML attributes containing hyphens (such as data-foo or aria-label) are not accessible via AUTOLOAD since hyphens are not valid in Perl method names. Use "attr" in Mojo::DOM directly for those:

$dom->attr('aria-label');
$dom->attr('data-foo');

Or use "data" for data-* attributes specifically.

CAVEATS

If a future version of Mojo::DOM introduces a method whose name clashes with an HTML attribute you are accessing via AUTOLOAD, the real method will take precedence and AUTOLOAD will not fire. Use "attr" in Mojo::DOM directly in that case.

SEE ALSO

Mojo::DOM, Mojo::Role

AUTHOR

Simone Cesano <scesano@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) Simone Cesano.

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

cpanm Mojo::DOM::Role::AttrAccessors

perl -MCPAN -e shell
install Mojo::DOM::Role::AttrAccessors