InstallApps

Syntax

F_ApiCallClient("ditafmx", "InstallApps |appname [|appname...]");

appname

The name of the structure application to install. When installing multiple applications, each is passed as a separate argument separated by the vertical bar character.

Usage

This API installs structure applications using the “stub” file method used by the default DITA-FMx applications. The applications to be installed must be provided in a ZIP archive and are installed to a “root” directory. The “root” directory is defined by the ROOT entry (see below) or is the FMHOME\Structure\XML folder if the ROOT entry is not provided. The ZIP file is copied to root folder and extracted into that location. The ZIP archive must be set up with the necessary internal folder structure to be extracted in this way. After the archive is extracted, the stub file is added into the structure application definitions file as a text inset. If the structure application definitions file already contains an application definition of the name being installed, the existing definition will be deleted.

Structure applications installed with this API must first be registered in the AppInstall section of the ditafmx.ini file. Each application requires the following entries (“ZIP” and “STUB” entries are required, while “ROOT” is optional).

appname-ZIP=path-to-zip

Where appname is the structure application name and path-to-zip specifies the ZIP archive that contains the application files. This must be an absolute path or relative to the “root” location.

appname-STUB=path-to-stubfile

Where appname is the structure application name and path-to-stubfile specifies the relative path to the installed “stub” file that is to be inserted into the structure application definition file. This path is relative to the “root” location.

appname-ROOT=root-path

(Optional) Where appname is the structure application name and root-path specifies the directory the application is copied to. If this is not provided, the “root” location is the FMHOME\Structure\XML folder.

Example ditafmx.ini file settings (not using a ROOT entry):

[AppInstall] 
DITA-MyApp-Topic-1.2-ZIP=DITA-MyApp\DITA-MyApp_1.2_apps.zip 
DITA-MyApp-Topic-1.2-STUB=DITA-MyApp_1.2\Topic\structapps-stub_topic_1.2.fm 
DITA-MyApp-Map-1.2-ZIP=DITA-MyApp\DITA-MyApp_1.2_apps.zip 
DITA-MyApp-Map-1.2-STUB=DITA-MyApp_1.2\Map\structapps-stub_map_1.2.fm 
DITA-MyApp-Book-1.2-ZIP=DITA-MyApp\DITA-MyApp_1.2_apps.zip 
DITA-MyApp-Book-1.2-STUB=DITA-MyApp_1.2\Book\structapps-stub_book_1.2.fm

In this example, all three applications are stored in the same ZIP archive. You could specify separate files if needed. This ZIP archive is copied to the FrameMaker\DITA-MyApp folder before the API is used to install the applications.

Return Value

0

Failure. Unable to process the specified document or book. It is also possible that DITA-FMx is not available for calls. Verify that DITA-FMx is registered in the maker.ini file using the client name of “ditafmx”.

<0

Failure.

>0

Success. Value returned represents the number of applications installed.