OyezForms Application-level macros
See also:
- Creating menu-driven events
- Creating a mirror folder for Word Templates delivered by Active Library
- Tracking a form's lifecycle
- Saving a form via WebDAV
Overview
OyezForms hosts SaxBasic, a VB-syntax scripting language at both the level of the form template (these macros are typically written and compiled into distributed form templates by Oyez), and the level the OyezForms application itself. Macros give access to application events (Save, open, new) triggered by OyezForms users and allow you to launch scripts or trigger external code to extend the functionality of the software.
Application level macros are stored in the oyezfrms.bas file in the application folder (you are free to edit this text file which is supplied blank by Oyez). An editing environment for application level macros is available via File>Macro in OyezForms when no forms are open. Language help is available via the saxbasic.hlp file in the \help sub-folder.
You can enable/disable macros at both form and application level via Tools>Options>Macros. You can also determine if external automation triggers application level macro events or not.
SaxBasic supports basic form dialogues.
Application events
The following events offer entry points for your SaxBasic macros. If you write code for an event, you will have to call the relevant function below to continue OyezForms' (see example code, below).
| Event | Description |
| NewOLF | Occurs when the File>New command is chosen or when the New button on the toolbar is used. Call NewLegalForm to ensure New dialogue subsequently opens |
| OpenOLF | Occurs when the File>Open command is chosen or when the Open button on the toolbar is used. Call OpenLegalForm to ensure Open dialogue subsequently opens |
| SaveOLF | Occurs when the File>Save command is chosen or when the Save button on the toolbar is used. Call SaveLegalForm to ensure form subsequently saves |
| SaveAsOLF | Occurs when the File>SaveAs command is chosen. Call SaveLegalFormAs to ensure SaveAs dialogue subsequently opens |
| CloseOLF | Occurs when the File>Close command is chosen. Call CloseLegalForm to ensure form subsequently closes |
| Initialize | Occurs when the Oyezfrms.exe first loads. |
| ActiveLibraryComplete | Triggered after library synchronisation. Event supplies status parameter: 1 on success, 0 on failure. Available in v10.00r+ |
| CustomAction | Preconfigured User-generated event. See 'Custom actions', below. |
| FormDocumentCreated | Form's first intialisation after template is selected from FILE>NEW menu |
| FormDocumentOpened | Form has loaded after user FILE>OPEN or double-click in file system |
Custom Actions
You can create user-driven application-level entry points into macro code. See Creating user-driven events.
Application functions/properties
The following functions are available to trigger actions in OyezForms. Use the Object browser in the macro editing environment for details of returns and parameters, and see also example below.
Producing dialogues, menu supression
| NewFormDlg | Triggers the FILE>NEW user dialogue |
| SaveFormDlg | Triggers the FILE>SAVE AS user dialogue |
| OpenFormDlg | Triggers the FILE>OPEN user dialogue |
| HideRecentFiles() | Hides the FILE>RECENT FILES.... menu option. This should be called in the Application_Initialize() event. If this is not called, OyezForms will display the names of temporary files created when forms are dowloaded from cloud-based software. |
Actions
| NewLegalForm | Create a new blank form. 2 parameters: <string> Form title e.g. 'Agree20' <long> Select Library 1=user, 2=custom, 3=master |
| OpenLegalForm | Opens previously saved form from path provided Returns True on Success, False on failure. |
| SaveLegalForm | Saves form to existing path Returns True on Success, False on failure. |
| SaveLegalFormAs | Saves form to new path given Returns True on Success, False on failure. |
| SaveCopyOfLegalFormAs | Saves a copy of active form to given path without affecting the acitve form's path, or untitled status. Retursn True on Success, False on failure. |
| CloseLegalForm | Closes active legal form Returns True on Success, False on failure. |
Resource names/paths
| GetFormName | Returns string of the active form's title. e.g. 'Agree20' |
| GetPathName | Returns string of the active form's path |
| GetUserStorageFolder | returns default save path (set in HKEY_CURRENT_USER\Software\Oyez\Oyez Legal Forms\User\StoredFilePath). [v10.00n+] |
| GetNewLibrary | Retrieve the library chosen by the user from the NEW dialogue following use of the NewFormDlg function <long> Select Library 1=user, 2=custom, 3=master |
| GetNewRevision | returns <long> The revision value for the last form selected from the NEW dialogue or zero on error |
Controling a form's "dirty" status
| IsFormModified | Returns True if form has been altered sinced last save |
| ClearFormModified | Sets modified flag to False |
Locking forms as read-only
| .SetDocumentLock() | <enable> Long. 1 = set document as 'locked' (read-only to user); 0 = unlock document (editable to user). OyezForms can 'lock' any form and prevent user alterations. This can only be done via this external command , or via application-level macros. The locked state only persists for the current editing session. It is not stored in the form file when saved. |
| .GetDocumentLock() | Returns the state of the current document lock. 0 signifies no lock, 1 signifies the document is locked. |
Setting application title bar text
| .SetDocumentTitle() | <title> String. Set the title text displayed on the OyezForms application bar at the top of the application window.. This is useful when downloading forms saved to local temp folder from cloud-based applications. |
| .GetDocumentTitle() | Returns the title displayed on the OyezForms application bar at the top of the frame. |
Setting contextual data for a form
Each created form has the capacity to store two string values that can be set/read by external code. The UserPropertyBeta can also be set via the external COM interface by automating code. Introduced with V11.01F+. The UserPropertyAlpha is not externally accessible. The GetDocumentGUID() command returns a string of the windows-assigned GUID that is permanently stored within the .olf/x file. This is not available in XP. This value is read-only and constant. Introduced with V11.01F+
| UserPropertyAlpha (set/get only via app-level macros) |
UserPropertyBeta (set/get via form macros, app-level macros, external code) |
| GetDocumentGUID() (get via form macros, app-level macros, external code) |
e.g.: App.UserPropertyAlpha = "DocID=43026;LastCheckIn=2008-09-02"
Prior to v10.02S, values stored in this way persisted only for the length of the user's OyezForms session. As of OyezForms v10.02S+, these values are stored within the file format and can be retrieved when the form is re-opened.
Producing PDFs
See also: Configuring OyezForms' PDF Engine
| .ExporttoPDF() | <fullpath> Full path, including file extension, of PDF's location |
| .actionscomplete() | Returns TRUE when the exporttoPDF process has completed Should be used to test for OyezForms completing generating a PDF (which occurs asynchronously) |
| .setpdfoptionlong() | Used to set options in the OyezForms PDF export engine: novaPDF. See nova documentation for details. <option name> The name of the option to be set <value>The value the option is to be set to. Returns: none |
| .setpdfoptionlong() | Used to set options in the OyezForms PDF export engine: novaPDF. See nova documentation for details. <option name> The name of the option to be set <value>The value the option is to be set to. Returns: none |
| .setpagestoprint() | <string selecting pages to output> e.g. .setpagestoprint("1,2,7,8") would print the 2 two and last 2 pages of an 8 page form. |
Sample application macros