=encoding utf8

=head1 NAME

Strehler::Element - Base class for Strehler entities management

=head1 DESCRIPTION

Articles, images and every entity you decide to manage in Strehler have to be Strehler::Element subclasses. Strehler::Element is the collection of methods that you can call to (mainly) retrieve the data inserted in the CMS and make it available in your business logic.

=head1 SYNOPSIS

Below, a code example to display an archive (with pagination) with all the articles about a certain category.

    get '/romanzo' => sub {
        my $entries_per_page = 20;
        my $page = params->{page} || 1;
        my $order = params->{order} || 'desc';
        my $elements = Strehler::Element::Article->get_list({ 
            page => $page, 
            entries_per_page => $entries_per_page, 
            category => 'EXAMPLE_CATEGORY', 
            language => 'en', 
            ext => 1, 
            published => 1, 
            order => $order});
        template "archive", { 
            page_title => 'Archive',
            articles => $elements->{'to_view'}, 
            page => $page, 
            order => $order, 
            last_page => $elements->{'last_page'} };

    };

=head1 METHODS TO RETRIEVE INFORMATIONS ABOUT AN ENTITY

=over 4

=item exists

Return Value: $exists

Return 1 if the element is linked to a real row on the database, 0 otherwise.

=item check_role

Arguments: $user_role

Return Value: $access

Return 1 if user, considering his $user_role, has rights to access the entity.


=item get_attr

Arguments: $attr, $bare

Return Value: $attr_value

Return the value for the attribute (the database column) named $attr.

If $bare is true (1) database value is given back ignoring possible hook for the attribute.

=item get_attr_multilang

Arguments: $attr, $lang, $bare

Return Value: $attr_value

Return the value for the multilanguage attribute named $attr in the language $lang

If $bare is true (1) database value is given back ignoring possible hook for the attribute.

=item has_language

Arguments: $lang

Return Value: $has_language

Return 1 if the Element has multilang attributes for language $lang

=item get_category_name

Return Value: $category

Return the name of the category of the element in the format $parent/$category is category has two levels.

=item get_tags

Return Value: $tags

Return a string composed with all the tags related to the element, separated with commas.

=item get_basic_data

Return Value %data;

Return all the data about the element, except for multilang attributes.

=item get_ext_data

Arguments: $lang

Return Value %data;

Return all the data about the element as C<get_basic_data>, adding all the multilang attributes in the language $lang.

=item main_title

Return Value: $main_title

Return the main title for the element. The standard implementation try for an attribute named B<title> or B<name>. If these attributes are not available return just B<id>.

In Articles and Images it returns the title attribute in the default language.

=item fields_list

Return Value: $list_of_fields

Return a pointer to an array used by list views to configure the header (and just the header) of the table of contents. Every element of the list is a pointer to an hash. Hash attributes are the following:

    label: The label that will be displayed
    id: used only if the field is ordinable, the db column user to order objects
    ordinable: true if the column can be used to order elements

About id consider notes about order_by field in the get_list method.

=back

=head1 METHODS TO MANIPULATE ENTITIES

These methods are used by Strehler backend, so use them carefully.

=over 4

=item delete

Delete the element and all the multilang attributes linked to it.

=item publish

Publish a publishable element

=item unpublish

Unpublish a publishable element

=back

=head1 METHODS TO RETRIEVE ELEMENTS

The most important methods. Some of them are class method. They're wrappers for the queries needed to retrieve data.

=over 4

=item get_list

Arguments: \%query_params

Return Values: \%elements

Main class method to retrieve elements. There're many query_params you can use.

    order => desc|asc # The order of the results. Default is desc
    order_by => $order_by # The field to order by. Default is id. 
                          # Accept array_ref for multiple ordering.
    entries_per_page => $entries # How many results retrieve. Default is 20.
                                 # -1 makes the method return ALL results
    page => $page. Default is 1
    language => $lang # The language for multilanguage attributes. 
                      # Default is Strehler configured default language
    published => $pub # Retrieve only published elements (for publishable elements)
    tag => $tag # Retrieve elements with a certain tag
    category => $category # Retrieve elements with a certain category
                          # Category can be written in the form $parent/$cat
    category_id => $category_id # Retrieve elements with the category with that id
    ext => 1 # Return elements with all data (get_ext_data is invoked)
    join => $tables #Tables to join for search purpose. Can be an array reference or a single element.
    ancestor => $category_id # Similar to $category_id, but a query with this parameter will retrieve 
                             # from considered category and all its subcategories
                             
            

order_by attribute can be written as a field of the multilanguage children table. For example articles can be ordered using contents.title. In this case contents table will be filtered on language field, using only the considered language in the query. It's not necessary to specify contents table in the join parameter. Tables pointed out in the order by field will be joined automatically.

All the parameters can be combined together.

The method return a pointer to an hash composed by:

    to_view => \@to_view # A pointer to an array of hashes. Every hash contain the data about an element 
                         # as in get_basic_data or get_ext_data
    last_page => last available page, to make easy paging logic.    

=item next_in_category_by_order/prev_in_category_by_order

Arguments: $language

Return Value: $element

Retrieve the next/previous element of the same category of the element used to call it using the display_order as ordering field.
Language is needed because a element could exists in a language but not in another.
Returns a Strehler::Element.
You can use this only on elements with a display_order field (like articles). Configure the entity as ordered.

=item next_in_category_by_date/prev_in_category_by_date

Arguments: $language

Return Value: $element

Same as previous method, but using the publish_date to order elements.
You can use this only on elements with a publish_date field (like articles). Configure the entity as dated.

=item get_first_by_order/get_last_by_order

Arguments: $category, $language

Return Value: $element

Class method. Retrieve the last/first element in the category with category name $category (child categories must be written as parent/child). Order using display_order.
Language considered as in the previous methods.
Returns a Strehler::Element.
You can use this only on elements with a display_order field (like articles). Configure the entity as ordered.

=item get_first_by_date/get_last_by_date

Arguments: $category, $language

Return Value: $element

Same as get_first_by_order/get_last_by_order, using publish_date to order elements.
You can use this only on elements with a publish_date field (like articles). Configure the entity as dated.

=item get_last_pubunpub

Arguments: $category, $language, $order

Return Value: ($element, $element)

This method is used by dashboard. It retrieves a couple of elements, the most recent unpublished one and the most recent published one. 
Refer to L<Strehler::Dancer2::EX::Plugin> latest keyword to understand the logic.

=item error_message

Arguments: $action, $code

Return Value: $message

This method is used to customized error messages that can appear after an action that went wrong. Considered actions in the standard backend are add, edit, delete, publish, unpublish.

We expect that the entity method related to add/edit (save_form) return the id of the submitted entity. Any value returned that is minus to zero is considered an error and error_message is used to find the message to display.

We expect that publish/unpublish and delete return 0 as OK or any othe number as error. Again, error_message is called to retrieve the message.

Designing new entities you can reimplement error_message to display custom message on errors you like to manage.

=back

=head1 SEE ALSO

L<Strehler::Element::Role::Configured> for Element functions related to its configuration.

=cut