Retrieving the parent folder

This section will add support for an "Up a Level" link that returns the user to a folder one level up in the tree. It is similar to the RetrieveChildFolders function except in the way it accesses the results.

Creating an "Up a Level" link

To create a link such as this, you need to know:

• the ID of the folder you are currently in so that you can display its name
• the ID of the current folder's parent, so that you can provide the "Up a Level" link.

Once you have the ID of the current folder, you can retrieve its parent from the APS. The parent's ID will be used later to retrieve its children using the RetrieveChildFolders function.

Add the following RetrieveParentID function to Folders.csp:

RetrieveParentID function

function RetrieveParentID(IStore, ChildID)

{

//This function retrieves the ID number of a particular folder's

//parent.

//Precondition:

//IStore - The InfoStore object required to interface with server.

//ChildID - The ID of the child whose parent ID is to be retrieved.

//Postcondition:

//Returns the ID of the parent.

//Notes:

//If an error occured the function returns null.

    //The query that will select all the child folders.

    var Query;            

    //The result of the query.

    var Result;            

    //Create a query that selects the parent's ID for a folder.

    Query = "Select SI_PARENTID From CI_INFOOBJECTS Where SI_ID = " +

    ChildID + " And SI_PROGID = 'CrystalEnterprise.Folder'";

     //Query the server.

    try {

        Result = IStore.Query(Query);

    }

    catch(e) {

        //There was an error querying the server.

       return (null);

    }

    if (Result.Count > 0) {

        //Retrieve the ID from the query result.

        return( Result.Item(1).ParentID);

    } else

    return ("");

}

Remarks

The RetrieveParentID function is very similar to the RetrieveChildFolders function. Two lines of particular importance are different, however, and it is worth examining these in more detail.

Query = "Select SI_PARENTID From CI_INFOOBJECTS Where SI_ID = " +

        ChildID + " And SI_PROGID = 'CrystalEnterprise.Folder'";

This line is the query that finds the parent ID of a specified child folder. Note that this time, the SI_PARENTID Property is used instead of the SI_PARENT_FOLDER Property. While the two have been used interchangeably here, note that they are not equivalent. The following diagram illustrates the difference between them.

In the case of this diagram, an instance is owned by a report, and the report is owned by a folder. That is, the SI_PARENTID property for the Instance refers to the Report, and the SI_PARENTID property for the report refers to the folder. The SI_PARENT_FOLDER property for both the instance and the report, however, refer to the folder, and not the report.

Note:    In general, it is always preferable to use SI_PARENTID as it is faster to retrieve than SI_PARENT_FOLDER.

The second line worth noting in the example above is this one.

return(Result.Item(1).ParentID);

In this line, the ID of the parent folder is retrieved directly as it has been built into the object model. All properties are documented in the Query Language Reference: you will find the properties that have been built in the object model in their respective reference chapters as well.

Go to next step:

Retrieving the current folder