This article presents the usage guidance principles that Marfeel follows for whiteCollar.
Usage example whiteCollar 2.0
WC is the library name, just like $ for Jquery.
To use whiteCollar 2.0, Marfeel engineers need to pass an array to getItems instead of a function. Marfeel engineers no longer need to define them because everything is already specified inside the getItems.
getItems are an Array of Object and every Object defines a different group of Items.
The first property of the Object is a selector where Marfeel specifies the selector used to query the items. This String is then passed to a document.querySelectorAll under the hood, where Marfeel engineers can write everything they would write in querySelectorAll.
Even though different comma separated selectors can be placed here, it's better to keep it short and simple.
The next property is extractors. This is where the whiteCollar is instructed on how to extract the item properties.
The default and most simple method is to specify a selector, just like with the selector property. In addition, in this case, the string is passed under the hood to a querySelector function. The same recommendations specified for the selector property apply here.
The other method is to use a function in which you can manipulate the articleNode to get the item property back. Caution should be exercised because when the selector is used, Gutenberg takes care of everything, however, when a function is passed, it assumes that you know what you are doing and passes the articleNode and expects you to return the elaborated property as in the example (excerpt) above.
Not all the extractors behave like this, as presented in the following detailed list:
title: String (selector) or Function
subtitle: String (selector) or Function
media: Empty String (null media), String (selector), Object (like in the default whiteCollar), or leave it undefined to so it will default to the "IMG" selector
uri: String (selector) or Function
date: String (selector) or Function
excerpt: String (selector) or Function
author: String (selector) or Function
isExtractable: Boolean or Function
allowDifferentHost: Boolean or Function
pocket: Object or Function
The last property is modifiers. It is a property of both the getItems Objects and of document.whiteCollar.
It accepts an array of functions or a single function which manipulates the array of items.
The modifiers passed to getItems are applied only on the items selected by selector and the ones passed to whiteCollar are applied to all the items.
The modifiers list should be passed inside an Array, or directly if it's only one modifier.
The following is an example of a more complex scenario:
All modifiers are functions returning a function. This should be noted and kept in mind in cases where you build your own.
Limits the number of the extracted articles according to the specified number.
Filters all the articles which are consecutives and have the same property value as the one specified as the argument.
If no argument is specified, it defaults to URI.
Set the item "isExtractable" to false when the checker function returns true.
Filters all the items for the URI which contains any of the strings specified in the blacklist Array.
The curried function checks if "content" is contained by "container."
If no argument is specified, it uses the default extractor which takes the first string of the pathname.
If no argument is specified, it uses the default extractor which takes the number from "/page/(number)"
Filters all items of an array which are falsy values ("", 0, NaN, null...).
Converts array-like objects to Array.
Identify all the groups of items with the same structure in the tenant page. Every group will be mapped into an Object of the Array passed to getItems.
Once you have defined the selector of every group, you can proceed to define the extractors of every group.
If you find yourself writing some custom function that you think could be useful to someone else in the future, be sure to add it to the library. For more information, see the How to contribute section.
How to contribute
All the library functions are defined in "wcLibrary.js" in Gutenberg which makes significant use of Ramda.js. To better understand the source code, see the Ramda.js documentation for more information. In addition, remember that it's possible to use both Ramda and Jquery inside the whiteCollar.
The purpose of this new version is to avoid code duplication, so every time you find yourself writing some custom function that is already used in another file or going to be used in the future, be sure to add it to wcLibrary.js.