NAME

Catalyst::View::Vega - A Catalyst view for pre-processing Vega specs

SYNOPSIS

    # In YourApplication.pm
    #
    YourApplication->inject_component( 'View::Vega' => { from_component => 'Catalyst::View::Vega' } );
    YourApplication->config(
        'View::Vega' => {
            path => YourApplication->path_to("root/vega")->stringify,
        }
    );

    # In a controller action
    #
    my $vega = $c->view('Vega');
    $vega->specfile('patient-chart.json');
    $vega->bind_data({
        "patient"     => [{
            id   => $patient->id,
            name => $patient->name,
        }],
        "medications" => [ $meds->all ],
        "samples"     => [ $samples->all ],
    });
    $c->detach($vega);

DESCRIPTION

This class lets you bind data to the datasets declared in a Vega spec and output the spec with the bound data inlined. This is useful for inlining data dynamically without using a templating library. Inlining data reduces request overhead and creates standalone Vega specs which can be rendered as easily offline as they are online.

A new instance of this view is created for each request, so it is safe to set attributes and use the view's API in multiple controllers or actions. Each new view instance is based on the application's global instance of the view so that initial attribute values are from your application config.

ATTRIBUTES

json

Read-only. Object with encode and decode methods for reading and writing JSON. Defaults to:

    JSON::MaybeXS->new->utf8->convert_blessed->canonical->pretty

You can either set this at application start time via "config" in Catalyst:

    YourApplication->config(
        'View::Vega' => {
            json => ...
        }
    );

or pass it in during the request-specific object construction:

    my $vega = $c->view("Vega", json => ...);

path

Read-only. Filesystem path under which "specfile"s are located. Usually set by your application's config file or via "config" in Catalyst, e.g.:

    YourApplication->config(
        'View::Vega' => {
            path => YourApplication->path_to("root/vega")->stringify,
        }
    );

specfile

Read-write. A file relative to "path" which contains the Vega spec to process. Usually set in your controller's actions.

METHODS

bind_data

Takes a hashref or list of key-value pairs and merges them into the view object's dataset bindings.

Keys should be dataset names which match those in the Vega "specfile". Any existing binding in this view for a given dataset name is overwritten.

Values may be either references or strings. References are serialized and inlined as the values dataset property. Strings are serialized as the url property, which allows you to dynamically reference external datasets. See Vega's documentation on dataset properties for more details on the properties themselves.

Note that Vega expects the values property to be an array, although this view does not enforce that. Make sure your references are arrayrefs or objects that serialize to an arrayref.

Returns nothing.

unbind_data

Takes a dataset name as the sole argument and deletes any data bound in the view object for that dataset. Returns the now unbound data, if any.

process_spec

Returns the Vega specification as a Perl data structure, with bound data inlined into the spec.

process

Sets up up a JSON response using the results of "process_spec". You should usually call this implicitly via "detach" in Catalyst using the idiom:

    my $vega = $c->view("Vega");
    ...
    $c->detach($vega);

This is the most "viewish" part of this class.

AUTHOR

Thomas Sibley <trsibley@uw.edu>

THANKS

Thanks to Evan Silberman <silby@uw.edu> for suggesting dynamic inlining of datasets.

COPYRIGHT

Copyright 2016- by the University of Washington

LICENSE

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

SEE ALSO

Vega data specs

Vega documentation

Vega

cpanm Catalyst::View::Vega

perl -MCPAN -e shell
install Catalyst::View::Vega