https://github.com/avaiga/guiext-template
Template repository for creating a Taipy GUI extension library.
https://github.com/avaiga/guiext-template
Last synced: 7 months ago
JSON representation
Template repository for creating a Taipy GUI extension library.
- Host: GitHub
- URL: https://github.com/avaiga/guiext-template
- Owner: Avaiga
- License: apache-2.0
- Created: 2023-02-15T12:08:26.000Z (over 2 years ago)
- Default Branch: develop
- Last Pushed: 2025-02-07T08:09:26.000Z (8 months ago)
- Last Synced: 2025-02-07T09:22:25.784Z (8 months ago)
- Language: JavaScript
- Homepage:
- Size: 59.6 KB
- Stars: 2
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# guiext-template
A simple GitHub template that lets you create a [Taipy GUI](https://github.com/Avaiga/taipy-gui)
extension library that contains visual elements with dynamic properties therefore coded
with React.
You can find the Taipy GUI Extension Libraries documentation in
[this section](https://docs.taipy.io/en/latest/manuals/gui/extension/)
of the Taipy GUI User Manual.
This template contains all the code that lets you build a Taipy GUI Extension Library
containing a single element and use this library in a tiny Taipy GUI application.
This code is meant to be modified so you can add your custom visual elements.
## Prerequisites
To build Taipy GUI Extension Libraries, you need to have installed:
- Python 3.9 or above
- Node 18.2 or above (and npm)
- Taipy GUI 4.0 or above
## How to use this template
Click [](https://github.com/Avaiga/guiext-template/generate)
to create a new repository initialized from this template.
## Repository structure
- `README.md`: this file.
- `demo.py`: Python script demonstrating the usage of the elements provided in the
[`ElementLibrary`](https://docs.taipy.io/en/latest/manuals/reference/taipy.gui.extension.ElementLibrary/).
- `pyproject.toml`: Python project settings file for the extension library package.
- `MANIFEST.in`: This file lists the commands to be executed when the Python package
is built as a source distribution. See [this section](#packaging-the-extension-library)
for more details.
- `taipy_gui_ext_library/`: The directory where all the Python and TypeScript code for
the extension library can be found.
Note that this repository's name is ultimately the root directory of the Python
package you will build.
This directory contains the following:
- `front-end/`: The directory where all the front-end code is located.
This directory contains the following:
- `src/`: Where the source files for components are located.
- `index.ts`: the entry point for the front-end bundle.
This file typically just exports all the component classes so Taipy GUI can
use them.
- `Element.tsx`: TypeScript source for the React component associated with
the custom element called "element", as defined in the method
`get_elements()` of the `ElementLibrary` subclass.
- `scripts/install.js`: a JavaScript script used by `npm` when installing the
dependencies for building the main JavaScript bundle of the extension library.
- `package.json`: Holds the meta-data for the Node project.
- `tsconfig.json`: Holds the options to compile the TypeScript project.
The two important settings for the project configuration are:
- The value of *compilerOptions.outDir*: This indicates where the JavaScript
bundle is ultimately created.
If you wish to change this, you must also update the value of *output.path*
in the [webpack configuration file](taipy_gui_ext_library/front-end/webpack.config.js) and
the script path in the [library Python module file](taipy_gui_ext_library/library.py)
(see the `get_scripts()` method of the `ElementLibrary` subclass).
The value in the template is "./dist/".
- The value of *compilerOptions.include*: Holds the list of directories that
are scanned for TypeScript source files. This must include the directory where
our source files are located.
The template value is "["src"]", since that is the only directory where our
source files are located.
## Building the extension library
You must take several steps to build the Python package that holds the extension library
and the JavaScript code it uses.
### Customizing the extension library settings
Although the settings will work for the extension library defined in this template,
you will have to modify some files to match your specific settings.
Here are the parameters to watch and where they are referenced:
- Python package directory name
The name of the Python package that holds both the Python and JavaScript code
for the extension library. This package is autonomous and can be imported from
any Taipy GUI application that needs to use the defined elements.
It is important that this package name be unique because it gets installed next
to all the other packages of your Python installation (or virtual environment).
The value for the Python package directory name in the template is
"taipy_gui_ext_library" and is referred to as ''.
The name of the package appears in several places:
- As the name of the directory that holds all the code for this extension library.
This directory is located at the top level of this repository.
Note that in all this document, we use the default value of "taipy_gui_ext_library"
although your settings will change that.
- In the [`pyproject.toml`](pyproject.toml) file, as the value for the `name` key of the
*[project]* table.
- In the `get_scripts()` method of the `ElementLibrary` subclass defined in
[/library.py](taipy_gui_ext_library/library.py).
The path to the JavaScript bundle, relative to the directory containing the extension
library class definition, should be updated.
- In the [`demo.py`](demo.py) file, where the extension library is imported.
- In the [`MANIFEST`](MANIFEST.in) file used for building the Python package.
This file contains an instruction to package the JavaScript bundle, which is located
using the package directory name.
The source code comments refer to this value as ''.
- Extension library name
The library name is the string that is returned by the method
[`get_name()`](https://docs.taipy.io/en/latest/manuals/reference/taipy.gui.extension.ElementLibrary/#taipy.gui.extension.library.ElementLibrary.get_name)
of the `ElementLibrary` subclass you are implementing.
The name "taipy" is reserved by Taipy GUI.
This name usually identifies the extension library author.
It is defined in [/library.py](taipy_gui_ext_library/library.py).
This is used when Taipy GUI searches for the code involved in implementing
a visual element: custom element types use the library name as a prefix
for their name (i.e., `<|extension_library_name.element_name|>` in a Markdown page).
This name is also used to create a default name for the JavaScript module when the method
[`get_js_module_name()`](https://docs.taipy.io/en/latest/manuals/reference/taipy.gui.extension.ElementLibrary/#taipy.gui.extension.library.ElementLibrary.get_js_module_name)
is not overloaded: a camel case version of the element library name is then used.
The value in the template is "library".
The source code comments refer to this value as ''.
- Elements
The [library definition source file](taipy_gui_ext_library/library.py) contains a single
element called "element" that should ultimately be removed from your extension library.
This element is declared as using the "Element" React component defined in the
[TypeScript source file](taipy_gui_ext_library/front-end/src/Element.tsx) and referenced in
the [JavaScript bundle entry point](taipy_gui_ext_library/front-end/src/index.ts).
These will have to be removed as well from your final project.
- JavaScript bundle file name
The name of the JavaScript bundle file that holds the front-end code for
this extension library.
You don't have to change the base name of this bundle file, but in case
you want to change this, make sure it is updated in these two locations:
- In the method `get_scripts()` of the `ElementLibrary` subclass, defined in
[/library.py](taipy_gui_ext_library/library.py).
This method must return an array of strings containing the path to the bundle
file, relative to the directory containing the extension library class definition.
The value in the template is "taipy_gui_ext_library/front-end/dist/library.js".
- In the [webpack configuration](taipy_gui_ext_library/front-end/webpack.config.js).
The filename of the bundle must be set as the *filename* property value
of the *output* property of the dictionary returned by the function
assigned to *module.exports*.
The value in the template is "library.js"
- Packaging information
The [Python project settings file](pyproject.toml) defines a handful of information
bundled in the Python package to help people find or learn about your project when
it is deployed.
You can look at the
[setuptools documentation](https://setuptools.pypa.io/en/latest/)
for more information.
Here is a quick summary of what you can customize in the *[project]* table:
- The *name* key already mentioned above must be set to the project's name;
- The *version* key can be used to identify the version of your package;
- The *authors* keys can be set to identify you, your company, or any other
individual that is part of authoring this extension library;
- The *description* key provides a short text string that describes your package;
- The *readme* key can be set to locate a file with all the details for the
extension library;
- The *keywords* key can facilitate finding your package in package
repositories that provide a search capability.
### Setting up the JavaScript build
Before the bundle can be built, you must install the Node modules that are needed
and resolve JavaScript bundle dependencies. One of those dependencies is the Taipy
GUI JavaScript bundle that provides the Taipy GUI Extension API.
The detection of the path to the taipy-gui package should be done automatically by
installing the packages with: `npm install` in the `taipy_gui_ext_library/front-end` directory.
If you don't want to use the automatic setup, you must set the environment variable
"TAIPY_GUI_DIR" to the full path of the directory where Taipy GUI is installed.
To get this information, you can type:
```
pip show taipy-gui
```
This will print the information relevant to the installed Taipy GUI package. You must set
the environment variable "TAIPY_GUI_DIR" to the value indicated at the "Location:" line.
You can verify that this setting is correct by confirming that there is a directory at the
location `$TAIPY_GUI_DIR/taipy/gui/webapp`.
You can store this setting in the file `taipy_gui_ext_library/front-end/.env` if you want
to run the build process several times and not forget to set the environment variable
each time.
This file must contain this line:
```
TAIPY_GUI_DIR=
```
Once the environment variable "TAIPY_GUI_DIR" is set (as an environment variable or in the
`.env` file next to `package.json`), here are the steps to setup the build:
- Change your directory to where the front-end code is located:
`cd taipy_gui_ext_library/front-end`
- Install the packages that your library depends on:
`npm install`
This will run a NodeJS script that installs the Taipy GUI Extension API library.
This command will fail if the environment variable "TAIPY_GUI_DIR" is not set properly.
The 'front-end' directory will have an additional subdirectory called 'node_modules' where all dependent libraries are installed.
### Building the JavaScript bundle
To build the JavaScript bundle that holds the code for the front-end part of the extension
library, you must still be in the 'front-end' directory and run:
`npm run build`
Note that you can use `npm run build:dev` to keep debugging information to
spot and fix potential problems in your TypeScript code.
An additional directory called 'dist' is created in the 'front-end' directory, where
your JavaScript bundle was created.
### Testing the extension library
Now that the JavaScript bundle of the extension library is built, you can run the
[test application](demo.py) to verify it works properly.
Your current directory must be set to the root directory of the repository.
Assuming your Python environment is properly setup (that is, Taipy GUI is installed),
you can run the following:
```
python demo.py
```
A Taipy GUI application is launched, and your browser opens on the test page that
displays the custom visual element.
### Accessing the library's elements from the Page Builder API
At runtime, and *after* the library is registered (that is, after `Gui.add_library()` is invoked),
functions are dynamically added to the library's module to access its elements, exposing them with
the Page Builder API.
A typical code will look like:
```python
import
...
with tgb.Page() as page:
...
.()
...
```
To provide developers with autocompletion and type checking when coding, you can generate a Python
Interface Definition file next to your module's `__init__.py` file that will define function stubs
for every element of the extension library, with their properties, including their potential
documentation.
To create the Python Interface Definition file (called `__init__.pyi`, located next to the
`__init__.py` file), go to the project directory (above the '' directory) and
run:
```sh
python -m taipy.gui.extension generate_tgb
```
This file will provide support for developers in their IDEs.
### Packaging the extension library
If you wish to use your custom Taipy GUI extension library in several projects or share
it with other users of Taipy GUI, you can turn it into a standalone Python package.
From the root directory of this repository, run:
```
pip install build
python -m build
```
This creates a directory called 'dist' where the Taipy GUI extension library
has been packaged into a file called `taipy_gui_ext_library-1.0.0.tar.gz`.
You can distribute this file as a regular Python package archive.