Quick Start

#### Search Results

Search

# Quick Start

In order to understand the structure of a Natural Studio plug-in and its interaction with Natural Studio, it is instructive to create and explore a minimal, but fully operational plug-in. Later this plug-in will be extended. Perform the steps described in the topics below.

- Prerequisites

- Creating a Minimal Plug-in

- Transferring a Plug-in From Natural 6 to Natural 8

- Installing and Activating the Minimal Plug-in

- Exploring the Minimal Plug-in

- Extending the Minimal Plug-in

- Deactivating and Uninstalling the Minimal Plug-in

## Prerequisites

In order to develop a plug-in, you need the example library `SYSEXPLG` as a basis. This library contains the plug-in example and some central definitions and modules that are common to all plug-ins.

Plug-ins are always executed under the Natural parameter file `NATPARM`. While developing a plug-in, you need the same Natural environment during editing, cataloging, debugging and execution of your plug-in. Especially make sure that Natural Studio runs with the same system file settings as specified in the Natural parameter file `NATPARM`.

To check the prerequisites

1. Make sure that the library `SYSEXPLG` is available.

2. Invoke the Configuration Utility and make sure that the libraries `SYSEXPLG` and `SYSEXT` are defined as steplibs in the Natural parameter file `NATPARM`.

3. This step applies only after a first-time installation of Natural.

   In the Configuration Utility open Natural Configuration Files > Global Configuration File > System Files.

   You will see an entry with the alias name "PLUGINS". This system file, which is part of the plug-in environment must be used as the FUSER of the Natural installation.

   Note
   This new "PLUGINS" entry is only available after a first-time installation of Natural. It is not available with an update installation or when Natural is installed in parallel to an older version of Natural.

4. This step applies only after an update installation of Natural or when a current version of Natural is installed in parallel to an older version of Natural.

   After an update installation or when a current version of Natural is installed in parallel to an older version of Natural, the FUSER setting of the plug-in environment has to be added manually to the global configuration file:

   - In the Configuration Utility open Natural Parameter Files > NATPARM > System Files > User System File.

   - In the FUSER tab change the values for DBID and FNR to match those of the FUSER of your plug-in environment.

     Important
     Never use the FNAT of the plug-in environment as the FUSER of Natural since an update installation might delete the FNAT.

5. Save your configuration and exit the Configuration Utility.

6. Plug-ins are always executed in the plug-in environment (for example C:\Program Files (x86)\Common Files\Software AG\Natural\V1) under the Natural parameter file `NATPARM`.

   While developing plug-ins, Natural for Windows must be started with the FUSER of the plug-in environment.

   Important
   Please be aware of the fact that the plug-in environment is independent from the Natural Studio environment. When a plug-in extends Natural Studio or retrieves data from Natural Studio, this should always be performed via the exposed interfaces.

## Creating a Minimal Plug-in

Plug-ins are created using the Plug-in Manager.

To create a plug-in

1. Make sure that the Prerequisites are met.

2. Make sure that plug-in activation has been enabled. See Workspace Options in the documentation Using Natural Studio.

3. Invoke the Plug-in Manager as described in Invoking the Plug-in Manager in the documentation Using Natural Studio.

4. Invoke the context menu and choose New.

   The following dialog box appears.

   The entries that are proposed in the different text boxes contain your user ID.

5. Specify all the following information:

   > Library

   >   Enter the Natural library into which the plug-in shall be generated. You should ideally use a new library for each plug-in project. If the library is not empty, you will receive a warning. If you generate the plug-in anyway, existing modules will be replaced without further warnings.

   >   Note
   >   Do not use a library name starting with `SYS` since this plug-in library will then be created into the FNAT of the plug-in environment which is not permitted.

   > Class module

   >   The plug-in consists basically of a Natural class. Choose an eight character name for the class module and enter it here.

   > Class name

   >   This name will be used as class name in the `DEFINE CLASS` statement. Choose a 32 character class name and enter it here. This class name combined with the version number will be used as ProgID in the system registry when the plug-in is installed. Therefore you must use a name that is unique among all ActiveX components that are installed on the machine. It is good and common practice to prefix the name with an abbreviation of your company. For instance the class names of the plug-ins delivered with Natural Studio all start with "CSAGNAT".

   > Display name

   >   This name will be used to display the plug-in in the Plug-in Manager.

   > Version

   >   The version number specified here is combined with the class name specified above to form the ProgID of the plug-in, for example "CSAGNATUSERNATURALPLUGIN.3". Different plug-ins with the same class name and different version numbers can coexist in one installation.

   > Single server

   >   If this check box is selected, the new plug-in will run in an own Natural server process, distinct from all other plug-ins. This is required only if the plug-in uses generic document windows.

   >   If this check box is not selected, the plug-in will run in the same server process as the Plug-in Manager. This saves an extra Natural server process during execution of the plug-in. However, it does not allow the usage of generic document windows.

6. Choose the OK button to generate the plug-in into the specified library. This is a minimal plug-in which you can extend with your own code (this is explained later in this section).

   If an error occurs during the generation process, check the generation log. A common reason for errors is that the example library `SYSEXPLG` is not available, is not set as a steplib or was manually modified. In such a case, you have to reinstall the example library and check the steplib assignment.

7. In order to register and activate the plug-in, proceed as described in Installing and Activating the Minimal Plug-in below.

## Transferring a Plug-in From Natural 6 to Natural 8

This section describes how to transfer a custom plug-in running in a Natural Version 6 environment to a Natural Version 8 or higher environment.

Note
Following this approach, the custom plug-in will still run in the Natural Version 6 environment.

To transfer a plug-in

1. Start Natural Version 6.x and unload the custom plug-in library to the file system using the Unload Wizard of the Object Handler.

2. Stop Natural Version 6.x.

3. Start the Natural Version 8.x Configuration Utility.

4. Adjust the steplibs as described in Prerequisites.

5. Add the FUSER setting of the plug-in environment manually to the global configuration file:

   - In the Configuration Utility open Natural Parameter Files > NATPARM > System Files > User System File.

   - In the FUSER tab change the values for DBID and FNR to match those of the FUSER of your plug-in environment.

     Important
     Never use the FNAT of the plug-in environment as the FUSER of Natural since an update installation might delete the FNAT.

6. Save your configuration and exit the Configuration Utility.

7. Start Natural Version 8.x.

8. Load the custom plug-in library to the file system using the Load Wizard of the Object Handler.

   Note
   If the custom plug-in ported to Natural Version 8.x is located in an FNAT library (library name starting with `SYS`), the library must be renamed to an FUSER library.

9. Delete incompatible objects:

   - Delete the `INSTAL-N` object of the ported custom plug-in library.

   - Delete the Resources folder containing a .reg and a .log file.

10. Use a new GUID and a new version number:

    - Generate a new GUID by creating a temporary plug-in library and copy the GUID into the clipboard.

    - Open the `INSTALL` program located in the custom plug-in library.

    - Init the `#CLSID` variable with the newly generated GUID value.

    - Increment the `#VERSION` variable value.

    - SAVE and STOW the `INSTALL` program.

11. Open the custom plug-in class in the custom plug-in library.

    - Init the `#CLSID` variable with the newly generated GUID value.

    - Increment the `#VERSION` variable value.

    - SAVE and STOW the custom plug-in class.

12. In order to register and activate the plug-in, proceed as described in Installing and Activating the Minimal Plug-in below.

## Installing and Activating the Minimal Plug-in

When the minimal plug-in has been created as described above, it can be installed. When it has been installed, it can be activated.

The advantage of an activated plug-in is that you can immediately test whether your own code that you add to the plug-in works as intended.

To install a plug-in

1. Execute the program `INSTALL` that was created in the library specified during the creation of the plug-in.

2. Restart Natural Studio to make the new plug-in visible in the Plug-in Manager.

   Note
   The next time you execute the program `INSTALL`, the plug-in is uninstalled.

To activate a plug-in

1. Invoke the Plug-in Manager.

2. Activate the new plug-in as described in Activating and Deactivating a Plug-in in the documentation Using Natural Studio.

   Note
   When you define automatic activation mode for this plug-in, the plug-in will be activated each time you start Natural Studio. See Defining Automatic or Manual Activation Mode for a Plug-in in the documentation Using Natural Studio.

## Exploring the Minimal Plug-in

Log on to the library into which the plug-in was generated and open the generated class in the Class Builder. You will notice that the plug-in is just a Natural class that implements two specific interfaces, namely `INaturalStudioPlugIn` and `INaturalStudioPlugInTree`. These interfaces are specified in the interface modules (copycodes) `NSTPLG-I` and `NSTPLT-I`, which are contained in the example library `SYSEXPLG` and are shared by all plug-ins.

The minimal plug-in leaves most of the methods of these interfaces empty. In fact it really implements only two methods: `OnActivate` and `OnDeactivate` of the interface `INaturalStudioPlugIn`. These methods are of specific interest: Natural Studio calls the method `OnActivate`, when the user chooses the command Activate in the Plug-in Manager. `OnDeactivate` is called when the user chooses the command Deactivate in the Plug-in Manager.

If you open the method bodies of `OnActivate` and `OnDeactivate` in the Class Builder, you will notice that the minimal plug-in does nothing other than indicating its activation and deactivation by opening a message box. A real plug-in will of course use these methods to prepare itself for operation and to initialize and uninitialize its state. In the following section, we will see what this can mean.

## Extending the Minimal Plug-in

The following topics are covered below:

- Adding a Command

- Enabling the Command

- Handling the Command

### Adding a Command

In order to interact with the user, the plug-in must define commands and present them to the user in menus or toolbars. Usually this will be done in the method `OnActivate`. Natural Studio passes a handle to the Natural Studio interface `INatAutoStudio` to the plug-in. The plug-in will store this handle and use it to access Natural Studio during further method calls.

To add a command

- As an example, add the code which is indicated in bold to the method `OnActivate`:

      define data
      parameter using nstact-a
      object using nsttmp-o
      local
      1 #controlbars handle of object
      1 #commands handle of object
      1 #command handle of object
      1 #toolbars handle of object
      1 #toolbar handle of object
      end-define
      *
      * Keep the Natural Studio Automation interface in mind.
      #studio := nstact-a.iNatAutoStudio
      * Show that we are coming up.
      send "MessageBox" to #studio
      with "Activating plug-in!" "Natural Studio Plug-in"
      *
      * Add a command.
      #controlbars := #studio.ControlBars
      #commands := #controlbars.Commands
      send "Add" to #commands
      with 100 "My Command" 1
      return #command
      *
      * Select a toolbar.
      #toolbars := #controlbars.Toolbars
      send "Item" to #toolbars
      with "Tools"
      return #toolbar
      *
      * Insert the command.
      send "InsertCommand" to #toolbar
      with #command
      *
      end

  This code sequence creates a command with the internal identifier "100" and inserts it into the Tools toolbar. Whenever the user chooses the new toolbar button, Natural Studio sends the command identifier "100" to the method `OnCommand` of the interface `INaturalStudioPlugIn`.

### Enabling the Command

Initially, Natural Studio shows the new command disabled. In order to make the command available to the user, the plug-in must implement a command status handler. In the command status handler, the plug-in can check any condition necessary to enable the command. In particular, it has access to the interface `INatAutoStudio` to perform operations in Natural Studio. In the simplest case, the plug-in enables the command without any condition.

To enable the command

- As an example, add the code which is indicated in bold to the method `OnCommandStatus` of your plug-in:

      define data
      parameter using nstcst-a
      object using nsttmp-o
      end-define
      *
      decide on first nstcst-a.Command
        value 100
          nstcst-a.Enabled := True
        none
          ignore
      end-decide
      *
      end

### Handling the Command

In order to react to the command, the plug-in must implement a command handler. In the command handler, the plug-in can do anything necessary to implement the command. In particular, it has access to the interface `INatAutoStudio` to perform operations in Natural Studio.

To handle the command

- As an example, add the code which is indicated in bold to the method `OnCommand` of your plug-in:

      define data
      parameter using nstcmd-a
      object using nsttmp-o
      local
      1 #objects handle of object
      1 #progs handle of object

      end-define
      *
      decide on first nstcmd-a.Command
        value 100
            #objects := #studio.Objects
            #progs := #objects.Programs
            send "Add" to #progs with 1009
        none
            ignore
      end-decide
      *
      end

  Now when the user chooses the new toolbar button, the plug-in opens the program editor with an untitled program.

## Deactivating and Uninstalling the Minimal Plug-in

If you do not want to work with your minimal plug-in any longer, you can deactivate it. If you want to remove your minimal plug-in from the Plug-in Manager, you have to uninstall it.

To deactivate a plug-in

1. Invoke the Plug-in Manager.

2. Deactivate your minimal plug-in as described in Activating and Deactivating a Plug-in in the documentation Using Natural Studio.

   Note
   When automatic activation mode has been defined for this plug-in, the plug-in will be activated again the next time you start Natural Studio. See Defining Automatic or Manual Activation Mode for a Plug-in in the documentation Using Natural Studio.

To uninstall a plug-in

1. Execute the program `INSTALL` that was created in the library specified during the creation of the plug-in.

2. Restart Natural Studio to remove the plug-in from the Plug-in Manager.

   Note
   The next time you execute the program `INSTALL`, the plug-in is installed again.

### On this page

- Prerequisites
- Creating a Minimal Plug-in
- Transferring a Plug-in From Natural 6 to Natural 8
- Installing and Activating the Minimal Plug-in
- Exploring the Minimal Plug-in
- Extending the Minimal Plug-in
- Deactivating and Uninstalling the Minimal Plug-in