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:

  1. Check the paths defined by the PYDM_DISPLAYS_PATH environment variable.

  2. Check any paths defined by the typhos.ui package entry point.

  3. Check the built-in paths (core and devices)

With that in mind, there are two recommended workflows for running typhos with custom templates:

  1. 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 other PATH variable in linux.

  2. Create a module that defines the typhos.ui entry point. This entry point is expecting to find a str, pathlib.Path, or list 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