# Filters and hooks - Labelline 1.x documentation

> Read a product's labels in code, add conditions, placeholders, kinds of label and places, and change the markup, the limit and the sale badge.

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

```php
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.

```php
// "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}`.

```php
// {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). |

```php
// 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.

Source: https://extendiment.com/plugins/labelline/docs/1.x/filters-and-hooks