/ 
Yancy-1.055
River stage one • 3 direct dependents • 3 total dependents
/ Yancy::Help::Standalone

NAME

Yancy::Help::Standalone - How to run Yancy without writing Perl code

VERSION

version 1.055

SYNOPSIS

To see the Yancy UI in action with some sample data, do this in a checkout of the repo:

$ cp eg/test-app/yancy.data.json yancy.data.json
$ cp eg/test-app/myapp.conf yancy.conf
# t/lib is to provide Yancy::Backend::Test
$ perl -Ilib -It/lib bin/yancy daemon &

Having done the above, now visit http://localhost:3000/yancy.

Alternatively, you can try some test data, together with the read_schema feature to automatically configure the API from the database schema:

$ export TEST_ONLINE_SQLITE=sqlite:/tmp/test.db
# run the test, put the test data in a disk file
$ prove -l t/backend/sqlite.t
$ echo >yancy.conf "{backend=>'$TEST_ONLINE_SQLITE', read_schema=>1}"
$ perl -Ilib bin/yancy daemon &

As a further bit of control, you can create your yancy.conf as above, then use an OpenAPI spec instead of reading the schema from the database:

$ SPECFILE=openapi.json
$ perl -Ilib bin/yancy get /yancy/api >$SPECFILE
$ echo >yancy.conf "{backend=>'$TEST_ONLINE_SQLITE', openapi=>'$SPECFILE'}"
$ perl -Ilib bin/yancy daemon &

Getting Started

To run Yancy as a standalone application, you must create a yancy.conf configuration file that defines how to connect to your database and what the data inside looks like. See Yancy::Help::Config for details.

NOTE: Yancy does not have authentication or authorization built-in. If you want to control which users have access to data, you should use a plugin like Yancy::Plugin::Auth::Basic or an HTTP proxy with these features.

Once the application is started, you can navigate to http://127.0.0.1:3000/yancy to see the Yancy administration app. Navigate to http://127.0.0.1:3000/ to see the getting started page.

Rendering Content

In the standalone app, all paths besides the /yancy application are treated as paths to templates. If a specific template path is not found, Yancy will search for an index template in the same directory. If that template is not found, an error is returned.

The templates are found in the templates directory. You can change the root directory that contains the templates directory by setting the MOJO_HOME environment variable.

Template names must end with .format.ep where format is the content type (html is the default). You can render plain text (txt), JSON (json), XML (xml), and others.

Database content can be read by using the database helpers that Yancy provides.

  • yancy->list( $schema ) - Get a list of items

  • yancy->get( $schema, $id ) - Get a single item

  • yancy->set( $schema, $id, $data ) - Update an item

  • yancy->delete( $schema, $id ) - Delete an item

  • yancy->create( $schema, $data ) - Create an item

Some example template code:

%# Get a list of people
% my @people = app->yancy->list( 'people' );

%# Show a list of people names 
<ul>
    % for my $person ( @people ) {
        <li><%= $person->{name} %></li>
    % }
</ul>

%# Get a single person with ID 1
% my $person = app->yancy->get( 'people', 1 );

%# Write the person's name to the page
<p>Hi, my name is <%= $person->{name} %>.</p>

More information about Mojolicious helpers is available at Mojolicious::Guides::Rendering.

Plugins

In standalone mode, you can configure plugins in the Yancy configuration file. Plugins can be standard Mojolicious::Plugins (with a name starting with Mojolicious::Plugin, or they can be specifically for Yancy (by extending Mojolicious::Plugin and having a name starting with Yancy::Plugin).

Plugins are configured as an array of arrays under the `plugins` key. Each inner array should have the plugin's name and any arguments the plugin requires, like so:

{
    plugins => [
        [ 'PodRenderer' ],
        [ CGI => [ "/cgi-bin/script" => "/path/to/cgi/script.pl" ] ],
    ],
}

SEE ALSO

Yancy

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Doug Bell.

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