doc/gui/extension/README.md
This directory contains all the files needed to build, package and deploy an example of a custom element library for Taipy GUI.
This example demonstrates several types of custom visual elements including static and dynamic elements, handling properties with different types.
README.md: This file.
main.py: A Python script that can be used to run a Taipy GUI application that
has pages using the example element library.
See the section on Testing the library for more information.
pyproject.toml: The Python project settings file that can be used to package
the example library, if needed.
See the section on Packaging for more information.
Manifest.in: The Python package manifest that lists the files to include or remove.
All files that are not Python source files and that you want to be integrated into your package should be listed. See Manifest.in for more information.
example_library/: The directory where the whole extension library example is located.
__init__.py: Makes example_library a potential Python package.example_library.py: The source file where the custom library is declared.front-end/: The directory that contains all the JavaScript source files and
build directions.
package.json: JavaScript dependency file used by npm to build the front-end part of
the extension library.webpack.config.js: This file is used for building the JavaScript bundle that
holds the Web components code that is used in the generated pages.tsconfig.json: The configuration file for TypeScript transpilation.src/: The source code for the Web components used by the custom elements.
index.ts: The entry point of the generated JavaScript module.ColoredLabel.tsx: A simple example of a React component that displays
the value of a property as a string where each consecutive character has
a different color.scripts/: A directory containing NodeJS scripts used by the build process.This section explains how to build the custom extension library.
To complete the build of the extension library, we need the following tools:
Python 3.9 or higher;
Taipy GUI 2.2 or higher;
Node.js 18.0 or higher: a JavaScript runtime.
This embeds npm, the Node Package Manager.
The build process needs that you set the environment variable TAIPY_DIR to the location of
the Taipy installation:
taipy repository,
this variable should be set to the path of the directory two levels above the directory where this
README file is located, then down to the "taipy" directory (i.e., the result of the Unix command
"readlink -f `pwd`/../../taipy").pip show taipy-gui.You can check that the setting is correct by verifying that the directory "$TAIPY_DIR/taipy/gui/webapp" exists.
A way to set this variable once and for all for your environment is to add the line:
TAIPY_DIR=<taipy_installation_directory>
to the file `example_library/front-end/.env'. This file, if present, is read by the build process to initialize the environment variable.
This example has all the important settings, ready to be built and used to run a Taipy GUI application using this extension or even to make it a regular Python package.
It is however important to understand the relationship between some of these settings so that if you reuse this code, you can change some values and know what the impact of these changes is.
Extension Library directory: in this example, this is "example_library".
The name of the directory where all the Python and front-end code is stored.
This is the name of the Python package to be imported by the Taipy GUI application script.
This directory needs to hold a file called __init__.py so that Python recognizes this
directory as a valid Python package directory.
This directory name must appear in the paths that are used in the implementation
of the method get_scripts() of the ElementLibrary subclass. This is how
Taipy GUI finds the JavaScript module to be loaded.
It is the name of the Python package to be built, as indicated in the file
pyproject.toml where it appears as the value of the "name" key of the "project" table.
It is part of the pathname to be included when building the Python package, in
the manifest file MANIFEST.in.
Extension Library name: in this example, this is "example".
The name of the extension library.
<|example.<element_name>> fragment.output.library.name in
the webpack configuration file, is
derived from this name if the method get_js_module_name() of the ElementLibrary
subclass is not overloaded: the JavaScript module name defaults to a camel case version
of the extension library name.Front-end code directory: in this example, this is "front-end".
The name of the directory where all the front-end code is stored.
get_scripts() of the ElementLibrary subclass. This is how
Taipy GUI finds the JavaScript module to be loaded.MANIFEST.in.JavaScript bundle file name: in this example, this is "exampleLibrary.js".
The name of the file where the front-end code is compiled.
ElementLibrary.get_scripts().output.filename in the
webpack configuration file.MANIFEST.in. In this example, the manifest file indicates
that all the files located in example_library/front-end/dist should be
packaged, so we don't need to explicitly refer to the bundle file name.Note that the path to the file also relies on the output directory setting (the
value for output.path) in the
webpack configuration file and
appears also in MANIFEST.in
The JavaScript module name: in this example, this is "Example".
The name of the JavaScript module.
output.library.name in the
webpack configuration file.ElementLibrary.get_js_module_name(). In this example,
we rely on the default implementation, which returns a camel case version of the element
library name (therefore "example" is transformed to "Example").When all configuration files have been properly set (which is the case in this example) and the "TAIPY_DIR" variable is set, we can build the JavaScript module file:
Set your directory to example_library/front-end
Install the Taipy GUI JavaScript bundle and the other dependencies:
You must run the command:
npm install
This command will fail with a message indicating that the Taipy GUI 'webapp' directory could not be found if the "TAIPY_DIR" environment variable was not set properly.
You can now build the custom element library JavaScript bundle file:
npm run build
This generates the bundle exampleLibrary.js in the dist directory (if you have not
changed the output settings in webpack.config.js). This file contains the definition
for the Example JavaScript module.
Next to this README file, you can find a Python script called main.py that
creates a Taipy GUI application with a page that demonstrates the various
elements defined by this extension library example.
To execute this application, you can run:
python main.py
(prefixed by pipenv run if you are using pipenv)
You can create an autonomous Python package for this extension library.
The following two simple steps must be performed:
pip install build
pipenv run if you are using pipenv)python -m build
pipenv run if you are using pipenv)This generates an autonomous Python package that contains both the back-end and the front-end code for the extension library.