The subitems list: Table options and its columns #

Read this page if your editors use the sub items list in the admin, if you override children_detailed.tpl or its JavaScript, or if you want to add a column of your own. In Exponential 6.0.15 the Table options of the list under every node (content/view/full/<node id>) offers a catalogue of more than a hundred columns instead of 15 fixed ones, grouped, sortable on the server, reorderable, with presets and CSV export. A site developer adds a column with a few lines of INI and a PHP function or a template.

Everything a column shows is computed on the server, only for the columns the user made visible and only for the rows of the page on screen. A column the user may not see (its Policy[]) is not offered, not computed and not sent.

In short #

What users see #

Table options (the button above the list) has:

• Number of items per page: 10, 25, 50, 100 (subitems.ini [SubitemsSettings] PageSizes[]), or a custom number.
• Find a column: a filter box; type part of a name ("alias", "count") and only the matching columns stay in the list.
• The columns by group: Basic, Node, Object, Version, Location, URLs, SEO, Dates, People, Relations, Translations, Workflow, Users, Media, Technical, Custom, and one group "Attributes: <class>" per class among the children. A checkbox per column; the column's description is its tooltip.
• Order of the visible columns: drag a column to move it, or use its arrow buttons.
• Column presets: choose one (SEO, Editorial, Technical, Translations ship with the system), Save current as... to keep the current columns under a name of your own, Delete preset for your own.
• Export CSV: downloads every child (up to CSVLimit) with the visible columns, in their order.

In the table itself, a click on a sortable column's header sorts the list by it, on the server (so the order is right across pages). A cell of a column marked Copy=true (IDs, paths, URLs, the page title ...) copies its value on a click and says "Copied".

The choice is saved for the user, per part of the admin (the content tree, the media library and the users keep their own), on the server: it follows the user to every browser. The columns chosen earlier in the eZSubitemColumns cookie are taken over the first time.

The list works this way in every admin design: admin and admin4 have their own children_detailed.tpl, the other admin designs (admin2, admin3, sevenx_site_admin) use the one of the design they fall back on. Without the server functions (an old ezjscore.ini) it falls back to the classic 15 columns.

The column catalogue #

129 columns ship in settings/subitemscolumns.ini; on top of them come the automatic attribute columns (below). "Sort" names the field the list sorts by when the header is clicked (empty: not sortable); "Policy" the functions a user needs to be offered the column at all. "Kind" is how the value is made: built-in (rendered by the list from the node, as before), a class and its Field=, a Handler or a Template.

Basic (5) #

Node (16) #

Object (14) #

Version (7) #

Location (5) #

URLs (10) #

SEO (5) #

Dates (10) #

People (5) #

Relations (6) #

Translations (6) #

Workflow (12) #

Users (9) #

Media (12) #

Technical (4) #

Custom (3) #

How some columns work it out #

• Page title in the browser (pagetitle) is the <title> the public site prints for the item's page, worked out from the node and the public siteaccess's settings, without rendering the page. The public siteaccess is SiteAccess= in the block, else site.ini [SiteSettings] DefaultAccess (on the reference installation: site). TitleFormat= picks the rule of the design that siteaccess uses:

  • name (the default; the media design, extension/sevenx_themes_media/design/media/templates/pagelayout/head/title.tpl): <page title> - <SiteName>, where the page title is the meta title of the item's xrowmetadata attribute when it has one, else the item's name; the page title alone when it equals SiteName. So on the reference installation the media root is "Media - Fit & Healthy", and the front page node "Fit & Healthy" is just "Fit & Healthy".
  • path (design/standard and ezwebin page_head.tpl): the names of the item and its ancestors, the item first, joined by " / ", then " - <SiteName>": "Banners / Media - Bold Agency" (the example under "The shipped families").

  SiteName is the public siteaccess's [SiteSettings] SiteName; names are taken in its first SiteLanguageList[] language when the item has it. The value is the plain text (with &, not &), as the browser shows it. A meta title is used as it is stored; the xrowmetadata metadata() operator leaves [name] style placeholders in place, and so does the column.

• URL alias (urlalias) is the alias the admin uses (url_alias of the node). The kernel answers an empty alias in two cases, and the column resolves both from the alias table instead of showing an empty cell: the node that owns the root element of ezurlalias_ml (the row with parent 0 and empty text) is the page at the site root and shows /; the content root ([NodeSettings] RootNode), whose pathWithNames() is always empty, shows its own alias when the root element belongs to another node. On the reference installation the root element belongs to node 89 ("Fit & Healthy", the front page), which also has the named alias fit-healthy its children hang below, and node 2 is reached at websites. All URL aliases (allaliases) lists every own alias of the item.

• Public path / Public URL take the public siteaccess's PathPrefix off the alias (unless PathPrefixExclude[] keeps it, as urlAlias() does) and put its SiteURL in front, with Scheme=https unless SiteURL has a scheme.

• Hidden is the item hidden by an editor; Invisible is "not shown to visitors", hidden itself or below a hidden node. They differ for everything below a hidden node.

• Node children count counts the children the current user may read; Child classes counts every child per class (numbers only, no names).

• Word count, Text length and Reading time read the main text: the first of body, description, intro, short_description (or Attributes[] in the block) that is a rich text, XML or text block with content, else the first such attribute at all; markup is left out.

• Users columns are empty for anything that is not a user account.

• Rating, Tags need the ezstarrating and eztags extensions and an attribute of that kind; without them they are empty, never an error.

Every column gives an empty cell (null) when it does not apply to an item's class, and never stops the list: a column that fails gives an empty cell and a debug warning.

Adding a column in 3 minutes #

A column is one [Column_<key>] block. Put it in settings/override/subitemscolumns.ini.append.php, or better in an extension: extension/<yours>/settings/subitemscolumns.ini.append.php (with the extension listed in ActiveExtensions[]). The key is lowercase letters, digits and _. Clear the INI cache afterwards (php bin/php/ezcache.php --clear-tag=ini); reload the PHP-FPM that serves the admin when a PHP class was added (and regenerate the autoloads). A new template also needs the template override cache cleared (--clear-id=template-override), or the cell stays empty.

The three examples below are the ones tests/tests/kernel/classes/subitems/columns/fixtures/subitemscolumns.ini.append.php holds; expSubitemsGuideExamplesTest loads that file into a registry and computes the columns as the rows server function does.

1. A Handler: one function #

[Column_mydaysonline]
Name=Days online
Group=Custom
Type=number
Handler=expSubitemsColumnHandlers::daysOnline
SortField=published
Align=right
Order=5000
Description=Whole days since the item was first published.

class expSubitemsColumnHandlers
{
    public static function daysOnline( eZContentObjectTreeNode $node, array $settings, expSubitemsColumn $column )
    {
        $object = $node->attribute( 'object' );
        $published = $object instanceof eZContentObject ? (int)$object->attribute( 'published' ) : 0;
        return $published > 0 ? expSubitemsColumn::days( $published ) : null;
    }
}

The function gets the row's node, the block as an array and the column object, and returns the value: null, a scalar, or a list of scalars. Type= decides how the cell and the CSV show it (a number here). SortField=published makes the header sort the list by publishing date. The shipped kernel/classes/subitems/columns/expsubitemscolumnhandlers.php has this one and editLink.

2. A Class: a column of your own #

[Column_myreadingtime]
Name=Reading time
Group=Custom
Type=number
Class=expSubitemsReadingTimeColumn
WordsPerMinute=250
Align=right
Order=5010
Description=Minutes a reader needs for the main text.

class expSubitemsReadingTimeColumn extends expSubitemsColumn
{
    public function value( eZContentObjectTreeNode $node )
    {
        $count = $this->wordCount()->value( $node );
        if ( !$count )
            return null;
        $perMinute = max( 1, (int)$this->setting( 'WordsPerMinute', 200 ) );
        return max( 1, (int)ceil( $count / $perMinute ) );
    }

    public function html( eZContentObjectTreeNode $node, $value )
    {
        return $value === null ? '' : self::escape( $value . ' ' . ezpI18n::tr( 'design/admin/node/view/full', 'min' ) );
    }

    public function prefetch( array $nodes )
    {
        $this->wordCount()->prefetch( $nodes );
    }

    protected function wordCount()
    {
        return new expSubitemsObjectColumn( $this->key, array( 'Field' => 'word_count' ) + $this->settings );
    }
}

A class extends expSubitemsColumn and implements value(); it may override html() (the cell; escape everything with self::escape()), text() (the CSV), sortBy(), isAvailable() and prefetch() (see Performance). It reads its own settings with $this->setting( 'Name', $default ), so one class can serve several blocks. The base class has the formatting every column shares, for use in value() and html(): escape(), oneLine(), markupToText(), linkHtml(), formatDate(), formatAge() ("3 days ago"), days(), formatBytes() ("245 kB"), and memo( $bucket, $key, $compute ) for a lookup done once per request. This is the shipped readingtime column (kernel/classes/subitems/columns/expsubitemsreadingtimecolumn.php).

3. A Template: markup without PHP #

[Column_mystatus]
Name=Status
Group=Custom
Type=html
Template=design:subitems/columns/statusbadge.tpl
Order=5020
Description=What visitors see of the item.

{def $exp_badge = 'visible'}
{if $node.is_hidden}{set $exp_badge = 'hidden'}
{elseif $node.is_invisible}{set $exp_badge = 'invisible'}
{elseif $node.object.state_identifier_array|contains( 'ez_lock/locked' )}{set $exp_badge = 'locked'}{/if}
{switch match=$exp_badge}
{case match='hidden'}<span class="exp-subitems-badge exp-subitems-badge-hidden">{'Hidden'|i18n( 'design/admin/node/view/full' )}</span>{/case}
...
{case}<span class="exp-subitems-badge exp-subitems-badge-visible">{'Visible'|i18n( 'design/admin/node/view/full' )}</span>{/case}
{/switch}
{undef $exp_badge}

The template gets $node (the row), $column (the block as a hash: $column.Length, $column.Attributes) and $key. Its output is the cell; its text without tags ("Visible") is the value and the CSV text. Escape what you print (|wash). The shipped design/standard/templates/subitems/columns/statusbadge.tpl and teaser.tpl are both examples; teaser.tpl shows reading block settings and an XML text block.

The shipped families #

Most shipped columns are one class per family with Field= choosing the column, so a block of your own can reuse them with other settings (another SiteAccess= for the page title, Limit= for relation names, Attributes[] for the main text or the image):

For example, the title of the bold siteaccess, by the path rule (design/standard style):

[Column_pagetitle_bold]
Name=Page title (bold)
Group=SEO
Type=text
Class=expSubitemsSEOColumn
Field=page_title
SiteAccess=bold
TitleFormat=path
Copy=true
Order=701
Description=The <title> of the bold siteaccess.

On the reference installation the media root's first child then shows "Banners / Media - Bold Agency". A SiteAccess= that is not in AvailableSiteAccessList[] gives an empty cell.

Automatic attribute columns #

With subitems.ini [SubitemsSettings] AttributeColumns=enabled, Table options also offers one column per attribute of every class among the parent's children, in a group "Attributes: <class name>", key attr:<class identifier>/<attribute identifier> (one query finds the classes). The value is the attribute's title, else its text without tags (at most 300 characters); the column sorts when the datatype has a sort key, and sorting by it limits the list to that class (subTree's attribute sort leaves the other classes out; the count stays right). AttributeColumnsExcludedDataTypes[] keeps datatypes out (ezuser by default: its text holds the password hash), and AttributeColumnsDataTypePolicy[<datatype>]=module/function gives a datatype's columns a policy.

Policies #

Policy[]=module/function entries in a block must all be granted (any limitation counts as granted) or the column does not exist for that user: not in Table options, not computed, not in the rows or the CSV, and a saved choice or preset that names it simply leaves it out. Several entries can also be written in one line separated by ;. The rows themselves always respect content/read: the list and the CSV only show children the user may read, and the rows function requires read access to the parent.

The shipped policies: the Users group needs role/read (the people who see the role setup), and E-mail and Failed logins need role/assign. Columns that list names of other objects (related objects) leave out those the user may not read.

Defaults per subtree and class #

What a user sees before saving a choice of their own comes from subitems.ini: the first [Defaults_<id>] block whose Subtree[] holds the parent or one of its ancestors, or whose ParentClassIdentifiers[] holds the parent's class, wins, in file order; else DefaultColumns[]. The shipped blocks keep the list's former defaults for the media library (thumbnail;name;visibility;type) and the users tree.

[Defaults_fitness]
Subtree[]
Subtree[]=92
ParentClassIdentifiers[]
ParentClassIdentifiers[]=ng_blog
Columns[]
Columns[]=name
Columns[]=published
Columns[]=publishedage
Columns[]=pagetitle

On the reference installation this gives name, published, publishedage, pagetitle under "Fitness" (node 92) and under every node below it. Blocks added by an override file come after the shipped ones, so to change the media library's or the users' defaults, override Columns[] of [Defaults_media] / [Defaults_users] instead of adding a block for the same place.

Presets #

[Preset_<id>] blocks in subitems.ini (id: a-z, 0-9, _, -) are offered to everybody: Name= and Columns[] in order. Shipped: seo, editorial, technical, translations. Users save their own next to them ("Save current as..."), at most 20, and cannot take an INI preset's id. A preset's columns the user may not see are left out for that user.

INI reference #

settings/subitemscolumns.ini #

settings/subitems.ini #

The server API #

Three ezjscore functions, [ezjscServer_expsubitems] in extension/ezjscore/settings/ezjscore.ini (class expSubitemsServerFunctions), and one content view. Every call needs a logged-in user with access to the admin and read access to the parent; keys are checked against the registry, and nothing from the request is ever used as a class, function or template name. ezjscore wraps every answer as { "error_text": "", "content": ... }.

• ezjscore/call/expsubitems::columns::<parent>: the columns the user may see (key, name, group, type, sortable, align, description, copy, builtin, order), defaults, presets (source: ini or user), the saved preference (visible, preset, page_size, saved), page_sizes, csv_export. On the reference installation, as the admin, the media root offers 138 columns (129 from the INI, 9 attribute columns):

  {"key":"pagetitle","name":"Page title in the browser","group":"SEO","type":"text","sortable":false,"align":"",
   "description":"The public site's title for the item's page, worked out as its pagelayout does, without rendering the page.",
   "copy":true,"builtin":false,"order":700}

• ezjscore/call/expsubitems::rows::<parent>::<limit>::<offset>::<sort key>::<order 0|1>[::<name filter>] with columns=a,b,c (POST or GET): the ezjscnode::subtree answer, every item with columns: { <key>: { v: <value>, h: "<html>" } } for the requested non-built-in keys. The sort key is a column key whose column sorts, or one of the old names (published_date, modified_date, node_id ...); anything else sorts as the parent does. Two children of the media root on the reference installation, with columns=parentnodeid,urlalias,pagetitle,childrencount,version,readingtime:

  {"parentnodeid":{"v":43,"h":"43"},"urlalias":{"v":"media/banners","h":"<code>media/banners</code>"},
   "pagetitle":{"v":"Banners - Fit & Healthy","h":"Banners - Fit &amp; Healthy"},"childrencount":{"v":4,"h":"4"},
   "version":{"v":1,"h":"1"},"readingtime":{"v":null,"h":""}}
  {"parentnodeid":{"v":43,"h":"43"},"urlalias":{"v":"media/clients-partners","h":"<code>media/clients-partners</code>"},
   "pagetitle":{"v":"Clients & Partners - Fit & Healthy","h":"Clients &amp; Partners - Fit &amp; Healthy"},
   "childrencount":{"v":12,"h":"12"},"version":{"v":1,"h":"1"},"readingtime":{"v":null,"h":""}}

• ezjscore/call/expsubitems::savepreference[::<parent>], POST preference=<json> (with the form token): { "visible": [...], "preset": "seo"|null, "page_size": 25, "presets": { "<id>": { "name", "columns" } } }, every key optional; stored for the parent's navigation part.

• content/subitemsexport/<parent>/(columns)/a,b,c/(sort)/<key>/(order)/0|1: the CSV (below).

PHP code can use the same pieces: expSubitemsColumnRegistry::instance() (availableColumns( $parent ), column( $key, $parent ), resolveColumns( $keys, $parent ), defaults(), presets(), sortFor()), and expSubitemsServerFunctions::columnValues( $nodes, $columns ) for the cells (it prefetches; prefetch() and cell( $column, $node ) are the two steps on their own).

Performance #

Only the visible columns are computed, and only for the rows of the page (the page size), never for the whole subtree. The 15 built-ins cost nothing extra: they come with the node, as before. Most other columns read the loaded node or object and cost no query.

The others load what they read once for the page, not once per row: before computing any cell, the rows function and the CSV export call prefetch( $nodes ) on every requested column with the page's nodes, and the column loads its data for all of them in one query, into the same per-request memo its value() reads. A prefetch only changes the number of queries, never a value (the tests compute every column both ways and compare), and one that fails just leaves the column to load per row. Loaded once per page:

Columns of one row that read the same data share it, and lookups that are the same for every row (the parent's name, a class's groups, a section, the public siteaccess's settings, a user's name) are done once per request. The rows function and the CSV export empty the memo first, so a persistent worker never answers from an earlier request. On MongoDB the grouped queries are skipped and the columns load per row. Still per row: Subtree size (a count over each whole subtree), Newest child, the URL alias based columns for the odd node whose alias the kernel leaves empty, the user columns, and Teaser (it renders an XML text block); keep the heavy ones for small pages.

A family class (expSubitemsFieldColumn) lists in prefetchSets() which Field= values read which set, and has a prefetch<Set>( $nodes ) for each; a column class of your own overrides prefetch().

Measured on the reference installation (SQLite, as the admin, on the command line; median of 5 runs, each in a fresh process): every one of the 114 non-built-in columns at once, for the first 10 children of the media root and for the first 50 and 100 nodes of the content tree.

CSV export #

Export CSV in Table options, or content/subitemsexport/<parent node id>/(columns)/a,b,c/(sort)/<key>/(order)/0|1 (view parameters; a ?columns= query string is not read): every child the user may read (up to CSVLimit, fetched 100 at a time), the given columns (without columns=: the user's saved choice, else the defaults), in order; the header row holds the column names. UTF-8 with BOM, comma separated, CRLF; cells starting with =, +, - or @ get a leading ' so a spreadsheet does not run them. Built-ins are included (except the thumbnail), lists are joined with , , dates written as Y-m-d H:i:s, bools as 1/0, sizes in bytes. The file is named after the parent. CSVExport=disabled removes the button and the view.

Where the choice is stored #

The user's choice is one eZPreferences value, admin_subitems_table, a compact JSON document:

{"v":1,"parts":{"ezcontentnavigationpart":{"visible":["name","urlalias","pagetitle"],"preset":null}},
 "page_size":25,"presets":{"mine":{"name":"Mine","columns":["name","nodeid"]}}}

The visible columns and the chosen preset are kept per navigation part (* when saved without a parent), the page size and the own presets once. It is kept under 4000 bytes on every database (the Oracle limit); a choice that does not fit is refused, not cut. The old rows-per-page preference (admin_list_limit) is still used while no page size was saved.

Where the code lives #

Tests #

php vendor/bin/phpunit tests/tests/kernel/classes/subitems/            # everything (100 tests)
php vendor/bin/phpunit tests/tests/kernel/classes/subitems/columns/    # the catalogue and the prefetch (64 tests)

The catalogue tests start the kernel on the admin siteaccess with the installation's own database and check every column against real nodes: the content root, the media root, the users root, the admin user, and nodes found by what they hold (an image, a file, tags, an XML text, relations, a rating). They check that every block builds, names a known group, type and field, that its sort field is accepted, that every column gives a JSON-safe value and one-line CSV text for four very different nodes, that columns that do not apply give null, that policies decide availability, that no node ever shows an empty URL alias, and the three worked examples above. expSubitemsPrefetchTest computes every column (and the attribute columns) for pages below the content, media and users roots once row by row and once with the page prefetch, as the admin and as anonymous, and requires the same cells; and that after the prefetch the rows of the prefetched columns need no query. A test that needs data the database does not have is skipped, not failed.

Related pages #

• Sub items table options (feature)
• Sub items: copy selected
• Sub items: hide and unhide in More actions
• Editing several items at once
• Where the page sizes live
• Content model and editing guide