Yancy - A simple CMS for administrating data
version 0.004
### Standalone app $ yancy daemon ### Mojolicious plugin use Mojolicious::Lite; plugin Yancy => { ... };
Yancy is a simple content management system (CMS) for administering content in a database. Yancy accepts a configuration file that describes the data in the database and builds a website that lists all of the available data and allows a user to edit data, delete data, and add new data.
Yancy uses JSON Schema to define the data in the database. The schema is added to an OpenAPI specification which creates a REST API for your data.
Yancy can be run in a standalone mode (which can be placed behind a proxy), or can be embedded as a plugin into any application that uses the Mojolicious web framework.
Yancy can manage data in multiple databases using different backends (Yancy::Backend modules). Backends exist for Postgres via Mojo::Pg, MySQL via Mojo::mysql, and DBIx::Class, a Perl ORM
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 "CONFIGURATION" for details.
yancy.conf
NOTE: Yancy does not have authentication or authorization built-in. If you want to control which users have access to data, you should use an HTTP proxy with these features.
Once the application is started, you can navigate to http://127.0.0.1:3000/admin to see the Yancy administration app. Navigate to http://127.0.0.1:3000/ to see the getting started page.
http://127.0.0.1:3000/admin
http://127.0.0.1:3000/
In the standalone app, all paths besides the /admin application are treated as paths to templates.
/admin
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.
templates
MOJO_HOME
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.
.format.ep
format
html
txt
json
xml
Database content can be read by using the database helpers that Yancy provides.
yancy->list( $collection ) - Get a list of items
yancy->list( $collection )
yancy->get( $collection, $id ) - Get a single item
yancy->get( $collection, $id )
yancy->set( $collection, $id, $data ) - Update an item
yancy->set( $collection, $id, $data )
yancy->delete( $collection, $id ) - Delete an item
yancy->delete( $collection, $id )
yancy->create( $collection, $data ) - Create an item
yancy->create( $collection, $data )
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.
For information on how to use Yancy as a Mojolicious plugin, see Mojolicious::Plugin::Yancy.
This application creates a REST API using the standard OpenAPI API specification. The API spec document is located at /api in the standalone app, and /yancy/api in the Mojolicious plugin.
/api
/yancy/api
The Yancy configuration file is a Perl data structure. The individual parts are described below. An example configuration file looks like:
{ backend => 'pg://user@example.com/mydb', collections => { people => { type => 'object', properties => { id => { type => 'integer', readOnly => 1, }, name => { type => 'string' }, email => { type => 'string' }, }, }, }, }
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.
backend
backend => 'pg://user@example.com/mydb',
backend => 'mysql://user@localhost/mydb',
backend => 'dbic://My::Schema/dbi:SQLite:file.db',
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.
collections
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.
title
description
example
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:
people
id
name
email
collections => { people => { properties => { id => { type => 'integer', readOnly => 1, }, name => { type => 'string', }, email => { type => 'string', }, }, }, },
Yancy generates input elements based on the type, and format of the object's properties.
type
type => "boolean" - A Yes/No field
type => "boolean"
type => "integer" - A number field (<input type="number" >)
type => "integer"
<input type="number" >
type => "number" - A number field (<input type="number" >)
type => "number"
type => "string", format => "date" - A date field (<input type="date">)
type => "string", format => "date"
<input type="date">
type => "string", format => "date-time" - A date/time field (<input type="datetime-local">)
type => "string", format => "date-time"
<input type="datetime-local">
type => "string", format => "email" - A e-mail address (<input type="email">)
type => "string", format => "email"
<input type="email">
type => "string", format => "url" - A URL input (<input type="url">)
type => "string", format => "url"
<input type="url">
type => "string", format => "tel" - A telephone number (<input type="tel">)
type => "string", format => "tel"
<input type="tel">
Fields with an enum property will be translated to <select> elements.
enum
<select>
Other schema attributes will be translated as necessary to the HTML input fields:
title will be used to label the input field
readOnly
pattern
minimum
maximum
minLength
maxLength
JSON Schema allows marking properties as required using the required property, which must be an array of property names.
required
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.
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 => { ... }, },
There are some extended fields you can add to your collection definition to control how it is treated by Yancy.
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 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 => { ... }, },
JSON schema, Mojolicious
Doug Bell <preaction@cpan.org>
This software is copyright (c) 2017 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.
To install Yancy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Yancy
CPAN shell
perl -MCPAN -e shell install Yancy
For more information on module installation, please visit the detailed CPAN module installation guide.