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:

    entry:                # when __mode=list&_type=entry is requested
        title:            # for the title column
            label: Entry
            html: $Core::MT::Entry::title_html
            # ... to be continued
            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

            label: Title
            base: __virtual.label


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.

            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”


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


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


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


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”


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;


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

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


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;


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


Should the property be displayed by default. possible values:

Always show. the user can not hide this column
Initially show. the user can hide it in the Display Options menu
Initially hide. the user can show it using the menu (this is the default value)
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.




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


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


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;


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;


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,


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


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


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]',


Raw HTML to put in this table cell

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


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


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?

                     class: excerpt
                     label: Excerpt
                     display: default


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


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;


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.