Zoffix Znet > POE-Component-Bundle-WebDevelopment-1.001004 > POE::Component::WebService::Validator::CSS::W3C

Download:
POE-Component-Bundle-WebDevelopment-1.001004.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.001004   Source  

NAME ^

POE::Component::WebService::Validator::CSS::W3C - non-blocking wrapper around WebService::Validator::HTML::W3C

SYNOPSIS ^

    use strict;
    use warnings;

    use POE qw(Component::WebService::Validator::CSS::W3C);

    my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn;

    POE::Session->create(
        package_states => [
            main => [ qw( _start validated ) ],
        ],
    );
    $poe_kernel->run;

    sub _start {
        $poco->validate( {
                event => 'validated',
                uri => 'http://zoffix.com',
            }
        );
    }

    sub validated {
        my $input = $_[ARG0];

        if ( $input->{request_error} ) {
            print "Failed to access validator: $input->{request_error}\n";
        }
        else {
            if ( $input->{is_valid} ) {
                printf "%s is valid! See %s for proof\n",
                            @$input{ qw(uri request_uri) };
            }
            else {
                printf "%s contains %d error(s), see %s\nErrors are:\n",
                            @$input{ qw(uri num_errors request_uri) };

                printf "    %s on line %d\n",
                            @$_{ qw(message line) }
                    for @{ $input->{errors} };
            }
        }

        $poco->shutdown;
    }

Using the event based interface is also possible.

DESCRIPTION ^

The module is a non-blocking POE wrapper around WebService::Validator::CSS::W3C which provides access to W3C CSS validator ( http://jigsaw.w3.org/css-validator/ )

CONSTRUCTOR ^

spawn

    my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn;

    POE::Component::WebService::Validator::CSS::W3C->spawn(
        alias => 'val'
    );

The constructor returns a POE::Component::WebService::Validator::CSS::W3C object, though you don't need to store it anywhere if you set the alias argument (see below). Takes a few optional arguments which are as follows:

alias

    POE::Component::WebService::Validator::CSS::W3C->spawn(
        alias => 'val'
    );

Optional. Specifies a POE Session alias for the component.

ua

    my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
        ua => LWP::UserAgent->new( timeout => 10 ),
    );

Optional. Takes an LWP::UserAgent object which will be used to access W3C validator. If not specified the LWP::UserAgent with its defaults will be used, with the exception of timeout which will be set to 30 seconds.

val_uri

    my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
        val_uri => 'http://jigsaw.w3.org/css-validator/validator',
    );

Specifies the URI of the CSS validator to access. Defaults to: http://jigsaw.w3.org/css-validator/validator, however you are strongly encouraged install local validator, see http://jigsaw.w3.org/css-validator/DOWNLOAD.html for details.

options

    my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
        options => {
            trace => 1,
            default => 1,
        },
    );

Optional. A hashref of POE Session options to pass to the component's session. No options are set by default.

debug

    my $poco = POE::Component::WebService::Validator::CSS::W3C->spawn(
        debug => 1
    );

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS ^

These are the object-oriented methods of the components.

validate

    $poco->validate( {
            event => 'validated', # mandatory
            uri   => 'http://zoffix.com', # this or 'string' must be here
        }
    );

    $poco->validate( {
            event    => 'event_to_send_results_to', # mandatory
            string   => '#foo { display: none; }', # this or 'uri' must be
            medium   => 'print', # this one and all below is optional
            profile  => 'css3',
            warnings => 2,
            language => 'de',
            session  => 'other_session_to_get_results',
            _user    => rand(), # user defined args
            _any     => 'other',
        }
    );

Takes hashref of options. See validate event below for description.

session_id

    my $val_session_id = $poco->session_id;

Takes no arguments. Returns component's session ID.

shutdown

    $poco->shutdown;

Takes no arguments. Shuts down the component.

ACCEPTED EVENTS ^

validate

    $poe_kernel->post( val => validate => {
            event => 'validated', # mandatory
            uri   => 'http://zoffix.com', # this or 'string' must be here
        }
    );

    $poe_kernel->post( val => validate => {
            event    => 'event_to_send_results_to', # mandatory
            string   => '#foo { display: none; }', # this or 'uri' must be
            medium   => 'print', # this one and all below is optional
            profile  => 'css3',
            warnings => 2,
            language => 'de',
            session  => 'other_session_to_get_results',
            _user    => rand(), # user defined args
            _any     => 'other',
        }
    );

Instructs the component to validate some CSS code, which can be passed either in a form of a scalar or in a form of a URI to the page. Options are passed in a hashref with keys as follows:

event

    { event => 'validation_result' }

Mandatory. An event to send the result to.

uri

    { uri => 'http://zoffix.com' }

Semi-mandatory. Either uri or string (see below) must be specified. The uri key instructs the validator to validate the page specified in the value.

string

    { string => '#foo { display: block; }' }

Semi-mandatory. Either string or uri (see above) must be specified. The string key instructs the validator to validate CSS code specified as the value.

medium

    { medium => 'print' }

Optional. Specifies the media type of CSS to check against. Should be one of aural, braille, embossed, handheld, print, screen, tty, tv, and presentation. A special value all can also be specified which means all media types. Defaults to: undef which means validator will use its default, which currently is all.

profile

    { profile => 'css3' }

Specifies the CSS version to check against. Legal values are css1, css2, css21, css3, svg, svgbasic, svgtiny, mobile, atsc-tv, and tv. A special value none can also be used. Defaults to: undef which tells the W3C validator to use its default, which currently defaults to css21.

warnings

    { warnings => 2 }

An integer 0 - 10 that determines how many warning messages you want to get back from the CSS Validator, 0 means no warnings, 10 would give most warnings, but is currently effectively the same as 1. The defaut is undef in which case the CSS Validator determines a default value; this is expected to be as if 2 had been specified. NOTE: there seems to be a discrepancy in WebService::Validator::CSS::W3C documentation and '0' defaults to "Most Important", '1' => 'Normal', '2' => 'All' and value no, or default is "No warnings". The bug report has been submitted and hopefully this will be resolved soon. Use warnings option with caution until this note is removed.

language

    { language => 'de' }

The desired language of the supposedly human-readable messages. The string will passed as an Accept-Language header in the HTTP request. The CSS Validator currently supports en, de, fr, ja, nl, zh, and zh-cn.

session

    { session => $some_other_session_ref }

    { session => 'some_alias' }

    { session => $session->ID }

Optional. An alternative session alias, reference or ID that the response should be sent to, defaults to sending session.

user defined

Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.

shutdown

    $poe_kernel->post( 'calc' => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT ^

 $VAR1 = {
    'result' => 1,
    'is_valid' => 0,
    'num_errors' => '1',
    'errors' => [
                $VAR1->{'som'}{'_content'}[2][0][2][0][2][5][2][0][2][1][2][1][4]
                ],
    'uri' => 'google.ca',
    'request_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca&output=soap12')}, 'URI::http' ),
    'refer_to_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca')}, 'URI::http' ),
    'http_response' => bless( { blah }, 'HTTP::Response' ),
    'som' => bless( { blah }, 'SOAP::SOM' ),
    'val_uri' => 'http://jigsaw.w3.org/css-validator/validator',
    'num_warnings' => '0',
    'warnings' => [],
 };

The result will be posted to the event and (optional) session specified in the arguments to the validate (event or method). The result, in the form of a hashref, will be passed in ARG0. The keys of that hashref are as follows:

result

    { 'result' => 1 }

Whill contain either a true or false value. The false value will indicate that we failed to access the validator, use request_error key (see below) to determine the reason. If the value is true - we successfully accessed the validator (note that it doesn't mean that the code was valid)

request_error

    { request_error => '500: Request timed out' }

If we could not access the validator (i.e. result contains a false value) then the request_error key will contain the description of the error.

is_valid

    { is_valid => 0 }

Will contain either a true or false value. If contains a true value the CSS code which was validate does not contain errors. If is_valid key contains a false value - the CSS code is invalid.

num_errors

    { 'num_errors' => '1' }

Will contain the number of errors found in CSS code which was validated.

errors

    printf "%s on line %d\n", @$_{ qw(message line) }
                for @{ $_[ARG0]->{errors} };

This will contain an arrayref of hashrefs which represent errors. The possible error hashref might be:

    ( {
        context    => 'p',
        property   => 'color',
        expression => { start => '', end => 'not-a-color' }
        errortype  => 'parse-error',
        message    => 'not-a-color is not a color value',
        line       => 0,
    } )

However, not all the keys will be present at all times.

uri

    { 'uri' => 'google.ca' }

If the uri argument was used to the validate event/method (as opposed to string) the uri key in the output will contain whatever you've passed to validate

string

    { 'string' => '#foo { display: block; }' }

If the string argument was used to the validate event/method (as opposed to uri) the string key in the output will contain whatever you've passed to validate

request_uri

    { 'request_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca&output=soap12')}, 'URI::http' ) }

Will contain a URI object which was used to access the validator.

refer_to_uri

    { 'refer_to_uri' => bless( do{\(my $o = 'http://jigsaw.w3.org/css-validator/validator?uri=google.ca')}, 'URI::http' ), }

Will contain a URI object which you can use to direct people to the HTML version of the validator output.

http_response

    { 'http_response' => bless( { blah }, 'HTTP::Response' ) }

The http_response key will contain an HTTP::Response object obtained during the access to validator. You could perhaps examine it to find out why you failed to access the validator.

val_uri

    { 'val_uri' => 'http://jigsaw.w3.org/css-validator/validator' }

The val_uri key will contain a URI of the CSS validator which was used for validaton.

som

    { 'som' => bless( { blah }, 'SOAP::SOM' ), }

The SOAP::SOM object for the successful deserialization, check the result key (see above) for a true value before using this object.

warnings

    { 'warnings' => [], }

The warnings key will contain an arrayref of warnings found in CSS file (providing the warning level was set appropriately). Note: the docs for WebService::Validator::CSS::W3C read:

    Returns a list with information about the warnings found for the style
    sheet. This is currently of limited use as it is broken, see
    http://www.w3.org/Bugs/Public/show_bug.cgi?id=771 for details.

The validator bug shows as "RESOLVED", however I could not get any warnings from WebService::Validator::CSS::W3C. If you can figure it out drop me a line ;)

user defined

    { '_some' => 'other' }

Any arguments beginning with _ (underscore) passed into the validate event/method will be present intact in the result.

SEE ALSO ^

WebService::Validator::CSS::W3C, POE, LWP::UserAgent

REPOSITORY ^

Fork this module on GitHub: https://github.com/zoffixznet/POE-Component-Bundle-WebDevelopment

BUGS ^

To report bugs or request features, please use https://github.com/zoffixznet/POE-Component-Bundle-WebDevelopment/issues

If you can't access GitHub, you can email your request to bug-POE-Component-Bundle-WebDevelopment at rt.cpan.org

AUTHOR ^

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE ^

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.

syntax highlighting: