NAME

Yancy::Guides::Model - Building modules for your application's business logic

VERSION

version 1.088

DESCRIPTION

This guide describes how to extend Yancy::Model to add custom business logic.

Model Classes

There are three types of classes in Yancy::Model:

Model

The model class represents the entire database and contains schemas.

Schema

Schema classes represent individual tables, views, or collections and contain items.

Item

Item classes represent individual records from the database.

Using the Default Model

The default Yancy::Model class contains basic CRUD (Create, Retrieve, Update, Delete) methods.

Setup

For now, you must set up the model manually by creating a Yancy::Model object, passing in a Yancy::Backend:

    my $model = Yancy::Model->new( backend => $backend );

Schemas

Get a schema using the schema method:

    my $users = $model->schema( 'users' );

This returns a Yancy::Model::Schema object (or a custom schema class, see "Schema Classes").

Creating Items

To create an item, use the create method on the schema:

    my $user_id = $model->schema( 'users' )->create({
        username => 'bender',
        password => 'shiny',
    });

Only the ID of the new item is returned.

Lookup by ID

To look up an item by its ID, use the get method on the schema.

    my $bender = $model->schema( 'users' )->get( $bender_id );

This method returns a Yancy::Model::Item object (or a custom item class, see "Item Classes").

Search

To search for items, use the list method on the schema. The list method returns a hash reference with items and total keys. items is an array reference of Yancy::Model::Item objects. total is the total number of items that match the query.

    my $result = $model->schema( 'users' )->list({ active => 1 });
    if ( $result->{total} > 0 ) {
        my @users = $result->{items}->@*;
        say "Found $result->{total} active users: ",
            map { $_->{username} } @users;
    }

Updating Items

To update an item, first get the item object and then call set to update its data.

    my $bender = $model->schema( 'users' )->get( $bender_id );
    $bender->set({ password => 'daffodil' });

Bulk-updating items is not yet supported, but may be added in a later release (patches welcome!)

Deleting Items

If you already have an item, you can use its delete method to delete it. Otherwise, you can delete an item by its ID.

    $model->schema( 'users' )->get( $user_id )->delete;
    $model->schema( 'users' )->delete( $user_id );

Bulk-deleting items is not yet supported, but may be added in a later release (patches welcome!)

Relationships

Related data can be prefetched and added to an item using the join option to get or list.

    my $user = $model->schema( 'users' )->get( $id, join => 'user_roles' );
    my $result = $model->schema( 'users' )->list( {}, join => 'user_roles' );

The resulting data is added in a key named for the join:

    my $roles = $user->{user_roles};

TODO: Items could have a related method that gets related data after-the-fact.

Future Development: Queries

In the future, a query method may be added that will return an object that can build up arguments for a call to the list method, as well as act as a cursor for that call.

Starting a Custom Model

When building your own model layer, you only need to create classes when you want to add custom code. By default, the Yancy::Model class will load classes from all of its configured namespaces.

Make sure to add your namespace to the "namespaces" in Yancy::Model array:

    unshift @{ $model->namespaces }, 'MyApp';

This adds MyApp::Schema as a namespace for schema classes, and MyApp::Item as a namespace for item classes.

Create a Model Class

If you need it, you can create a model class by extending Yancy::Model.

    package MyApp::Model;
    use Mojo::Base 'Yancy::Model', -signatures;

Your model class could include methods for the most common data lookups:

    sub get_user( $self, $id ) {
        return $self->schema( 'user' )->get( $id );
    }

Your model class should also store configuration needed by the other classes:

    # Invitation e-mails come from this address
    has email_from => 'no-reply@example.com';

Schema Classes

Schema classes contain code for working with the entire schema or a subset of the schema. Any code that affects more than one item should live in the schema class.

To create a schema class, extend Yancy::Model::Schema. The name of the schema class should be the camel-cased version of the schema's name.

    package MyApp::Schema::User; # schema: 'user'
    use Mojo::Base 'Yancy::Model::Schema', -signatures;

The schema class should contain methods that work on the collection: Creating new items, searching for items.

    # Invite a new user
    sub invite( $self, $email ) {
        my $id = $self->create({ email => $email });
        $self->get( $id )->send_invite_mail;
        return $id;
    }

Item Classes

Item classes contain code for working on a single item.

To create an item class, extend Yancy::Model::Item. The name of the item class should be the camel-cased version of the schema's name.

    package MyApp::Item::User;
    use Mojo::Base 'Yancy::Model::Item', -signatures;

    # Send the invite mail to this user
    sub send_invite_mail( $self ) {
        my $to = $self->data->{email};
        my $from = $self->model->email_from;
        # TODO: Send e-mail
    }

Adding Custom Validation

To add custom validation to a schema, override the validate method of Yancy::Model::Schema. This method is called by both Schema and Item classes.

Adding Input / Output Transforms (Filters)

To transform a model's input before creation or update, override the create method of Yancy::Model::Schema and the set method of Yancy::Model::Schema. The set method of the Schema class is called by both Schema and Item classes. You cannot modify data in the validate method.

To transform a model's data after being read from the database, override the build_item method of Yancy::Model::Schema.

SEE ALSO

Yancy::Model, Yancy::Guides::Schema, Yancy::Backend, Yancy::Guides

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

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

cpanm Yancy

perl -MCPAN -e shell
install Yancy