How do I make my Ruby script extension compliant?

Developers Ruby API
1

I have created a series of ruby scripts that I would now like to install and test from the extensions warehouse. I have been approved as a developer from Trimble, and I just need someone to point me to a “how to” tutorial to actually load my scripts into the extension warehouse. Thanks.

1 Like
2

The whole developer center with RBZ requirements and similar info seems to have gotten lost in the migration to Extension Warehouse 2 :frowning: .

SketchUp rubocop gives quite a lot of useful feedback on whether your code base is compliant with various requirements and recommendation, but doesn’t really explain how to get started structuring an extension.

I can’t find anything in the help center either :confused: .

Anyhow, a valid SketchUp extension consists of a registrar file and a support folder with a name matching the basename of the registrar. The registrar sets up the SketchupExtension object with all of its preferences, and references a file in the support folder that is to be loaded if the extension is enabled. All business logic of an extension should be inside this support folder.

All of your ruby files in the extension must also wrap everything they define in a unique namespace to avoid clashes with other extensions. Typically have an outer wrapping module with your name and an inner one with the extensions name.

When you finally build the RBZ file to share your extension, zip the registrar and the support directory. Make sure the name of the zip matches that of the registrar and folder, but with underscore and the version number appended. Also change the file extension from .zip to .rbz.

In practice, a registrar named my_extension.rb should have a support folder named my_extension and the RBZ should be named my_extension_1.0.0.rbz (if that is the version number).

Here’s a practical example of how an extension can be structured.

1 Like
3

Wow! Thanks for getting back to me so quickly. Several other questions. I have reviewed the pattern and method of what you mentioned to be the registrar file and that it matches the name of the support folder. But how do you create the registrar folder, or is that created when the extension is installed?

I’m not really interested in sharing these extension tools at this time with others until I have actually tested them fully before deciding how I want to distribute and support such utilities. They work for me and I think they work for others.

If I’m correct in my “assumption” that the minimum requirements for the extension to be properly installed, would be 3 main items: 1) the registrar file, 2) the support folder, and 3) the main script file, which could simply have an UI.messagebox statement with “This is my own extension”, along with the logic that would display it on startup. I could simply test that function by enabling and disabling the extension. Once I have the structure of the extension installed, I can simply add to the additional ruby scripts located in the extension support directory along with the code that utilize them.

So how do I create the registrar file?

Thanks, Scott.

4

I meant to say how do you create the registrar file? And do those two files with the support directory have to be zipped, as an .rbz?

5

I would regard the structure of the registrar, folder and “main” file to be the first requirement for an RBZ. The second requirement would be defining the SketchupExtension object in the registrar and the third requirement to wrap all these script in a namespace (module). There are additional rules like not using global variables, but those 3 are what turns a plugin into an extension.

You can just copy the registrar from my linked example and change the file name, module names and extension properties (author, name, version, description).

Zip all this stuff making up the extension and change the file extension from zip to rbz, and you have your RBZ.

6

I have developed the ruby scripts for that last several years utilizing the appropriate namespace (module) design and so that’s not a problem for me.

As I continued to search for appropriate loading requirements for extensions, I found this link.

I think I have the procedure to install an extension to 5 steps.

Step 1. Primary extension registrar file is to simply create copy of an existing registrar file and name it appropriate to the utility, along with editing the extension license information, ie. author, date, version, etc.

Step 2. Create a directory containing the same name as registrar’s .rb file.

Step 3. The main ruby script that initiates and controls the widget/utility items of my extension.

Step 4. Select registrar file, support directory, and main ruby script, and zip them together, and then change the extension of the file from .zip to .rbz.

Step 5. Place this zip file in a loading directory, MyDocuments, etc. activate the Extension Manager and install extension.

Does that sound about right? Thanks for your help. Wish me luck.

Scott.

7

The steps work perfectly. I was able to install and enable and disable the UI.messagebox comment upon startup.

Thanks so much for your input and assistance.

Scott.

8

You should not open modal windows during the startup cycle as it halts the application processes.

Instead either open the Ruby Console and use puts statements to send text to STDOUT,
… or … use non-modal GUI objects like UI::Notifcation or UI::HtmlDialog windows.

ALL your extension code and support files (except the registrar file,) must be in the extension subdirectory (ie… the folder having the same name as the registrar file.) So when you select the registrar script file and the folder … everything for the extension is selected for the RBZ zip archive.
(Ie, in the SketchupExtension constructor call, the 2nd argument should refer to the main loader file in the extension’s subfolder.)

It is common after the zip is created, to add a version suffix to the end of the name prior to the “.rbz” extension. Examples:

  • The RBZ naming from one of the Trimble open source community extensions, the SketchUp Shapes extension: "su_shapes-2.0.1.rbz".
  • The naming for one of TIG’s extensions: "TIG_AreaTextTag_v1.6.rbz"

Notice how the registrar file and the extension subfolder names are prefixed by the author/company namespace module name, followed by an underscore, and then the extension submodule name. This is necessary because the "Plugins" directory is a shared filespace. So registrar files and their accompanying extension subfolders need to be uniquely qualified to avoid naming collisions.

Some other helpful webpages …

9

Thanks Dan. I’m always amazed that you dedicate so much time to answering most all of these queries, on most all of the topics. For the last several years using these forums, I take your advice, comments, and suggestions very seriously, and incorporate the information you share into my development process.

I just want you to know that the only reason I used the UI.messagebox with the message was simply to test the enable and disable functions of the EW Manager. It was a single line within the program, so that that I could be assured about how my program was activated. And once tested, it was removed. I assure you that the messagebox is not activated during the initialization process.

Thanks, Scott.

3 Likes
10

Yea, but I don’t want you to get in that habit because messageboxes can fail silently if the string message is malformed.

1 Like
11

Yea, this was reported recently. I’ll get restored. We also have a better knowledge article which we plan to get into the API docs/wiki.

Btw, we have a bunch of examples on GitHub:

The tutorials folder has examples with very detailed commenting about almost every line.
The examples folder provides less comments but wider range of examples on how to do things.
We also have other repositoires on our GitHub account with more complex examples that deserve their own repos.

2 Likes
12

If you are not already into development you may not even know of GitHub. Ideally there should be a friendly start page for potential future developers to just stumble upon and almost accidentally start learning.

13

It’s all linked from the front page of the Ruby docs: http://ruby.sketchup.com/
(Though - we have plans to refresh that as well.)

1 Like
14

While it’s good to have this link in the Ruby API documentation, it doesn’t help people much to stumble upon it by accident. I think a lot can be done for inviting more people to become the developers of the future.