Adding a Folder

The following example checks to see if a folder for a user exists. If it doesn't, it creates one.

The folder hierarchy for this example is as follows. The Users folder is where the portal stores things such as user homepages:

Root folder

   Users folder

      UserId1 folder

      UserId2 folder

      UserId3 folder

      . . .

The following is the complete code sample: the steps explain each line.

Local ApiObject &MyPortal;
Local ApiObject &UserFldrColl, &UserFldr;

&MyPortal = %Session.GetPortalRegistry();

If NOT &MyPortal.Open(MYRECORD.PORTAL_NAME) Then
   /* Do error handling */
End-if;

&UserFldrColl = &MyPortal.RootFolder.Folders.ItemByName("Users").Folders;

&UserFldr = &UserFldrColl.ItemByName(%UserId);
If &UserFldr = Null Then

/* add Folder */

   &UserFldr = &UserFldrColl.InsertItem(%UserId, %UserId);
   &UserFldr.Description = %UserId;

/* Set dates */

   &UserFldr.ValidFrom = %Date;
   &ToDate = AddToDate(%Date, 1, 1, 0);
   &UserFldr.ValidTo = &ToDate;

/* Set properties */

   &UserFldr.PublicAccess = True;

/* save the folder */

   &UserFldr.Save();

End-If;

To add a folder:

Get a Session object and a PortalRegistry.

Before you can access a PortalRegistry object, you must get a session object. The session controls access to the registry, provides error tracing, enables you to set the runtime environment, and so on. Because you want to use the existing session, use the %Session system variable (instead of the GetSession function.) In addition, you want to get a PortalRegistry. Using the GetPortalRegistry method returns a reference to an unpopulated PortalRegistry object.
```
&MyPortal = %Session.GetPortalRegistry();
```
Open the PortalRegistry.

After you get a PortalRegistry object, you want to open it, that is, populate it with data. Use the Open method to do this. The Open method returns a Boolean value, and this example uses that value to do error checking to make sure that the PortalRegistry is actually opened. In addition, the name of the PortalRegistry is kept in the record MYRECORD, in the field PORTAL_NAME.
```
If NOT &MyPortal.Open(MYRECORD.PORTAL_NAME) Then
   /* Do error handling */
End-if;
```
Access the User folder collection.

One of the strengths of dot notation is being able to string together many methods and properties into a single line of code. The result of this single line of code is to return a reference to the folder collection within the Users folder.
```
&UserFldrColl = &MyPortal.RootFolder.Folders.ItemByName("Users").Folders;
```
Note that in this kind of code, you must access the RootFolder for the PortalRegistry before you can access the folders collection.

If there were additional folders in your hierarchy, you could continue in the same way, using ItemByName and Folders.
Check if the user already has a folder.

The system variable %UserId returns the user ID of the current user. Then this example uses the ItemByName method on the folder collection to see if the user already has a folder. This assumes that the user folders are names according to the UserId. The ItemByName method returns a reference to the folder if it exists. If the folder does not exist, ItemByName returns NULL.
```
&UserFldr = &UserFldrColl.ItemByName(%UserId);

If &UserFldr = Null Then
```
Add a folder if one doesn't exist.

Use the UserId as the name of the folder, as well as for the label and the description.
```
&UserFldr = &UserFldrColl.InsertItem(%UserId, %UserId);
&UserFldr.Description = %UserId;
```
Set the ValidFrom and ValidTo dates.

For this example, the folder should be accessible from the date it's created, so the example sets the ValidFrom property to be today's date.

When you first create a folder, the ValidTo date, that is, the date that this folder "expires", is set to null, that is an empty string. This means it never expires. In this example, we set the ValidTo date to one year and one day after the current date.
```
   &UserFldr.ValidFrom = %Date;
   &ToDate = AddToDate(%Date, 1, 1, 0);
   &UserFldr.ValidTo = &ToDate;
```
Set permissions for the folder.

There are several properties that work together to determine the access of a folder or content reference. This example sets the PublicAccess property to True, which means that everyone has access to it, and it's included in all collections of folders.
```
   &UserFldr.PublicAccess = True;
```
This example sets only the permission properties on the folder. It doesn't set all the possible permissions, such as the PermissionValue objects for the folder.
Save the folder.

After you have finished your changes to the folder, save it.
```
&UserFldr.Save();
```
You may want to check for errors after you save each folder.

See Using Security.