# WhiteCollar items

WhiteCollar scripts return an object (described in details in the whiteCollar article) containing an array named getItems.

This article details all the properties that each item can have, for example:

{
    selector: '.article',
    extractors: {
        title: 'h2',
        uri: WC.getUri(),
        media: 'img',
        date: getDate
        pocket: {
            className: 'mrf-article--home'
        }
    },
    modifiers: []
}

# `selector`

Mandatory string passed to querySelectorAll under the hood, to select all the articles part of the group.

It can contain different comma separated selectors that wrap the information of every article (e.g. #latest-news ARTICLE, .featured-items .post).

However, it is recommended to keep it short and simple to structure each block of the section page with precision. Having different specific selectors separated contributes to the use of content groups and layouts, and it also eases the edition of the code. For example:

{
    selector: '.post',
    extractors: {
        title: '.entry-title',
        uri: '.entry-title > a',
        media: 'img',
        excerpt: '.entry-content p'
    },
    modifiers: []
},
{
    selector: '.widget.mks_author_widget',
    extractors: {
        title: '.widget-title',
        uri: '.mks_author_link',
        media: 'img',
        excerpt: '.mks_author_link',
        pocket: {}
    },
    modifiers: []
}

Type

Instead of a string, selector can be a custom function returning a NodeList directly.

Contribution needed

If you use a custom funtion returning a NodeList for selector, please edit this file (opens new window) to add your example, or send it to the Ada team.

Thank you!

# `extractors`

Mandatory object containing all the instructions on how to extract an item properties. All extractors instructions are applied to each article node found by the selector.

Only extract properties that are needed for the section page display. If the article author appears on the page, but is not required for the marfeelized section, don't add it.

WC Library

For all the properties listed below, whenever you need to write a function, be sure to check the WC library, in case the behavior you need is already implemented.

If do write a custom function, evaluate if it can become part of the library!

# `title`, `uri`, `subtitle`, `author`, `excerpt`, `media`

Those 6 properties have exactly the same type: DOMString or function returning a String.

title and uri are mandatory, but subtitle, author, excerpt, media are optional.

Strings will be passed down to a querySelector function. Functions directly manipulate the article node and return the relevant item property. You can create the functions from scratch, or use existing ones from the WC library.

Examples:

As DOMString, for example, use an html element selector:

title: 'a'

As DOMString, for example, use a class selector:

subtitle: '.detail'

As DOMString, for example, use two comma-separated selectors, the second one as fallback:

author: '.author, .auth'

As a function, for example, use a WC library function:

uri: WC.getUniqueUri()

As a function, for example, use a custom function:

function getMedia(node) {
    var img = WC.qs('img', node);
    if (img) {
        return img.getAttribute('data-src') || img.src;
    }
}
...
media: getMedia
...

WARNING

Selecting properties with a string lets you take advantage of Gutenberg's optimizations.

When using functions, the return value is the final value. You manage trimming and sanitizing.

TIP

If the same extractors are used in different selectors, create a commonExtractors object and reuse it where needed:

...
var commonExtractors = {
    title: 'h3 > a',
    uri: 'h3 > a',
    media: '.entry-thumb',
    author: '.td-post-author-name'
};
...
{
    selector: '.td-big-grid-post',
    extractors: R.merge(commonExtractors, {
        pocket: {
            key: 'big'
        }
    });
}

# `isExtractable`

Optional Boolean or function returning a Boolean, defaults to true. This is useful for items that should appear in a section page, but that don't lead to a marfeelized page.

See usage examples in the whiteCollar general guide.

# `pocket`

Optional Object or function returning an Object, defaults to empty.

Possible values:

order: Number. "Suggests" rank of group. See order vs. position for an example.
position: Number. Forces rank of group at that exact number. Synonym with the legacy apiOrder. See order vs. position for an example.
key: String. Name of the Content group to reference in the layout descriptor.
className: String or Array of Strings. Applies to the article node in the section page, for styling purposes.
removeBalconAd: Boolean. For content groups that support it, don't include any ad placement between the items. It only works if the adDealer in mosaic is disabled. Check the content groups catalog to see which ones support this option.
forceStrategy: String. It determines how the image of the article is retrieved on the section page. All the supported strategies are in the MediaSelector enum (opens new window). Whenever possible, use this option instead of the defaultMediaSelectorStrategy flag in definition.jon. This way, the strategy is only applied to the specific group of articles that need it.
html: Used for widgets, to determine the HTML of a group - See cheatcc's whiteCollar (opens new window) or tycsports.com (opens new window).
mosaicHtml: String or function. Lets you append any string to the item. Read more.
mosaicHtmlPosition: String. Lets you choose the mosaicHtml position. Read more.
layoutClasses: String. Classes to replace the default ones used by the template. You can write the classes directly, or use an existing shortcut (opens new window).
template: deprecated. String to define the layout path for rendering. See layout descriptor.
balcon: deprecated. String to define a content group. See key.
widget: deprecated String equivalent to key.
disableCounter: Only ranking's layouts Boolean. Disables counter number from the ranking layout.
showRankingAd: Only ranking's layouts Boolean. Adds an ad after second article.

Custom pocket attributes

If you define a new, custom layout, you can add any properties to the pocket of the items consuming this layout, and use those properties in the template you create.

See for example 01net.com's customLinks pocket property (opens new window).

`pocket` in whiteCollar vs. `pocket` in layoutDescriptor

Those 2 objects are unrelated. The whiteCollar's pocket is about the article item, while the layout descriptor's pocket is about the layout.

# `modifiers`

Optional array. Same specification as the global modifiers array.

# WhiteCollar items

# selector

# extractors

# title, uri, subtitle, author, excerpt, media

# isExtractable

# pocket