NAME

Mandel::Document - A single MongoDB document with logic

SYNOPSIS

Extend a class with MyDocument::Class instead of Mandel::Document:

  package MyModel::Person;
  use Mandel::Document "MyDocument::Class";

Specify a default collection name, instead of the default. "import" will think you meant a base class, if this argument contains "::".

  package MyModel::Person;
  use Mandel::Document "some_collection_name";
  use Types::Standard 'Str';

  field "foo";

  field "foo" => (
    isa => Str,
    builder => sub {
      my $self = shift;
      return "default value";
    },
  );

Spell out the options with a list:

  package MyModel::Person;

  use Mandel::Document (
    extends => "My::Document::Class",
    collection_name => "some_collection_name",
    collection_class => "My::Custom::Collection",
  );

DESCRIPTION

Mandel is a simplistic model layer using the Mango module to interact with a MongoDB backend. The Mandel class defines the overall model, including high level interaction. Individual results, called Types inherit from Mandel::Document.

An object of this class gets automatically serialized by Mojo::JSON. See "TO_JSON" and Mojo::JSON#DESCRIPTION for details.

Example:

  use Mojolicious::Lite;
  # ...
  get '/some/resource' => sub {
    my $c = shift;
    # find some document...
    $c->render(json => $mandel_doc_object);
  };

ATTRIBUTES

Mandel inherits all attributes from Mojo::Base and implements the following new ones.

id

  $object_id = $self->id;
  $self = $self->id("507f1f77bcf86cd799439011");
  $self = $self->id(Mango::BSON::ObjectID->new);

Returns the Mango::BSON::ObjectID object for this document. Will create one if it does not already exist.

This can field can also be set.

data

  $hash = $self->data;
  $self = $self->data($hash);

Holds the raw mongodb document. It is possible to define default values for this attribute by defining builder for the fields.

in_storage

Boolean true if this document has been fetched from storage or saved to storage.

connection

An instance of Mandel. This is required.

model

Returns a Mandel::Model object. This object is a class variable and therefor shared between all instances.

dirty

This attribute holds a hash-ref where the keys are name of fields that has been updated or otherwise not stored in database.

TODO: Define what the values should hold. Timestamp? A counter for how many times the field has been updated before saved..?

METHODS

Mandel::Document inherits all of the methods from Mojo::Base and implements the following new ones.

new

Constructs a new object.

initialize

A no-op placeholder useful for initialization. See "initialize" in Mandel.

contains

  $bool = $self->contains('/json/2/pointer');

Use "contains" in Mojo::JSON::Pointer to check if a value exists inside the raw mongodb document.

fresh

  $self = $self->fresh;

Calling this method will force the next relationship call to return fresh data from database instead of cached. Example:

  $self->fresh->cats(sub {
    my($self, $err, $cats) = @_;
  });

get

  $any = $self->get('/json/2/pointer');

Use "get" in Mojo::JSON::Pointer to retrieve a value inside the raw mongodb document.

is_changed

Returns true if "dirty" contains any field names.

patch

  $self = $self->patch(\%changes, sub { my($self, $err) = @_ });
  $self = $self->patch(\%changes);

This method will insert/update a partial document. This is useful if /data does not contain a complete document.

It will also insert the document if a document with "id" does not already exist.

remove

  $self = $self->remove(sub { my($self, $err) = @_; });
  $self = $self->remove;

Will remove this object from the "collection" and set mark all fields as "dirty".

save

  $self = $self->save(sub { my($self, $err) = @_; });
  $self = $self->save;

This method stores the raw data in the database and collection. It clear the "dirty" attribute.

NOTE: This method will call the callback (with $err set to empty string) immediately unless "is_changed" is true and "in_storage" is false.

set

  $self = $self->set('/json/2/pointer', $val);

Use a JSON pointer to set data in the raw mongodb document. This method will die if the pointer points to non-compatible data.

import

See "SYNOPSIS".

TO_JSON

Alias for "data".

This method allow the document to get automatically serialized by Mojo::JSON.

validate_fields

  $self = $self->validate_fields;

This method can be used to validate the content of the fields of a document againt the types defined in the model. It can be called after a document has been loaded from MongoDB, e.g. via "single" in Mandel::Collection. It can be useful if the data in MongoDB might have been altered by something else after it was stored there.

SEE ALSO

Mojolicious, Mango, Mandel

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org