Extending EA with PERL

Package Contents

This package contains the following files:

• A.pl - a sample perl script
• EaControl.dll - a ready to use extension package
• EaControl.pm - the according perl module
• EaControlReposWrapper.pm - a handy extension module
• EaControl.reg - some registry keys needed for EA Addins

Installation

All you need to do is to follow these steps:

1. Place the files in a reasonable location.
2. Register the dll with REGSVR32 EaControl.dll. This will make the addins available for EA.
3. Edit and adjust the paths in the EaControl.reg file and add it to your registry by double-clicking the file.
4. Start EA

Now you should see an "Addin" context menu entry. If not, watch out for the message in the Addins/Manage Addins window. Likely you have an invalid path somewhere.

Configuration

The context menu in EA is build according to your entries in the registry (see EaControl.reg). Start with simple perl files (like the A.pl) contained in the package. For each entry you add in the registry you will find an according entry in the context menu. When clicked, the according perl file will be invoked. You can modify the perl file on the fly so the next invocation will run with your changes. See below on how to work with perl files on your EA repository.

Instead of pointing entries to simple perl files you can also point to perl modules (.pm). In contrast to simple perl files these modules are loaded permanently. That means an instance is created on startup of EA and then re-used. That way context information can be stored and re-used over several clicks. Further it is possible to create sub-menus from modules.

Working with .pl files

Upon invocation the .pl receive 3 parameters in %ENV:

• 'REP' holds the repository object. You can assign it to a local variable (e.g. $rep) for easy use.
• 'LOC' holds the values "TreeView" or "Diagram" depending on where the context menu is invoked. Note that a call from the menu will appear as "TreeView".
• 'OPT' contains an optional parameter provided after a comma following the file name in the registry.

The following code snippet demonstrates the principle:

1. my $elem = $rep->GetTreeSelectedObject(); # point to the selected element
2. $elem->{Name} = '(' . $elem->Name . ')'; # surround with brackets
3. $elem->Update(); # save changes

The first line retrieves the object that had been selected from the context. In the second line the object's attribute Name will be changed. Note that on the left hand side of the assignment you have to surround the attribute with braces. Note also that attributes and methods are case insensitive. However, it is convenient to write them in camel case. Finally on the third line the element changes are written back to the database.

It is quite easy to continue that way. The analogy between methods and attributes described in the SDK/EA Object Model/Reference is obvious (I think). I will eventually add some more snippets to demonstrate the ease of use. Meanwhile I have a collection of several thousand lines of EA Perl code and the only problem is: how to filter the interesting/general stuff.

Working with .pm files

Any .pm file will be loaded permanently. Further you have to implement the methods described below. 

sub new ($self, $rep)

Passes on the pointer to the repository so it can be used in the package.

sub menu ()

Must return the menu entries as array. If only one entry is returned then this is taken as menu entry. If more than one entry is returned then these entries are placed under a sub-menu for the according menu entry of the package.

sub exec ($self, $cmd, $loc)

The sub-menu name which has been chosen is supplied in $cmd. $loc holds either "TreeView" or "Diagram" (see above). The package can execute the command with the previously stored context and the repository from the new method.

Updates

As of 27-07-2010 I have uploaded a revised EaControl and Wrapper. The controller has removed the fixed references to Perl libs and now detects them dynamically. This should work for most installations. 

To update from a previous version first backup the old DLL. Then just replace the old DLL with the new one. If EA starts as usual and you find the addins, everything is okay. Else restore the old DLL and drop me a line so I can look into it.

On 16-05-2011 I added a DLL to work with new versions of ActivePerl. The old version did work up to build 1005 of ActivePerl (and probably a few later). But with new builds the DLL raises an error (EA_MenuClick: Exception Occurred Invoking Method). So I add a second DLL which is supposed to run with later builds. Just rename the EaControl 5.10.dll to EAControl.dll (replacing the original one).

On 30-04-2012 a new DLL release (5.14 suffix) has been added to work with ActivePerl build 1402. Obviously the Perl releases (the original one was created with 5.8 while the new one utilizes 5.14) have quite a few incompatibilities. I had not thought of these when initially creating the DLL. Maybe I'll start thinking about a release concept when the next incompatibility shows up next year.

Final remarks

Although the sources are in use and have been improved over several years they may contain errors. The DLL is created from the EaControl.pm using ActiveStates tools. You can also use WSH with the perl module. I did this in the past, but now I'm using the DLL. You can google for "ActiveState WSH" if you like to use EaControl.pm directly (with own modifications). Let me know how you like the package, where you did find errors, where you would like improvements or if you have added some for your own.

There's also an EaControlReposWrapper.pm to extend the number of methods provided by EA's automation. For a basic use you do not need this instrument. However you might want to use it if you have more experience. The wrapper has now been pimped with more functions like getting the (correct) children of elements and packages. That is, only the direct elements will be delivered and not their sub-elements.

Finally a word to debugging. I use ActiveState's Komodo where I have a simple method to attach the debugger. This allows for interactive debugging of EA addins.

Have fun.

This article contains content available for registered members only. You need to be logged in to view/download this content.