En dev registry list properties

aklaswad edited this page Dec 26, 2011 · 17 revisions

Registry: list_properties

list_properties structure

list_properties define which properties will be visible on the listing screen and how they will be rendered. It define these three subjects:

  • View column appearance
  • Filtering items according to this property
  • Sorting the item list based on this property

For example, if we add a title column to an entry, we should add it to the config.yaml file:

list_properties:
    entry:                # when __mode=list&_type=entry is requested
        title:            # for the title column
            label: Entry
            html: $Core::MT::Entry::title_html
            # ... to be continued
        body:
            label: Body
            html: $Core::MT::Entry::body_html
            # ... to be continued

Inheriting from a default property type

You can set up the property to inherent one of the default property types, using the base field
In the example below, we define the title property to be kind of a label

list_properties:
    entry:
        title:
            label: Title
            base: __virtual.label

Auto

Auto will ask the listing framework to try to deduce the viewing setting from the database schema.
The only thing that it can not deduce is the label, that you have to specify.

list_properties:
    entry:
        title:
            auto: 1
            label: Title
        keyword: Keyword

title is of type string in the schema, so it will automatically inherent from __virtual.string the filtering (based on text search) and sorting
the keyword field is a syntactic sugar for defining auto=1 and label=“Keyword”

Filtering

For enabling filtering based on a property, it needs at least filter_tmpl and terms.
If the filter can not be expressed in SQL terms, use ‘grep’ instead of ‘terms’.
See also filter_label for changing the name in the filter list.
Or you can just set the base to a default type, and inherent its filter

Field reference

args_via_param

When the list is loaded initially with a filter, convert this filter parameters to loading instructions.
Usually the list is loaded without a filter initially, here are some of the cases that it does currently in the system:
Filter profile pictures assets for a user, a list of entries / pings belong to a category, comments that belong
to specific commenter and so on

the filter_val parameter is either a comma-separated list with one value for each property, (in this case
the function gets the part that match to this property in the $val parameter) or is simply a single value,
acting as parameter to the filter parameter. (in this case the function should access it directly using
app->param('filter_val'). and there should be probably only one property with args_via_param in this object)

                  args_via_param => sub {
                      my $prop = shift;
                      my ( $app, $val ) = @_;
                      return { option => 'equal', string => $val };
                  },

auto

Automatically deduce viewing style from the database schema. default: false

base

Specify which of the property to inherent from. default is undef. (do not inherent)
The default types are: hidden, string, integer, float, date, single_select, id, label, title, name, created_on, modified_on, author_name, tag and object_count.
(All are listed in MT::Core, search for “list_properties”)
For inheriting from one of the default type, you should write: “__virtual.string”
Or it is possible to inherent from other property. i.e. “entry.created_on”

bulk_html

a function that should return a list of the HTML to display in the cells of this property. Should return one HTML string for every object

bulk_html => sub {
    my $prop = shift;
    my ($objs, $app, $opts) = @_;
    my %authors = map { $_->author_id => 1 } @$objs;
    my @authors = MT->model('author')->load(
        { id => [ keys %authors ], },
    );
    my %author_name = map { $_->id => $_->display_name } @authors;
    my @out;
    for my $obj (@$objs) {
        my $name = $author_name{ $obj->author_id };
        push @out, $name;
    }
    return @out;
},

bulk_sort

ロード済みオブジェクトのソートを行うサブルーチンを指定します。 sort の指定がなく、 bulk_sort が指定されている場合のみ有効となります。bulk_sortを行う場合、ページに含まれないものを含めた全オブジェクトがロードされます。そのため、パフォーマンスの劣化を招く恐れがあります。

bulk_sort => sub {
    my $prop = shift;
    my ($objs, $opts) = @_;
    return sort {
        $a->name cmp $b->name
    } @$objs;
},

condition

Return true if this property should be display in this context. Some fields are useful only on blog scope, system scope, for admin user and more

condition => sub {
   my $obj = shift;
   ....
}

default_sort_order

Initial sort direction, can be either ascend or descend. default: ascend

display

Should the property be displayed by default. possible values:

force
Always show. the user can not hide this column
default
Initially show. the user can hide it in the Display Options menu
optional
Initially hide. the user can show it using the menu (this is the default value)
none
Always hide.

Note that you must set ‘force’ display setting to the ‘primary’ column which was specified at listing_screens registry. If you have multiple primary columns, set ‘force’ to at least one.

filter_editable

ユーザーがフィルタアイテムの編集を行えるかを指定します。

filter_label

Set the name of the filter in the list. If omitted, the label property will be used

filter_tmpl

A template (MTML) for creating a filter from this field. Can be either the template string itself, or a function returning it.
For examples, see tmpl/cms/include/basic_filter_forms.tmpl

grep

If, for some reason, it is impossible to filter the objects in the SQL level, (using the cms_pre_load_filtered_list.object callback) and there is a need for Perl-level filtering.
This can cause performance degradation, as all the objects will have to be loaded first

grep => sub {
    my $prop = shift;
    my ( $args, $objs, $opts ) = @_;
    return grep { some_complex_judge( $_ ) } @$objs;

html

The HTML to be put in this table cell. will be called for each object separately

html => sub {
    my $prop = shift;
    my ( $obj, $app, $opts ) = @_;
    return sprintf '<p class="foo">%s</p>', $obj->text;
}

html_link

If the content of this table cell should be a link, use this field. It specify that link.
Should be used together with “raw”, that will specify the displaying HTML inside the ‘a’ tag.

html_link => sub {
    my $prop = shift;
    my ( $obj, $app, $opts ) = @_;
    return $app->uri(
        mode => 'foo',
        args => {
            id => $obj->id,
        },
    );
},

init

This function is used to initialize the MT::ListProperty object, gets $prop as parameter.
This function is quite rare.

label

The name for the column – to put in the heading of the table

label_via_param

see args_via_param for explanation on when this is used.
This will change the heading label for the property

label_via_param => sub {
    my $prop = shift;
    my ( $app, $val ) = @_;
    return MT->translate(
        '[_1] in [_2]: [_3]',
        $prop->datasource->class_label_plural,
        $prop->label,
        MT::Util::encode_html($val),
    );
},

raw

Raw HTML to put in this table cell

raw => sub {
    my $prop = shift;
    my ( $obj, $app, $opts ) = @_;
    return $obj->title;
},

sort

Inject instruction for the load function on how to sort this field. Gets the $terms and $args of the loading as parameters.
TODO: need to verify that it is actually used…

sort => sub {
    my $prop = shift;
    my ( $terms, $args, $opts ) = @_;
    $args->{sort} = 'title';
    return;
}

sub_fields

Sub-fields to add to the cell. each needs class, label and display.
The class is used by the JavaScript to show and hide this sub-field, using the Display Options menu
TODO: Is it used?

list_properties:
    entry:
        title:
            sub_fields:
                - 
                     class: excerpt
                     label: Excerpt
                     display: default

terms

When a filter is active, this property is used to turn the html-form parameters to SQL statement.
The return value will be added to the $terms parameter of the object loading.

terms => sub {
    my $prop = shift;
    my ( $args, $db_terms, $db_args, $opts ) = @_;
    my $value  = $args->{value};
    return { $col => $value };
},

validate_item

Check that the filter options are sane, before continue processing it. return true if it is

validate_item => sub {
    my $prop   = shift;
    my ($item) = @_;
    my $args   = $item->{args};
    my $option = $args->{option}
        or return $prop->error(
        MT->translate('option is required') );
    return 1;
},

view

Specify in which scopes this property is available. For example, when viewing in blog scope we probably don’t want to see the blog name, while in system scope we do what to see for which blog this object belongs

view => [ 'system', 'website', ],

See Also

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.