/ 
Strehler-1.6.8
River stage one • 2 direct dependents • 2 total dependents
/ Strehler::Element

NAME

Strehler::Element - Base class for Strehler entities management

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.

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'} };

};

METHODS TO RETRIEVE INFORMATIONS ABOUT AN ENTITY

exists

Return Value: $exists

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

check_role

Arguments: $user_role

Return Value: $access

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

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.

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.

has_language

Arguments: $lang

Return Value: $has_language

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

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.

get_tags

Return Value: $tags

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

get_basic_data

Return Value %data;

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

get_ext_data

Arguments: $lang

Return Value %data;

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

main_title

Return Value: $main_title

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

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

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.

METHODS TO MANIPULATE ENTITIES

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

delete

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

publish

Publish a publishable element

unpublish

Unpublish a publishable element

METHODS TO RETRIEVE ELEMENTS

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

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.
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.

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.

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.

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.

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 Strehler::Dancer2::EX::Plugin latest keyword to understand the logic.

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.

SEE ALSO

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