NAME
Yancy - A simple CMS for administrating data
VERSION
version 0.010
SYNOPSIS
### Standalone app
$ yancy daemon
### Mojolicious plugin
use Mojolicious::Lite;
plugin Yancy => { ... };
DESCRIPTION
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, SQLite via Mojo::SQLite, and DBIx::Class, a Perl ORM
Standalone App
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.
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/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( $collection )
- Get a list of itemsyancy->get( $collection, $id )
- Get a single itemyancy->set( $collection, $id, $data )
- Update an itemyancy->delete( $collection, $id )
- Delete an itemyancy->create( $collection, $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" ] ],
],
}
Mojolicious Plugin
For information on how to use Yancy as a Mojolicious plugin, see Mojolicious::Plugin::Yancy.
REST API
This application creates a REST API using the standard OpenAPI API specification. The API spec document is located at /yancy/api
.
CONFIGURATION
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' },
},
},
},
}
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 => 'pg://user@example.com/mydb',
- MySQL backend
-
backend => 'mysql://user@localhost/mydb',
- SQLite backend
-
backend => 'sqlite:filename.db',
- DBIx::Class backend
-
backend => 'dbic://My::Schema/dbi:SQLite:file.db',
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',
},
},
},
},
Generated Forms
Yancy generates input elements based on the type
, and format
of the object's properties.
type => "boolean"
- A Yes/No fieldtype => "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">
)
Fields with an enum
property will be translated to <select>
elements.
Other schema attributes will be translated as necessary to the HTML input fields:
title
will be used to label the input fieldreadOnly
pattern
minimum
maximum
minLength
maxLength
A Markdown editor can be enabled by using type => "string", format => "markdown"
. The Markdown can then be saved as HTML in another field by adding x-html-field => $field_name
.
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.
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.
-
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-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 => { ... }, },
- 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 => { ... }, },
Extended Field Configuration
There are some extended fields you can add to a field configuration to control how it is treated by Yancy.
-
If true, thie field will be hidden from the rich editing form.
- 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 add a filter.
Additional Configuration
There are additional configuration keys to alter how Yancy works.
controller_class
To customize how Yancy responds to API requests with data, you can create a custom controller and set the class here. For details how to create a custom controller, see Yancy::Controller::Yancy.
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.
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.
BUNDLED PROJECTS
This project bundles some other projects with the following licenses:
jQuery Copyright JS Foundation and other contributors (MIT License)
Bootstrap Copyright 2011-2017 the Bootstrap Authors and Twitter, Inc. (MIT License)
Popper.js Copyright 2016 Federico Zivolo (MIT License)
FontAwesome Copyright Dave Gandy (SIL OFL 1.1 and MIT License)
Vue.js Copyright 2013-2018, Yuxi (Evan) You (MIT License)
marked Copyright 2011-2018, Christopher Jeffrey (MIT License)
SEE ALSO
AUTHOR
Doug Bell <preaction@cpan.org>
CONTRIBUTORS
Mohammad S Anwar <mohammad.anwar@yahoo.com>
William Lindley <wlindley@wlindley.com>
COPYRIGHT AND LICENSE
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.