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 |
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 |
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/name
parameter
- get_name()
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
The name of the resource for which a local Path should be returned. |
required |
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. |