Custom Templates
Typhos ships with a handful of built-in templates. You can see these when you
browse the typhos/ui/core
and typhos/ui/devices
directories.
Note
This repo originally had a large number of LCLS-specific device templates. These have been moved to pcdsdevices.ui.
You can define your own templates outside of typhos to customize the behavior of the module when launching screens. These can be done generically, to replace the default templates, or per-class, to replace the templates in specific cases.
Template Creation
Templates are .ui
files created in qt designer. These are largely just
normal pydm displays, with extra macro substitutions. See the
pydm tutorial
for more guidance on using the designer.
Template Substitutions
All the information found in happi
will be loaded as a pydm macro into the
template. It does this by checking for attributes on the device.md
namespace object.
If no device.md
object is found, we will still include device.name
as the name
macro and device.prefix
as the prefix
macro.
The upshot of this is that you can include ${name}
, ${prefix}
, and
other keys from the happi database in your template and they will be
filled in from the device database on load.
Template Filenames
To replace a default template, create a template with exactly the same name.
To create a template for a class, name it based on the class name and the template type, e.g.:
PositionerBase.embedded.ui
PositionerBase.detailed.ui
PositionerBase.engineering.ui
Note that we’ll check an object class’s mro() when deciding which template to use- this is why all PositionerBase subclasses use the built-in PositionerBase.detailed.ui template by default.
In this way you can create one template for a set of related classes.
Template Discovery
There are currently three places that typhos checks for templates. In order of priority:
Check the paths defined by the
PYDM_DISPLAYS_PATH
environment variable.Check any paths defined by the
typhos.ui
package entry point.Check the built-in paths (core and devices)
With that in mind, there are two recommended workflows for running typhos with custom templates:
Create a repository to store your screens, and set
PYDM_DISPLAYS_PATH
to point to your repository clone’s screens directory. This path works exactly like any otherPATH
variable in linux.Create a module that defines the
typhos.ui
entry point. This entry point is expecting to find astr
,pathlib.Path
, orlist
of such objects at your entry point. One such example of how to do this can be found here
For top-level devices (e.g., at2l0
), the template load priority is as
follows:
Happi-defined values (
"detailed_screen"
,embedded_screen"
,"engineering_screen"
)Device-specific screens, if available (named as
ClassNameHere.detailed.ui
)The detailed tree, if the device has sub-devices
The default templates
For nested displays in a device tree, sub-device (e.g., at2l0.blade_01
)
template load priority is as follows:
Device-specific screens, if available (named as
ClassNameHere.embedded.ui
)The detailed tree, if the device has sub-devices
The default templates