How to create a new folder in Crystal Enterprise

This section describes how to create a new folder in Crystal Enterprise. The example that is included consists of two CSP files. The first page (GetFolderDetails.csp) prompts the user for the folder's name and description. The second page (AddFolder.csp) adds the folder to the APS at the very top level of the folder tree and then adds a sub-folder underneath the newly created folder.

The following parts in this section explain how to create a folder in general, demonstrates this procedure using code, and finally provides a working example.

Creating a folder

The following procedure assumes you have already logged onto the APS and have a current session (see Authenticating and logging on the user for information on creating a session):

To create a new folder

1. Retrieve the PluginManager Object.

   The PluginManager allows you to retrieve the Folder plugin, which is needed to create a new folder.

2. Retrieve the Report plugin by passing the plugin's ProgID to the PluginInfo property of the PluginManager.
3. Create an empty InfoObjects Collection using the NewInfoObjectCollection Method in the InfoStore Object.
4. Call the Add Method using the newly created InfoObjects Collection and Folder plugin.

   The Add method creates a new InfoObject based on the type of plugin you give it. In this case, it creates a new folder in the InfoObjects Collection. It is important to note that a folder object is a type of InfoObject.

5. Set the new folder's properties including its name, description, and location in the folder tree.

   The location in the folder tree is set using the folder's parent ID. If the ID is zero, it is a top level folder; otherwise it is placed under the folder specified by the SI_PARENTID Property.

6. Commit the new collection to the APS using the InfoStore's Commit Method.

   This adds the new folder to the APS InfoStore.

These steps are illustrated in the following function:

function AddFolder(ParentFolderID, FolderName, FolderDescription, InfoStore)

' Creates a new folder.

'

' PARAMETERS

'

' ParentFolderID [IN]

'     The ID of the folder's parent folder.

' FolderName [IN]

'     The new folder's name.

' FolderDescription [IN]

'     A description of the folder.

' InfoStore

'     The InfoStore used to communicate with the server.

' RETURNS

' Returns the ID of the newly created folder

' If the function fails, it returns zero.

    ' The plugin manager

    Dim pmgr

    ' The Folder plugin.    

    Dim FolderPlugin

    ' Step 1

    ' Since folders are implemented using a plugin

    ' you will need the PluginManager to retrieve the folder plugin.

     set pmgr = InfoStore.PluginManager

    ' Step 2

    ' Retrieve the Report plugin by passing the pluginís ProgID

    ' to the PluginInfo property of the PluginManager.

     set FolderPlugin = pmgr.PluginInfo("CrystalEnterprise.Folder")

    Dim NewCollection

    Dim NewFolder

    ' Step 3

    ' Create a new, empty InfoObject collection.    

     set NewCollection = InfoStore.NewInfoObjectCollection()

    ' Step 4

    ' Give the Folder plugin object to the Add method.  This

    ' creates a new InfoObject based on the plugin type.

    ' In this case, since the plugin is the folder plugin,

    ' the object created is a folder object.

     set NewFolder = NewCollection.Add(FolderPlugin)

    ' Step 5

    ' Specify the folder's details.

    NewFolder.Title = FolderName

    NewFolder.Description = FolderDescription

    ' The next line indicates where in the folder tree the

    ' folder is to be created.  It does this by setting the

    ' parent ID property or, in other words, by telling the folder

    ' which folder is it's parent. If the parent ID property is

    ' zero, then the folder has no parent and is thus a top

    ' level folder.

    call NewFolder.Properties.Add ("SI_PARENTID",ParentFolderID)

    ' Step 6    

    ' Use the InfoStore to commit the new collection with the new folder

    ' to the APS database.

    on error resume next

    call InfoStore.Commit (NewCollection)

    if err.number = 0 then

        AddFolder = NewFolder.Id

    else

        addFolder = 0

    end if

end function