mirror of
https://github.com/weewx/weewx.git
synced 2026-04-19 00:56:54 -04:00
120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# Extensions
|
|
|
|
A key feature of WeeWX is its ability to be extended by installing 3rd
|
|
party *extensions*. Extensions are a way to package one or more
|
|
customizations so that they can be installed and distributed as a functional
|
|
group.
|
|
|
|
Customizations typically fall into one of these categories:
|
|
|
|
- search list extension
|
|
- template
|
|
- skin
|
|
- service
|
|
- generator
|
|
- driver
|
|
|
|
Take a look at the [WeeWX wiki](https://github.com/weewx/weewx/wiki) for
|
|
a sampling of some of the extensions that are available.
|
|
|
|
## Creating an extension
|
|
|
|
Now that you have made some customizations, you might want to share
|
|
those changes with other WeeWX users. Put your customizations into an
|
|
extension to make installation, removal, and distribution easier.
|
|
|
|
Here are a few guidelines for creating extensions:
|
|
|
|
- Extensions should not modify or depend upon existing skins. An
|
|
extension should include its own, standalone skin to illustrate any
|
|
templates, search list extension, or generator features.
|
|
- Extensions should not modify the database schemas. If it requires
|
|
data not found in the default databases, an extension should provide
|
|
its own database and schema.
|
|
|
|
Although one extension might use another extension, take care to write
|
|
the dependent extension so that it fails gracefully. For example, a skin
|
|
might use data the forecast extension, but what happens if the forecast
|
|
extension is not installed? Make the skin display a message about
|
|
"forecast not installed" but otherwise continue to function.
|
|
|
|
## Packaging an extension
|
|
|
|
The structure of an extension mirrors that of WeeWX itself. If the
|
|
customizations include a skin, the extension will have a `skins`
|
|
directory. If the customizations include python code, the extension will
|
|
have a `bin/user` directory.
|
|
|
|
Each extension should also include:
|
|
|
|
- `readme.txt` - a summary of what the extension does, list of
|
|
pre-requisites (if any), and instructions for installing the
|
|
extension manually
|
|
- `changelog` - an enumeration of changes in each release
|
|
- `install.py` - python code used by the WeeWX
|
|
ExtensionInstaller
|
|
|
|
For example, here is the structure of a skin called `basic`:
|
|
|
|
```
|
|
basic/
|
|
basic/changelog
|
|
basic/install.py
|
|
basic/readme.txt
|
|
basic/skins/
|
|
basic/skins/basic/
|
|
basic/skins/basic/basic.css
|
|
basic/skins/basic/current.inc
|
|
basic/skins/basic/favicon.ico
|
|
basic/skins/basic/hilo.inc
|
|
basic/skins/basic/index.html.tmpl
|
|
basic/skins/basic/skin.conf
|
|
```
|
|
|
|
Here is the structure of a search list extension called `xstats`:
|
|
|
|
```
|
|
xstats/
|
|
xstats/changelog
|
|
xstats/install.py
|
|
xstats/readme.txt
|
|
xstats/bin/
|
|
xstats/bin/user/
|
|
xstats/bin/user/xstats.py
|
|
```
|
|
|
|
See the `extensions` directory of the WeeWX source for examples.
|
|
|
|
To distribute an extension, simply create a compressed archive of the
|
|
extension directory.
|
|
|
|
For example, create the compressed archive for the `basic` skin
|
|
like this:
|
|
|
|
tar cvfz basic.tar.gz basic
|
|
|
|
Once an extension has been packaged, it can be installed using `weectl`:
|
|
|
|
weectl extension install extension-location
|
|
|
|
## Default values
|
|
|
|
Whenever possible, an extension should *just work*, with a minimum of
|
|
input from the user. At the same time, parameters for the most
|
|
frequently requested options should be easily accessible and easy to
|
|
modify. For skins, this might mean parameterizing strings into
|
|
`[Labels]` for easier customization. Or it might mean providing
|
|
parameters in `[Extras]` to control skin behavior or to
|
|
parameterize links.
|
|
|
|
Some parameters *must* be specified, and no default value would be
|
|
appropriate. For example, an uploader may require a username and
|
|
password, or a driver might require a serial number or IP address. In
|
|
these cases, use a default value in the configuration that will
|
|
obviously require modification. The *username* might default to
|
|
*REPLACE_ME*. Also be sure to add a log entry that indicates the feature
|
|
is disabled until the value has been specified.
|
|
|
|
In the case of drivers, use the configuration editor to prompt for this
|
|
type of required value.
|