<aside> <img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/ef7e1c71-55d2-42b6-b63b-f0e8787d53cc/ic_01_idea.png" alt="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/ef7e1c71-55d2-42b6-b63b-f0e8787d53cc/ic_01_idea.png" width="40px" /> 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.

</aside>

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

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.

<aside> <img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/db316e4a-d249-451a-ab8a-2fc1343d1866/ic_01_idea.png" alt="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/db316e4a-d249-451a-ab8a-2fc1343d1866/ic_01_idea.png" width="40px" /> See Bundle Context for more information on available context directives.

</aside>

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:

<aside> <img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/db316e4a-d249-451a-ab8a-2fc1343d1866/ic_01_idea.png" alt="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/db316e4a-d249-451a-ab8a-2fc1343d1866/ic_01_idea.png" width="40px" /> See Bundle Layout for more information on available context directives:Ï

</aside>

Example

layout:
	- PushButton A
	- PushButton B
	- PullDown A