Filters and hooks

Labelline's hooks are WordPress filters and actions. Put the examples in a small custom plugin or your child theme's functions.php. Labelline Pro is built on these same hooks.

A product's labels in code

use Extendiment\Labelline\Matcher;
use Extendiment\Labelline\Renderer;

// The labels a product shows in the shop, in order, with their text filled in.
foreach ( Matcher::for_product( $product, 'loop' ) as $item ) {
	echo esc_html( $item['text'] ); // $item['label'] is the Label (id, title, priority, data)
}

// The label layer for an image (absolutely positioned: put it inside a positioned wrapper).
echo Renderer::layer( Matcher::for_product( $product, 'single' ), 'single', $product );

A label's settings are in $label->data: text, sr_text, shape, background, color, font_size, position, offset_x, offset_y, places, match, conditions (each type, op, value), plus any settings an add-on keeps.

Conditions

labelline_conditions

Add a condition type. check gets the value, the comparison, the product and the place, and answers for the positive comparison; comparisons named is_not, not_in or starting with not_ turn the answer around.

// "Weight over N kg".
add_filter( 'labelline_conditions', function ( $conditions ) {
	$conditions['heavy'] = array(
		'label'  => __( 'Weight', 'my-plugin' ),
		'group'  => __( 'Product', 'my-plugin' ),
		'ops'    => array( 'over' => __( 'over', 'my-plugin' ), 'not_over' => __( 'not over', 'my-plugin' ) ),
		'field'  => 'number', // none, number, choices, terms, products, range, dates or text
		'min'    => 0,
		'suffix' => 'kg',
		'check'  => function ( $value, $op, $product, $place ) {
			return (float) $product->get_weight() > (float) $value;
		},
	);
	return $conditions;
} );

Other keys: options (for choices), taxonomy (for terms), step, default, volatile (true, or a callable: the answer can change between page views, for example with the customer or the time, so it's never cached), stock (a stock condition: left off the product page while Stockline is active), sale (the comparisons that make a sale label) and summary (a callable that describes the condition on the labels list).

Placeholders

labelline_placeholders

Add a placeholder. value returns the text for a product, or '' when it has nothing to show (the label is then left off that product). A placeholder can take an argument after a colon, {key:argument}.

// {origin}: the product's "origin" custom field.
add_filter( 'labelline_placeholders', function ( $placeholders ) {
	$placeholders['origin'] = array(
		'label'  => __( 'Where it was made', 'my-plugin' ),
		'sample' => 'Portugal',
		'value'  => function ( $product, $arg ) {
			return (string) $product->get_meta( 'origin' );
		},
	);
	return $placeholders;
} );

Kinds of label and places

• labelline_kinds: what a label is made of. Labelline's is text; register a kind with a render( $label, $text, $product, $place ) callable that returns the label's inner HTML (Labelline Pro adds image and icon).
• labelline_places: where a label can show. Labelline's are loop and single; register a place and show labels there yourself with Matcher::for_product( $product, 'your_place' ) and Renderer::inline() or Renderer::layer() (Labelline Pro adds title and cart).

Changing what shows

Hook	What it's for
labelline_product_labels	$labels, $product, $place: the labels a product shows, before placeholders are filled in and the limit applies. Add, remove or reorder Label objects.
labelline_max_labels	$max, $product, $place: the limit (0 for none).
labelline_hide_sale_flash	$hide, $product, $place: whether WooCommerce's sale badge is hidden.
labelline_discountline_sales	Whether Discountline's discounts count as sales.
labelline_placeholder_value	$value, $key, $product, $arg: a placeholder's filled-in value. Return '' to leave the label out, e.g. empty price and saving for shoppers who can't see prices.
labelline_label_html	$html, $label, $text, $product, $place: one label's markup.
labelline_label_classes	$classes, $label, $place: a label's classes.
labelline_layer_html	$html, $items, $place, $product: the whole layer over an image.
labelline_label_css	$rules, $label: the CSS rules for a label's colours and size. Rules can only set --labelline-* properties to a hex colour or a length, on class and element selectors; anything else is dropped, including rules inside @media and rules with a comment in front.
labelline_enqueue_styles	Whether to load the stylesheet on a page (default: whenever a label is on).

// No more than one label on the product page.
add_filter( 'labelline_max_labels', function ( $max, $product, $place ) {
	return 'single' === $place ? 1 : $max;
}, 10, 3 );

Hooks for add-ons

Hook	What it's for
labelline_loaded	Fires once Labelline has loaded (on plugins_loaded, only with WooCommerce active). LABELLINE_VERSION is defined from then on.
labelline_sanitize_label	$clean, $raw: clean and keep a setting of your own on a label. Labelline's own settings in the result are ignored.
labelline_label_problem, labelline_problem_message	Hold a label back (return a code) and explain why in the admin.
labelline_label_volatile	Never cache a label's answer.
labelline_editor_boxes, labelline_editor_rows	Add boxes to the label editor, and form table rows at the end of a box ($section, $label). Name fields labelline[your_setting].
labelline_posted_label	$data, $posted, $stored: read your settings from the editor (the nonce and capability are checked).
labelline_editor_config, labelline_editor_enqueue	The editor script's data, and enqueue your scripts with it. In JavaScript, add to window.labellineRender.kinds, listen for labelline:collect (jQuery, on document) to add your settings to the preview, and trigger labelline:redraw.
labelline_settings	The settings fields on WooCommerce → Settings → Products → Labels.

Labels nobody can show

A label whose kind, a condition or a placeholder no active plugin provides (an add-on's, while the add-on is inactive) is kept with all its settings but never shown, rather than shown without its condition or with its placeholder printed as it is. The labels list marks it, and the editor says why. Places no plugin provides are simply not used.

The code documents each hook's arguments where it's applied.