Functions

The public API of Elio Blocks: the functions that register providers and condition icons, and the ones the blocks read what they print with. Generated from the code of Elio Blocks 1.0.0.

elio_blocks_register_provider()

function elio_blocks_register_provider( Provider $provider ): bool

Registers a provider: an organization the data comes from, and what it serves.

Must be called on the 'elio_blocks_init' action. A provider the registry refuses (malformed slug, label or credential name, attribution URL not http(s), duplicate slug, registry already locked) gets a _doing_it_wrong() notice, as register_block_type() does.

A provider that needs to identify the site (an API key, an account, a contact address) declares its credentials: the settings page gives it a card with their fields, and its adapters get their values in fetch(). One whose license asks for a credit wherever its data is shown declares its attribution: the provider-attribution block prints it in the reports. What it serves are its adapters, one per domain: a WeatherForecastAdapterInterface for the weather forecast.

use ElioBlocks\Provider\Provider;
use ElioBlocks\Provider\ProviderAttribution;
use ElioBlocks\Provider\ProviderCredential;

elio_blocks_register_provider( new Provider(
    'my-provider',
    'My Provider',
    array( new ProviderCredential( 'api_key', __( 'API Key', 'my-plugin' ), required: true, secret: true ) ),
    new ProviderAttribution( 'https://my-provider.example/', 'CC BY 4.0', 'https://creativecommons.org/licenses/by/4.0/' ),
    array( new MyWeatherForecastAdapter() ),
) );

or with a class of its own extending Provider, as the built-in OpenMeteo. Each credential can also be set with the constant ELIO_BLOCKS_{SLUG}_{NAME} (uppercased, hyphens as underscores).

Parameters

• $provider Provider: The provider, with its credentials, attribution and adapters.

Returns bool: True if the provider was registered, false otherwise.

Since 0.1.0
Since 0.4.0: Takes a Provider, which holds its credentials, attribution and adapters, in place of a slug and an array. elio_blocks_register_weather_forecast_provider() is gone: an adapter is one of the adapters of its provider.

Source

elio_blocks_register_condition_icon_collection()

function elio_blocks_register_condition_icon_collection( string $slug, array $args ): bool

Registers a condition icon collection, a namespace for icons.

Must be called on the 'elio_blocks_init' action, before the icons of the collection.

Parameters

• $slug string: Collection slug: lowercase letters, digits, hyphens, underscores.
• $args array<string, mixed>
  • label string: Required. Human-readable label, shown in the editor.
  • description string: Optional. Human-readable description.
  • stroke_width float: Optional. Stroke width the stroke icons are drawn with, what the condition icon block applies unless set on the block. Default 2.

Returns bool: True if the collection was registered, false otherwise.

Since 0.1.0
Since 0.2.0: Takes a stroke_width.

Source

elio_blocks_unregister_condition_icon_collection()

function elio_blocks_unregister_condition_icon_collection( string $slug ): bool

Unregisters a condition icon collection and its icons.

Must be called on the 'elio_blocks_init' action.

Parameters

• $slug string: Collection slug.

Returns bool: True if the collection was unregistered, false otherwise.

Since 0.1.0

Source

elio_blocks_register_condition_icon()

function elio_blocks_register_condition_icon( string $name, array $args ): bool

Registers a condition icon in a registered collection.

Must be called on the 'elio_blocks_init' action.

Parameters

• $name string: Qualified name, "collection/icon-name".
• $args array<string, mixed>
  • content string: SVG markup. Required unless file_path is given.
  • file_path string: Absolute path of an .svg file, read when the icon is first shown.
  • label string: Optional. Human-readable label.
  • style string: Optional. 'fill' (default) or 'stroke': a stroke icon takes the stroke width of the block.
  • conditions array: Optional. Conditions the icon represents: array( WMO condition slug (WmoConditionCodes), 'day'|'night'|'all' ) pairs. Each pair is represented by one icon per collection; a block shows no icon for a condition its collection does not represent.

Returns bool: True if the icon was registered, false otherwise.

Since 0.1.0

Source

elio_blocks_unregister_condition_icon()

function elio_blocks_unregister_condition_icon( string $name ): bool

Unregisters a condition icon.

Must be called on the 'elio_blocks_init' action.

Parameters

• $name string: Qualified icon name.

Returns bool: True if the icon was unregistered, false otherwise.

Since 0.1.0

Source

elio_blocks_add_icon_to_sprite()

function elio_blocks_add_icon_to_sprite( string $name, string $svg ): void

Adds an icon to the sprite of the page, the symbols condition icons point at.

Condition-icon blocks add the icons they show; the report block around them prints the sprite (elio_blocks_render_icon_sprite()). An icon the page has already is not printed again.

Parameters

• $name string: Qualified icon name.
• $svg string: Sanitized SVG markup, the content of elio_blocks_get_condition_icon().

Since 0.1.0

Source

elio_blocks_render_icon_sprite()

function elio_blocks_render_icon_sprite(): string

Returns the sprite of the icons added since the last call and not printed yet.

For the report block, after its inner blocks rendered: printed before them, the symbols reach the browser before the icons using them.

Returns string: Hidden <svg> holding one <symbol> per icon, empty when there is none.

Since 0.1.0

Source

elio_blocks_get_weather_report_interactivity_state()

function elio_blocks_get_weather_report_interactivity_state(): array

Returns the state of the elio/weather-report store, for wp_interactivity_state().

The weather forecast endpoint, how long a weather forecast stays fresh, the refresh interval, and the derived values (state.*) the blocks of a report print.

Returns array<string, mixed>

Since 0.1.0

Source

elio_blocks_get_weather_report_interactivity_context()

function elio_blocks_get_weather_report_interactivity_context( WP_Block $block ): array

Returns the interactivity context of a weather report block (data-wp-context).

Its location, provider and units, the signature of the requests its view script sends, and its weather forecast, fetched now (or read from the cache). Not the block context ($block->context) the report gives its inner blocks.

Parameters

• $block WP_Block: Weather report block being rendered.

Returns array<string, mixed>

Since 0.1.0

Source

elio_blocks_get_current_conditions()

function elio_blocks_get_current_conditions(): ?array

Returns the current conditions of the weather report being rendered.

An item like the rows of elio_blocks_get_forecast_items() (temperature, condition_icons…); null when the report has no weather forecast.

Returns array<string, mixed>|null

Since 0.1.0

Source

elio_blocks_get_forecast_items()

function elio_blocks_get_forecast_items( string $type, int $count ): array

Returns the rows of a forecast list of the weather report being rendered.

Hourly rows start at the hour in progress. Empty when the report has no weather forecast.

Parameters

• $type string: 'daily' or 'hourly'.
• $count int: Number of rows.

Returns list<array<string, mixed>>

Since 0.1.0

Source

elio_blocks_get_condition_icon()

function elio_blocks_get_condition_icon( string $name ): ?array

Returns an icon of the weather report being rendered.

Items point to their icon by qualified name, in condition_icons[ collection ]. Null when the weather forecast of the report has no such icon.

Parameters

• $name string: Qualified icon name ("elio/sun").

Returns array{content: string, style: string}|null: Sanitized SVG markup, and 'fill' or 'stroke'.

Since 0.1.0

Source

elio_blocks_get_condition_icon_collection()

function elio_blocks_get_condition_icon_collection( ?string $block_collection, ?string $report_collection ): string

Returns the icon collection a condition-icon block shows.

Its own, else the one of its report, else the one of the site, else the plugin one ("elio"). A collection that is not registered counts as not chosen.

Parameters

• $block_collection string|null: The iconCollection attribute of the block.
• $report_collection string|null: The elio/reportIconCollection block context.

Returns string: Collection slug.

Since 0.1.0

Source

elio_blocks_get_condition_icon_stroke_width()

function elio_blocks_get_condition_icon_stroke_width( string $collection ): float

Returns the stroke width the stroke icons of a collection are drawn with.

What a condition-icon block applies to its symbol unless its strokeWidth attribute says otherwise: 2 for a collection that declares none, or that is not registered.

Parameters

• $collection string: Collection slug.

Returns float: Stroke width, in the units of the 24×24 viewBox.

Since 0.2.0

Source

elio_blocks_get_weather_forecast_attribution()

function elio_blocks_get_weather_forecast_attribution( string $provider ): ?array

Returns the credit the weather forecast of a provider is shown with, as the license of the provider asks.

Null when the provider asks for none, or serves no weather forecast.

Parameters

• $provider string: Provider slug (the elio/reportProvider block context), empty for the site default.

Returns array{name: string, url: string, license: string, license_url: string}|null: Label of the provider, its site, the license of its data and its page; to escape.

Since 0.2.0

Source