Skip to content

Bundle metadata

pyRevit History: Initially, pyRevit bundles were all written in IronPython, and the metadata about the bundle were included inside the python code as global variables. For example, the __title__ global variable would define a title for the tool in Revit UI. With the release of pyRevit 4.7, many more bundle types and languages were supported and a unified way was needed to provide this metadata. This page describes the unified Bundle Metadata File. The in-script global variables is still supported for IronPython for backward compatibility and convenience.

See Anatomy of IronPython Scripts for more information on in-script global variables.

The most important data about a bundle is the Bundle Type, and the Bundle Content (script, or other types of content). The naming conventions is the mechanism to provide this information to pyRevit runtime. For example for an IronPython command bundle, the folder extension (*.pushbutton) defines the bundle type, and the *script.py file defines the bundle content to be executed.

Bundle File

Bundle Metadata File (Bundle File for short) is a YAML *.yaml file that provides the extended, and optional metadata about the bundle. This metadata is used to improve the user experience, and provide more information about the bundle requirements and dependencies to the pyRevit runtime.

Improving Bundle User Experience

Bundle file can improve the user interface of a bundle, by providing a title, tooltip message, help url, and information about the authors. It is important to mention that the default UI title for a bundle is extracted from the bundle folder (MyTool in MyTool.pushbutton), but the bundle file can override that to define a better formatted name. One of the most popular cases for setting the title in a bundle file is when a line break (\n) is needed to better format the button name e.g. My\nTool.

# bundle title
title: "Make\nPattern"

# title can also be in various locales
# pyRevit pulls the correct name based on Revit language
title:
  en_us: Test Bundle (Custom Title)
  chinese_s: 测试包

# bundle tooltip
tooltip: Create new patterns in Revit
# tooltip can also be in various locales
# pyRevit pulls the correct tooltip based on Revit language
tooltip:
  en_us: Create new patterns in Revit
  chinese_s: 创建新模式

# bundle highlighting ('new' or 'updated')
# Revit UI will show a orange marker on the button and a border around the tooltip
highlight: new      # highlight as new
highlight: updated  # highlight as updated

# bundle help url
help_url: "https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf"
# help url can also be in various locales
# pyRevit pulls the correct help url based on Revit langauge
help_url:
  en_us: "https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf"
  chinese_s: "https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf"

# bundle author
author: Ehsan Iran-Nejad

# bundle author can also be a list of authors
authors:
  - John Doe
  - Ehsan Iran-Nejad

Use the locale codes here as shown above for various langauges

Supported Locale Codes

Revit Langauge Revit Locale Codes
English USA >=2013 english,en_us
English Great Britain >=2018 en_gb
Deutsch / German >=2013 german,de_de
español / Spanish >=2013 spanish,es_es
français / French >=2013 french,fr_fr
italiano / Italian >=2013 italian,it_it
Nederlands / Dutch >=2013 dutch,nl_be,nl_nl
简体中文 / Chinese Simplified >=2013 chinese,chinese_s
繁體中文 / Chinese Traditional >=2013 chinese,chinese_t
日本語 / Japanese >=2013 japanese,ja
한국어 / Korean >=2013 korean,ko
Русский / Russian >=2013 russian,ru
Čeština / Czech >=2013 czech,cs
Polski / Polish >=2013 polish,pl
Magyar / Hungarian >=2013 hungarian,hu
Português do Brasil / Brazilian Portuguese >=2013 portuguese_brazil,brazilian,portuguese,pt_br,pt_pt
Български / Bulgarian All bulgarian,bg
فارسی / Farsi All farsi,persian,fa
العربیه / Arabic All arabic,ar
Українська / Ukrainian All ukrainian,uk

Context Directives

The bundle file can also set the execution context of the bundle. This helps activating the bundle, where the appropriate conditions are available. For example a bundle can request to be activated only when selection is available.

See Bundle Context for more information on available context directives.

Example

# context directives are listed under `context` key, the order does not matter
context:
  - Walls
  - Text Notes

Bundle Layout

The bundle file can also set the order of all the childern bundles in the UI:

See Bundle Layout for more information on available context directives:Ï

Example

layout:
  - PushButton A
  - PushButton B
  - PullDown A

Bundle Environment Configs

Supported Revit Versions

Bundle file can define the range of Revit versions that support the bundle. pyRevit will not load the bundle if it is not supported under the running Revit. In the example below, the bundle will be loaded with Revit 2015 up to 2018 and is expected to work with the APIs for these versions.

# minimium supported Revit version
min_revit_version: 2015

# maximum supported Revit version
max_revit_version: 2018

Bundle file can also set the state of the bundle. pyRevit user can decide whether to load the Beta bundles when starting Revit or not.

is_beta: false

Using Liquid Templates

Bundles can define template values for all their child command bundles (and IronPython global variables). These are key, value pairs that are set inside the bundle file. The child bundle files can user the liquid tags {{ tag }} to reuse these template values.

For example, imagine all the help URLs for a series of tools, all direct to YouTube videos. Considering that YouTube videos have similar URLs that are formatted as https://www.youtube.com/watch?v=<video_id>, and the only unique part is the <video_id>, a good way to simplify these URLs is to define the repeated part of the URL (https://www.youtube.com/watch?v=) as a template and reuse the value in help URLs of the child bundles. In the examples below the liquid template tag {{youtube}} will be replaced with the value of youtube defined in the parent bundle file (https://www.youtube.com/watch?v=) when pyRevit is loading.

Inside Parent Bundle File

youtube: https://www.youtube.com/watch?v=

Inside Child Bundle Files

help_url: "{{youtube}}H7b8hjHbauE"
# final help url: https://www.youtube.com/watch?v=H7b8hjHbauE
help_url: "{{youtube}}po0lCldSGmk"
# final help url: https://www.youtube.com/watch?v=po0lCldSGmk proat

You can also group all your template values under the templates key. This cleans up the metadata files.

templates:
  youtube: https://www.youtube.com/watch?v=
  author: Ehsan Iran-Nejad