/ 
Yancy-1.021
River stage one • 3 direct dependents • 3 total dependents
/ Yancy::Help::Config

NAME

Yancy::Help::Config - How to configure Yancy

VERSION

version 1.021

SYNOPSIS

use Mojolicious::Lite;
plugin Yancy => {
    backend => 'pg://localhost/myapp',
    read_schema => 1,
    collections => {
        users => {
            title => 'Users',
            description => 'The authorized user accounts',
        },
    },
};

DESCRIPTION

This document describes all of the configuration available for Yancy.

When using the Yancy Mojolicious plugin, these values are given as a hash reference argument to the plugin. See "CONFIGURATION" in Mojolicious::Plugin::Yancy for some plugin-specific configuration values.

When using the Yancy standalone mode, these values are defined in a yancy.conf file which is parsed as a Perl hash reference. See Yancy::Help::Standalone for more information about running the standalone app.

Database Backend

The backend URL defines what database to use and how to connect to it. Each backend has its own format of URL, and some examples are shown below. See your backend's documentation for more information.

Postgres backend
# Backend URL
backend => 'pg://user@example.com/mydb',

# Backend hash
backend => {
    Pg => {
        dsn => 'dbi:Pg:dbname',
        username => 'fry',
        password => 'b3nd3r1sgr34t',
    },
}
MySQL backend
# Backend URL
backend => 'mysql://user@localhost/mydb',

# Backend hash
backend => {
    Mysql => {
        dsn => 'dbi:mysql:mydb',
        username => 'fry',
        password => 'b3nd3r1sgr34t',
    },
}
SQLite backend
# Backend URL
backend => 'sqlite:filename.db',

# Backend hash
backend => {
    Sqlite => {
        dsn => 'sqlite:data.db',
    },
}
DBIx::Class backend
# Backend URL
backend => 'dbic://My::Schema/dbi:SQLite:file.db',

# Backend arrayref (passed to Schema->connect() method)
backend => {
    Dbic => [
        'My::Schema',
        'dbi:SQLite:mysql.db',
        undef, undef,
        { PrintError => 1 },
    ],
}

Data Collections

The collections data structure defines what data is in the database. Each key in this structure refers to the name of a collection, and the value describe the fields for items inside the collection.

Each backend may define a collection differently. For a relational database like Postgres or MySQL, a collection is a table, and the fields are columns. For an ORM like DBIx::Class, the collections are ResultSet objects. For a document store like MongoDB, the collections are collections. See your backend's documentation for more information.

Collections are configured using JSON Schema. The JSON Schema defines what fields (properties) an item has, and what type of data those field have. The JSON Schema also can define constraints like required fields or validate strings with regular expressions. The schema can also contain metadata like a title, description, and even an example value. For more information on what can be defined, see the docs on JSON Schema.

For a collection named people that has 3 fields (an integer id and two strings, name and email), a minimal JSON schema will look like this:

collections => {
    people => {
        properties => {
            id => {
                type => 'integer',
                readOnly => 1,
            },
            name => {
                type => 'string',
            },
            email => {
                type => 'string',
            },
        },
    },
},

Instead of (or in addition to) defining collections yourself, you can tell Yancy to read your database to try to determine your collection configuration. See read_schema for more information.

Generated Forms

Yancy generates input elements based on the type, and format of the object's properties.

  • type => "boolean" - A Yes/No field. Boolean fields support input values 0, 1, "true", and "false". They will be stored as 0, and 1 in the database.

  • type => "integer" - A number field (<input type="number" >)

  • type => "number" - A number field (<input type="number" >)

  • type => "string", format => "date" - A date field (<input type="date">)

  • type => "string", format => "date-time" - A date/time field (<input type="datetime-local">)

  • type => "string", format => "email" - A e-mail address (<input type="email">)

  • type => "string", format => "url" - A URL input (<input type="url">)

  • type => "string", format => "tel" - A telephone number (<input type="tel">)

  • type => "string", format => "textarea" - A multiline text field (<textarea>)

  • type => "string", format => "markdown" - A Markdown field that shows a live preview of the rendered HTML. The Markdown can be saved as HTML in another field by adding x-html-field => $field_name to that field.

JSON schemas allow specifying multiple types for a field using an array. If a field has multiple types, the generated form will use the first type to decide what kind of field to display.

Other schema attributes will be translated as necessary to the HTML input fields:

  • title will be used to label the input field

  • description will be placed near the input field to explain it

  • readOnly will set the input field as read-only

  • enum specifies an array of possible values for the property, which will be shown in a drop-down <select> element.

  • pattern for string fields, a string that can be used as a regex, like pattern => '^foo-\d+$'.

  • minimum for numeric fields, the minimum value

  • maximum for numeric fields, the maximum value

  • minLength for string fields, the minimum length

  • maxLength for string fields, the maximum length

Required Values

JSON Schema allows marking properties as required using the required property, which must be an array of property names.

collections => {
    people => {
        required => [ 'name', 'email' ],
        properties => {
            id => {
                type => 'integer',
                readOnly => 1,
            },
            name => {
                type => 'string',
            },
            email => {
                type => 'string',
            },
        },
    },
},

Required values will be marked as such in the HTML.

Nullable Values

If a value can be null (undef in Perl terms) in addition to its declared type (string, integer, etc...), you must add it to the type field by using an array of types:

collections => {
    people => {
        required => [ 'name' ],
        properties => {
            id => {
                type => 'integer',
                readOnly => 1,
            },
            name => {
                type => 'string', # Required and must be a string
            },
            email => {
                type => [ 'string', 'null' ], # Can be null
            },
        },
    },
},

If you don't do this, and still include the field in an object, you will get an error: Expected string - Got null.. The correct way to fix this error is to add null as an option for the field's type.

Example Values

Setting an example value makes it easier to add new data. When a user tries to add a new item, Yancy will fill in the data from the example key of the collection. This key holds an example object using fake data. As an example of our people collection:

people => {
    example => {
        name => 'Philip J. Fry',
        email => 'fry@aol.com',
    },
    properties => { ... },
},

Extended Collection Configuration

There are some extended fields you can add to your collection definition to control how it is treated by Yancy.

title

A friendly title for the collection

description

A description of the collection. Markdown will be parsed into HTML.

You can use the trim and unindent functions from Mojo::Util to allow indenting your collection description:

use Mojolicious::Lite;
use Mojo::Util qw( unindent trim );
plugin Yancy => {
    collections => {
        employees => {
            description => unindent( trim q{
                The employees of Planet Express.

                * [View the employee health plan](/decapod-life)
                * [Latest Good News](/news)
            } ),
        },
    },
};
x-hidden

If this is true, the collection will be hidden from the list in the Yancy web app. This does not prevent using the API to edit this data.

x-ignore

Ignore this collection: Do not add it to the API, do not show it in the rich editing form. This is for collections that should not be edited from the Yancy form or the Yancy API.

This allows for removing collections when using "read_schema".

x-id-field

This key sets the name of the collection's ID field to use to uniquely identify individual items. By default, Yancy assumes the ID field is named id. If your collection uses some other identifier (e-mail address or username for example), you should set this configuration key.

people => {
    'x-id-field' => 'email',
    properties => { ... },
},

This field can be any unique identifier, but it will be the ID that Yancy uses for all of its operations.

x-list-columns

This key should be an array of columns to display on the list view, in order. This helps put useful information on the list page.

people => {
    'x-list-columns' => [ 'name', 'email' ],
    properties => { ... },
},

Instead of field names, columns can also be made out of templates using a hash with title and template keys. Inside the template key, use fields from the row with {field}, like so:

people => {
    'x-list-columns' => [
        { title => "Person", template => '{name} <{email}>' },
    ],
},
x-filter

This key is an array of filter names to run when setting or creating an item. Filters can allow for hashing passwords, for example. Filters are added by plugins or during configuration of Mojolicious::Plugin::Yancy. See "yancy.filter.add" in Mojolicious::Plugin::Yancy for how to create a filter in your app.

x-view-url

A URL to view the collection in the application. Will be shown as a button in the editor.

x-view-item-url

A URL to view the items in the collection. Will be shown as an icon next to the item row. Add data from the row in the url using {field}, like so:

# /people/1
/people/{id}
# /user/preaction
/user/{username}

Extended Field Configuration

There are some extended fields you can add to a field configuration to control how it is treated by Yancy.

title

A friendly title for the field

description

A description of the field. Markdown will be parsed into HTML.

x-hidden

If true, thie field will be hidden from the rich editing form. This is for collections that you want to use from the API but do not want to edit from the Yancy application.

x-order

Set the order of the fields in the edit form by assigning a number to the x-order property. Fields in the form are be sorted by their x-order, and then by their name (alphabetically). Fields that do not have x-order set will be sorted after fields that do.

x-filter

This key is an array of filter names to run on the field when setting or creating an item. Filters can allow for hashing passwords, for example. Filters are added by plugins or during configuration of Mojolicious::Plugin::Yancy. See "yancy.filter.add" in Mojolicious::Plugin::Yancy for how to create a filter in your app.

OpenAPI specification

Generation

An OpenAPI spec will be generated from the collections specified as above, by using the collections value as the /definitions of the spec. A default type called _Error will be added, to act as the return type in case of error.

From this, the /paths will be generated by adding one for each of CRUD (create, read, update, delete) plus a "list", to each collection.

Finally, for each operation generated under /paths, an x-mojo-to will be added, to connect it to the right controller. See Mojolicious::Plugin::OpenAPI::Guides::Tutorial for more information.

Passing in complete

As an alternative to supplying only the collections (and/or a true value for read_schema), you can pass a complete OpenAPI spec as openapi. It is an error to pass both collections and openapi. The spec will then have x-mojo-to added to each operation, using inferences based on the HTTP method.

The /definitions of the spec will be used as the collections property of the backend.

All of the operations on each path under /paths of the spec must, in line with REST convention, refer to only a single "collection". If any path has operations referring to more than one collection, that is an error. To derive which collection, these things are considered:

  • a key x-collection with string-value under the path

  • within the path's operations, looks up the $ref of either the body parameter (for mutations) or either the first 2XX, or default, response

  • the first path-component, so /user would operate on user

Each operation infers from the HTTP method plus other information which method of Yancy::Controller::Yancy::API it should connect to.

The id_field stash parameter is either the value of the x-id-field key in the operation or path spec, or if not given, the name of the last in: "path" parameter specified in the operation's spec. These methods need an id_field parameter: get in "read" mode, put, and delete. This is what the controller will pass as the id to the relevant Yancy::Backend method.

Additional Configuration

There are additional configuration keys to alter how Yancy works.

read_schema

When this is set, Yancy will read your backend to see what collections you have available. Any collections and fields that you do not configure will be assigned default configuration from your database schema. You can use the configuration to override information that Yancy gets incorrect, or to set information that Yancy can't (like the title and description of collections and properties).

You can also set this on a per-collection basis to read only certain collections from the database. This way you can include only the data you want in your editor.

NOTE: This exposes all the data in your schema to Yancy's API, which allows anyone to edit the data. If you do not want anyone to edit the data, use the plugin's route configuration to add authentication to Yancy.

# All collections
use Mojolicious::Lite;
plugin Yancy => {
    backend => 'pg://localhost/myapp',
    read_schema => 1,
};

# Only the notes and events
use Mojolicious::Lite;
plugin Yancy => {
    backend => 'pg://localhost/myapp',
    collections => {
        notes => { read_schema => 1 },
        events => { read_schema => 1 },
    },
};

api_controller

To customize how Yancy responds to API requests with data, you can create a custom controller and set the class name here. For details how to create a custom API controller, see Yancy::Controller::Yancy::API.

SEE ALSO

Yancy, Mojolicious::Plugin::Yancy

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 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.