Contribution API

The Chartlets contribution API is used by both application providers and contributors:

• Application providers implement specific contributions for their application using Contribution as a base class.
• Application contributors use the instantiate and parameterize the specific contributions and implement the functions to create the contributions' user interface (layout) and their event handlers (callbacks).

chartlets.Contribution

Bases: ABC

Base class for specific application contributions.

Derived classes typically add attributes that allow customizing the appearance of the contribution in the user interface. The user-provided values for such attributes determine the initial state of the contribution when it is rendered for the first time.

Parameters:

Name	Type	Description	Default
name	str	A name that should be unique within an extension.	required
initial_state		contribution specific attribute values.	{}

callback(*args)

Provide a decorator for a user-provided callback function.

Callback functions are event handlers that react to events fired by the host application state or by events fired by related components provided by this contribution's layout.

The first parameter of the decorated function must be a positional argument. It provides an application-specific context that is used to allow for access server-side configuration and resources. The parameter should be called ctx.

Other parameters of the decorated function are user-defined and must have a corresponding chartlets.Input argument in the layout decorator in the same order.

The return value of the decorated function is used to change the component or the application state as described by its Output argument passed to the decorator. If more than out output is specified, the function is supposed to return a tuple of values with the same number of items in the order given by the Output arguments passed to the decorator.

Parameters:

Name	Type	Description	Default
args	Channel	chartlets.Input, chartlets.State, and Output objects that define sources and targets for the parameters passed to the callback function and the returned from the callback function.	()

Returns:

Type	Description
Callable[[Callable], Callable]	The decorated, user-provided function.

layout(*args)

Provides a decorator for a user-provided function that returns the initial user interface layout.

The layout decorator should only be used once for given contribution instance.

The decorated function must return an instance of a chartlets.Component, usually a chartlets.components.Box that arranges other components in some layout.

The first parameter of the decorated function must be a positional argument. It provides an application-specific context that is used to allow for access server-side configuration and resources. The parameter should be called ctx.

Other parameters of the decorated function are user-defined and must have a corresponding chartlets.Input or chartlets.State arguments in the layout decorator in the same order.

Parameters:

Name	Type	Description	Default
args		chartlets.Input or chartlets.State objects that define the source of the value for the corresponding parameter of the decorated function. Optional.	()

Returns:

Type	Description
Callable[[Callable], Callable]	The decorator.

to_dict()

Convert this contribution into a JSON serializable dictionary.

May be overridden by subclasses to allow for specific JSON serialization.

Returns:

Type	Description
dict[str, Any]	A JSON serializable dictionary.

chartlets.Input

Bases: Channel

Describes the source of a parameter value for the user-provided layout and callback functions. Input instances are used as arguments passed to the layout and callback decorators.

An Input describes from which property in which state a parameter value is read. According state changes trigger callback invocation.

Parameters:

Name	Type	Description	Default
id	str | None	Value of a component's "id" property. Used only if source is "component".	None
property	str | None	Name of the property of a component or state. To address properties in nested objects or arrays use a dot (.) to separate property names and array indexes.	None
source	Link | None	One of "component" (the default), "container", or "app".	None

chartlets.State

Bases: Input

Describes the source of a parameter value for the user-provided layout and callback functions. State instances are used as arguments passed to the layout and callback decorators.

Just like an Input, a State describes from which property in which state a parameter value is read, but according state changes will notÜ trigger callback invocation.

Parameters:

Name	Type	Description	Default
id	str | None	Value of a component's "id" property. Used only if source is "component".	None
property	str | None	Name of the property of a component or state. To address properties in nested objects or arrays use a dot (.) to separate property names and array indexes.	None
source	Link | None	One of "component" (the default), "container", or "app".	None

chartlets.Output

Bases: Channel

Describes the target of a value returned from a user-provided callback function. Output instances are used as arguments passed to the callback decorators.

An Output describes which property in which state should be updated from the returned callback value.

Parameters:

Name	Type	Description	Default
id	str | None	Value of a component's "id" property. Used only if source is "component".	None
property	str | None	Name of the property of a component or state. To address properties in nested objects or arrays use a dot (.) to separate property names and array indexes.	None
target	Link | None	One of "component" (the default), "container", or "app".	None

chartlets.Channel

Bases: ABC

Base class for Input, State, and Output. Instances are used as argument passed to the layout and callback decorators.