Extensions and Commmands¶
Why do I need an Extension¶
pyRevit’s extensions system has evolved again to be more flexible and easier to work with. We’ll dive right into how you can add your own extension, but first let’s answer one important question:
Q: Why would I need to create a separate extension? Why Can’t I just add my scripts to the current pyRevit tools?
A: Because pyRevit is a git repository and the real benefit of that is that you can keep it always updated without the need to unsinstall and install the newer versions. To keep this system running without issues, I highly recommend not to mess with the pyRevit git repository folders and contents and pyRevit makes it really easy to add your own extensions. You can even add tools to the standard pyRevit tab in your own extensions. I’ll show you how.
Besides, by creating a separate extension, you’ll have all your precious scripts and tools in a safe place and away from the changes being made to the core pyRevit. They can even live somewhere on your company shared drives and be shared between your teams.
Each extension is a group of tools, organized in bundles to be easily accessible through the user interface.
Extensions are organized in a folder bundle with
Like this one:
There are two steps that you need to follow to create your own extensions:
Setup external extension folder:
First, is to create a separate folder for all your custom extensions and tell pyRevit to load your extensions from this folder. This is done in the Settings window, under the Custom Extension folders section. This way your precious extensions will stay out of the pyRevit installation and are safe.
Create custom extension bundle:
Next, create your
<your extension name>.extensionfolder under your custom extensions folder. Read the sections below on how to create bundles for your commands and the user interface.
A bundle is a folder named in the format
The most basic bundle is a command bundle. There are more than one type of
command bundles but a
.pushbutton bundle explained here covers 90% of the use cases.
Now that we have explained the command bundles, we need a way to organize these commands into a user-friendly interface. Let’s introduce Group Bundles
A group bundle is a bundle that can contain command bundles and other group bundles. They come in all different shapes and sizes but they have a few features in common:
- They can contain command bundles and other group bundles. (But I’ve already said that)
- icon.png: Bundle can include an icon for their user interface.
- lib/: The can define a python library (a sub-folder named
libinside the bundle will do). This library will be accessible to all the commands in this bundle and other child group bundles. This folder can contain all the python modules that are being shared between the child commands.
- _layout: This is a text file inside the bundle that defines the order in which the bundle contents should be created in the user interface. The contents of this file should be the names of the component in the order that they should be created in the user interface.
_layout file example. This is a layout file for a Group Bundle that
has a series of push buttons and other group bundles under itself:
PushButton A PushButton B PullDown A --- PullDown B Stack3 A >>> PushButton C PullDown C
Oh, and also:
---This line will add a separator to the interface (You can use more than 3
-characters. For example
----------still works as a separator)
>>>Any bundle after this line will be created inside a slide-out. This works for panel bundles only. (You can use more than 3
>characters. For example
>>>>>>>>>still works as a slide-out)
And this is how a typical Group Bundle looks like:
Now let’s talk about the different Group Bundles:
This bundle creates a Tab in the Ribbon with the bundle name.
This bundle creates a Panel in a Ribbon Tab with the bundle name.
||Any other bundle type|
This bundle creates a Pulldown Button in a Ribbon Panel or a Stack, with the bundle name and icon.
||Only command bundles|
There are a few more advanced bundle types in pyRevit as well. Here is some quick intro on these bundles.
Other Extension Types¶
Library extensions are created to share IronPython modules between all extensions. They’re in essence IronPython module packages. Some users might decide to develop an IronPython library (e.g. RevitPythonWrapper Library) that other users can use in their tools and benefit from.
Library extensions are identified by
.lib postfix. The library extension
folder address will be added to the
sys.path of all the other extensions by the loader.