Skip to content

ElementLibrary class

Bases: ABC

A library of user-defined visual elements.

An element library can declare any number of custom visual elements.

In order to use those elements you must register the element library using the function Gui.add_library().

An element library can mix static and dynamic elements.

Methods

get_data()

get_data(
    library_name: str,
    payload: t.Dict,
    var_name: str,
    value: t.Any,
) -> t.Optional[t.Dict]

TODO Called if implemented (i.e returns a dict).

Parameters:

Name Type Description Default
library_name str

The name of this library.

required
payload dict

The payload send by the createRequestDataUpdateAction() front-end function.

required
var_name str

The name of the variable holding the data.

required
value any

The current value of the variable identified by var_name.

required

get_elements() abstractmethod

get_elements() -> t.Dict[str, Element]

Return the dictionary holding all visual element declarations.

The key for each of this dictionary's entry is the name of the element, and the value is an instance of Element.

The default implementation returns an empty dictionary, indicating that this library contains no custom visual elements.

get_js_module_name()

get_js_module_name() -> str

Return the name of the JavaScript module.

The JavaScript module is the JavaScript file that contains all the front-end code for this element library. Typically, the name of JavaScript modules uses camel case.
This module name must be unique on the browser window scope: if your application uses several custom element libraries, they must define a unique name for their JavaScript module.

The default implementation transforms the return value of get_name() in the following manner:

  • The JavaScript module name is a camel case version of the element library name (see get_name()):
    • If the library name is "library", the JavaScript module name defaults to "Library".
    • If the library name is "myLibrary", the JavaScript module name defaults to "Mylibrary".
  • If the element library name has underscore characters, each underscore-separated fragment is considered as a distinct word:
    • If the library name is "my_library", the JavaScript module name defaults to "MyLibrary".

Returns:

Type Description
str

The name of the JavaScript module for this element library.

str

The default implementation returns a camel case version of self.get_name(),

str

as described above.

get_name() abstractmethod

get_name() -> str

Return the library name.

This string is used for different purposes:

  • It allows for finding the definition of visual elements when parsing the page content.
    Custom elements are defined with the fragment <|<library_name>.<element_name>|> in Markdown pages, and with the tag <<library_name>:<element_name>> in HTML pages.

  • In element libraries that hold elements with dynamic properties (where JavaScript) is involved, the name of the JavaScript module that has the front-end code is derived from this name, as described in get_js_module_name().

Returns:

Type Description
str

The name of this element library. This must be a valid Python identifier.

Element libraries with the same name

You can add different libraries that have the same name.
This is useful in large projects where you want to split a potentially large number of custom visual elements into different groups but still access them from your pages using the same library name prefix.
In this situation, you will have to implement get_js_module_name() because each JavaScript module will have to have a unique name.

get_query()

get_query(name: str) -> str

Return an URL query depending on the resource name.
Default implementation returns the version if defined.

Parameters:

Name Type Description Default
name str

The name of the resource for which a query should be returned.

required

Returns:

Type Description
str

A string that holds the query part of an URL (starting with ?).

get_resource()

get_resource(name: str) -> Path

TODO Defaults to return None? Returns a path for a resource name. Resource URL should be formed as /taipy-extension// with(see get_resource_url) - being the name parameter - the value returned by get_name()

Parameters:

Name Type Description Default
name str

The name of the resource for which a local Path should be returned.

required

get_resource_url()

get_resource_url(resource: str) -> str

TODO

get_scripts()

get_scripts() -> t.List[str]

Return the list of the mandatory script file pathnames.

If a script file pathname is an absolute URL it will be used as is.
If it's not it will be passed to get_resource() to retrieve a local path to the resource.

The default implementation returns an empty list, indicating that this library contains no custom visual elements with dynamic properties.

Returns:

Type Description
List[str]

A list of paths (relative to the element library Python implementation file or

List[str]

absolute) to all JavaScript module files to be loaded on the front-end.

List[str]

The default implementation returns an empty list.

get_styles()

get_styles() -> t.List[str]

TODO Returns the list of resources names for the css stylesheets. Defaults to []

get_version()

get_version() -> t.Optional[str]

The optional library version

Returns:

Type Description
Optional[str]

An optional string representing the library version.

Optional[str]

This version will be appended to the resource URL as a query arg (?v=)

on_init()

on_init(gui: Gui) -> t.Optional[t.Tuple[str, t.Any]]

Initialize this element library.

This method is invoked by Gui.run().

It allows to define variables that are accessible from elements defined in this element library.

Arguments gui: The Gui instance.

Returns:

Type Description
Optional[Tuple[str, Any]]

An optional tuple composed of a variable name (that must be a valid Python

Optional[Tuple[str, Any]]

identifier), associated with its value.

Optional[Tuple[str, Any]]

This name can be used as the name of a variable accessible by the elements defined

Optional[Tuple[str, Any]]

in this library.

Optional[Tuple[str, Any]]

This name must be unique across the entire application, which is a problem since

Optional[Tuple[str, Any]]

different element libraries might use the same symbol. A good development practice

Optional[Tuple[str, Any]]

is to make this variable name unique by prefixing it with the name of the element

Optional[Tuple[str, Any]]

library itself.

on_user_init()

on_user_init(state: State)

Initialize user state on first access.

Arguments state: The State instance.