Introduction to the Prime Automation Framework

Méthode Automation is a library enabling customers to include automations to get more by doing less operations. This framework offers a set of APIs that can extract and manipulate objects from Méthode Client. Méthode Automation exploits MS COM capabilities to access this set of APIs.

General Concepts

This framework provides a set of interfaces able to access Méthode Client. Those interfaces are accessible using a standard Javascript language. The Javascript file must be registered in a specific windows registry in order to let Prime load it during the application boot

// Example of how to retrieve the entry point interface (inside the Prime HTML panel)
var application = external.EomQueryInterface("Methode.Application");

// Example of how to retrieve the entry point interface (inside the Javascript addin)
var application = new ActiveXObject("methode.application");

// application will contains all the methods of the IApplication interface

Entry Point

The Méthode Client is an application allowing users to access different windows (Story Editor, Page Editor, Topic Editor, etc.).

Automation iapplication

Windows

Each window can have an active document, i.e. the document a user is working on (a story in the Story Editor, a page in the Page Editor, etc.).

Automation iwindow

Documents

The active document contains a focus on a particular element that represents the current selection. For example, a page can contain several stories. If a story is focused by some events, then this story becomes the selection for the current active document.

Automation idocument

Selection

The current selection can be seen as a document that contains further objects. For example, every story into a page can contain several other pieces (images, text, etc.) In this case, you consider the focused story as the current document and the focused piece as the current selection.

Automation recursion

Main Classes Hierarchy

Class diagram

Addins

Each Automation script (generally called Addin) is loaded by Prime during the bootstrap phase and before show the first windows. Prime will search the addins to load in a specific location inside the Window Registry

Installation

This script can be used to register an addin inside the registry in order to be loaded by Prime:

// Install Function
function OnRegister(addinName, addinPath)
{
	var wshell = new ActiveXObject("WScript.Shell");

	// This code performs the initial registration
	var key = "HKLM\\Software\\EidosMedia\\Methode\\Addins\\" + addinName + "\\";
	wshell.RegWrite (key + "Name", addinName, "REG_SZ");
	wshell.RegWrite (key + "Path", Path, "REG_SZ");
	wshell.RegWrite (key + "Description", addinName, "REG_SZ")
	wshell.RegWrite (key + "Enabled", "yes", "REG_SZ");
}

var ws = new ActiveXObject("WScript.Shell");
OnRegister ("Test", "C:\\Methode\\addins\\TestAddin.js")
Tip
 You can write the installation script in a javascript file (install.js) and run it in "Windows Script Host"

Addin Skeleton

As said before an addin is a Javascript file with a list of Callbacks that will be called by Prime to alert the script in some specific conditions.

Here an example of a standard Addin:

var app = null;
var cookie = null;

function OnConnection(Cookie){...};

function OnStartupComplete(){...};

function OnMTIWindowReady(){...};

function OnDocumentReady(){...};

/* Called when a toolbar button is pushed */
function OnEvent(evtName) {...};

/* Called when the last frame is closing, but still valid (IWindow can be used) */
function OnBeginShutdown(){...};

/* Called when the last frame is destroyed (IWindow cannot be used) */
function OnDisconnection(){...};

Main Callbacks

OnConnection

OnConnection is called just after Prime ha registered and loaded the adding inside his internal table. Prime will assign a Cookie which is an internal unique identifier for the addin. It must be used in same API calls where Prime need to know who is calling the framework (ex. when the adding will ask to add some button in the Toolbar)

The Cookie must be saved by the addin.

function OnConnection(Cookie)
{
	cookie = Cookie;
}

OnStartupComplete

OnStartupComplete is called after the startup phase is completed. After the startup phase: - The Prime is connected to the backend - All the addins are loaded inside the internal AddinsTable

The OnStartupComplete can be used to save the IApplication interface like this

function OnStartupComplete()
{
	app = new ActiveXObject("methode.application");
}

OnMTIWindowReady

OnMTIWindowReady every time a new frame is loaded. Prime has different windows (Story Editor, Page Editor, Page Editor, Browser, etc.) This callback can be used to verify if the frame type is compatible with the addin.

Below a standrd example how this callback is usually used:

	var w = app.ActiveWindow;

	if (w.Type == FrameText || w.Type == FrameDwp)
	{
        // This addin is compatible with the Story Editor and Page Editor
    }

OnDocumentReady

OnDocumentReady is like OnMTIWindowReady but is called after a document (typical a EomDb object) When the addin receive OnDocumentReady callback can start to interact with the IDocument interface

function OnDocumentReady()
{
    // ActiveDocument is valid now
	var currentDocument = app.ActiveDocument;

}

OnBeginShutdown

OnBeginShutdown is called when Prime starts to the shutdown phase. This is a good place where free all the resources handled by the addin

OnDisconnection

OnDisconnection will be called after OnBeginShutdown when Prime will unload also the Javascript code of the addin