Command Reference : User Objects : Defining a Registered User Object Class
  
Defining a Registered User Object Class
 
Creating an Object Definition File
Registering a User Object Class
Creating a User Object Package
Creating the Self-installing Package
Table of Contents
Installer Program
Documentation
Version
XML File Specification
To define a registered user object class, you must provide information on how to construct (create) an instance of the object. While the constructor information is all that is required, you may optionally specify menu items and custom command names for views and procs that will execute EViews programs.
We may divide the registration procedure into two distinct steps:
Create an object definition file which includes constructor, view, and proc definitions.
Register the object definition file with EViews.
This discussion assumes that you have already written programs to initialize your object and possibly to display views and execute procs. These programs will be standard EViews programs that use ordinary EViews commands. There are, however, several programming features which are designed specifically for user object (and Add-in) program development that you should find useful. See “Add-ins Design Support” in the Command and Programming Reference.
Creating an Object Definition File
The object definition file is a simple text file with a “INI” extension. This file describes how to construct the custom object using an EViews program and optionally provides menu items and custom command names for views and procs that will execute EViews programs.
There are three sections in the file, corresponding to the constructor, the views, and the procs of the object.
The first section of the definition file should start with a line consisting of the text “[constructor]” (without the quotes). The line immediately following should contain the path and name of an EViews program file that will be used as the constructor. The constructor program file describes how the object should be initialized, or constructed, when you create a new instance using the Object/New Object... menu item or the command line.
The second section contains the view definition specifications. This section should start with a line consisting of the keyword “[views]”. Each line following this keyword will define a view for the user object. Each view definition line should consist of the menu text, followed by a comma, a custom command name for the view, a comma, the path and name of the program file to be run when the view is selected from the menu or run from the command line.
The third section contains the proc definition specifications. It follows the same format as the views section, but begins with “[procs]” rather than “[views]”.
Note that when providing the path of the programs in your definitions, the “.\” shortcut can be used to denote the folder containing the definition INI file.
For example, the following is the definition file for the ResStore user object:
[constructor]
".\resstore construct.prg"
[views]
"View stored objects", objects, ".\viewall.prg"
"View stored equations", equations, ".\viewequations.prg"
"View stored graphs", graphs, ".\viewgraphs.prg"
"view stored tables", tables, ".\viewtables.prg"
[procs]
"Extract objects from store", extractobjects, ".\extract objects.prg"
"Add objects to store", addobjects, ".\resstore construct.prg"
"Remove objects from store", dropobjects, ".\remove objects.prg"
The ResStore user object use a constructor program called “resstore construct.PRG” which is called when you create a new ResStore object from the dialogs or command line.
There are four view menu items, each associated with a different EViews program. The first view definition tells EViews that it should create a view menu item View stored objects and object command objects, and associate both with the EViews program “viewall.PRG” (which is located in the ResStore directory). This definition means that selecting View/View stored objects from the object menu, or entering the object command
my_object.objects
will run the “viewall.PRG” program which displays all of the stored objects in MY_OBJECT.
Similarly, there are three proc menu items. Selecting Proc/Remove objects from store or issuing the command
my_object.dropobjects
runs the “remove objects.PRG” program which displays a dialog prompting you for the name of the objects to remove from MY_OBJECT.
Registering a User Object Class
To register a new user object class, select Add-ins/Manage User Objects... from the main EViews menu to display the User objects management dialog, then click on the Add button to display the Add/Edit Program dialog.
The dialog allows you to provide a name for the user object class, to specify the INI file, attach a documentation file, and provide various object attributes:
The Object name edit field should be used to specify the user object class name. Note that if you provide the name of a built-in EViews object, the EViews built-in object will take precedence.
The Definition file edit field must be used to enter the name and path of the INI definition file. Note you may press the “...” button to navigate to and select the file.
The Documentation file edit field allows you specify a PDF, Text, RTF, Microsoft Word file, or URL containing documentation for the user object class. (Note that relative paths are evaluated with respect to the directory of the INI file, not the default user object directory.)
You may use the Brief description edit field to describe the purpose of the User Object.
You may enter a Version number for your user object and an Update URL indicating where to find the update XML file (see “XML File Specification”).
You must provide an object name and a definition file to register your object. The remaining information is recommended, but not required.
Creating a User Object Package
In “Defining a Registered User Object Class” we showed how you can use EViews program files and an object definition file to register a new user object class for personal use.
If you wish to distribute your custom object to others, we highly recommend that you create a user object package. Packaging the user object allows you to bundle all of the files for distribution and, if you provide an installer program, offers automatic installation of the object by dragging-and-dropping the package onto EViews or double clicking on the file.
The process of creating a user object package is virtually identical to packaging of an EViews Add-in, with a few minor exceptions. We summarize briefly the main steps. Related discussion may be found in.
Creating the Self-installing Package
The process of creating a user object package is straightforward, requiring only two steps:
(optional) Create a table of contents (TOC) information file and installer program file to allow for automatic registration and updating of the Add-in.
Create a self-extracting user object package file containing the object definition file and any support files (including the TOC and installer program file, if available).
To create the self-extractive file simply create a standard ZIP archive file containing all of the files for your user object, then rename the ZIP file so that it has the extension “UOPZ”. Opening such an file, automatically after completing the download, by double clicking on the file, or by dropping it onto EViews, will begin the automatic installation procedure.
The user object will not, however be automatically installed and registered unless you include a table of contents (TOC) information file and installer program along with your program files. Creating the TOC and installer program files takes only a few minutes and allows you to support automatic registration and updating of the user object. We strongly recommend that package distributors take the time to create these files as described below.
Table of Contents
Next, you should create a table-of-contents file named “Toc.INI”. The TOC file should contain setup information for the user object which describes the directory in which it should be installed, and the name of the EViews program, if any, that should be run to register the user object files. The format of the TOC file is:
[package]
installer = <name of installer file>
folder = <name of folder to create>
A TOC file should always begin with the line “[package]”. The “installer” keyword is used to indicate the name of the EViews program file that should be run to register the user object. If, for example, a registration file named “Roll install.PRG” is included in your package, you should include the line
installer = roll install.prg
The “folder” keyword may be used to indicate the subfolder of the default user object directory into which you wish to extract the package files. Thus,
folder = Roll
tells EViews to extract the contents of the UOPZ file into the “Roll” folder of the User Object directory. If no folder is specified, the basename of the UOPZ file will be used as the target folder name.
Installer Program
If you wish to facilitate automatic registration of the user object class, you should create a simple EViews “.PRG” program that uses the adduo command to register the User Object class. For example, the rolling regression user object described in “Rolling Regression Estimation Object (Roll)” may be registered by including the command
adduo(name="roll", version="1.0", desc="Rolling regression object") ./rolldef.ini
in a program file, and including a reference to this file in the package table-of-contents.
Documentation
We recommend that you provide documentation for your user object, and use the “docs=” option to point to the documentation file. Providing some documentation for the command line methods of initializing the object and accessing views and procs is especially important. Documentation could be anything from a simple text file with some syntax hints, to a lengthy PDF document that describes the user object features in detail.
Version
You may specify an version number for your user object. Version numbers allow users to use automatic updating to ensure they have the latest version of the object class definition files. When a user uses the Update button on the Manage User Objects dialog to check for updates, EViews will compare the hosted version number with the currently registered version number and download the latest version if newer.
You may use the “version=” option to specify the version number. If omitted, EViews will assume that the user object version number is 1.0.
XML File Specification
One of the most useful user object management features is the ability of users to automatically update their installed user object as newer versions become available. To support this feature, EViews must know where to look to determine the most recent version of the user object and where to download any updates.
(Note that this specification is identical to the file specification for Add-ins and the material below is virtually identical to the discussion for Add-ins.)
This information is communicated in an XML file, typically located on the Add-ins package hosting site. If you will be hosting this file, you should use the adduo option “url=” to specify the URL for the XML file. If this option is not supplied, EViews will look for the XML file on EViews.com.
The XML file should contain one or more item definitions, where each item is a set of information on a specific user object. The item definition is contained in the lines between an <item> and </item> tag. The full specification of an item is as follows:
<item>
<title>Roll</title>
<version>1.0</version>
<description>User Object for performing rolling regression.</description>
<link>http://eviews.com/Addins/Roll.uopz</link>
<pubDate>14 Dec 2012</pubDate>
</item>
The only required specifications are the <title> and <link>.
The <version> is used to specify the current user object version number. When the user checks for updates, EViews will download the user object if the version number they have currently installed is lower than the one given in the <version> tag.
The <link> specification contains the URL (or network file location) of the UOPZ file containing the user object package. This is the location from which EViews will download the updated Add-in package should the user request an update.
The <description> and <pubDate> specifications should be self-explanatory.