14 Creating Custom Activity Spaces

Activity Spaces group task-specific actions into logical sets to provide portal developers with base functionality, and combine related pages to create cohesive Model-View-Control (MVC) objects. Everything in the portal is an Activity Space: a MyPage, an administrative editor, even the Directory tree.

For example, consider the Content Crawler editor used to create a new Content Crawler object in the portal. The entire editor is represented by one Activity Space object that uses several Models, Views/DisplayPages, and Controls. The Content Crawler Editor Activity Space also uses functionality inherited from base classes, including banner display and page-to-page editor navigation.

Every Activity Space within the portal is derived from one of the base Activity Space classes, which include the following:

The Editor Activity Space defines how form-based editors work within the MVC paradigm. This framework is used for activities that require one or more pages of data entry, including creating portal objects and modifying settings that affect the entire portal. As noted above, the Content Crawler Editor inherits functionality from this base class.
The AForm Activity Space defines a basic form submission page that does not require advanced editor functionality. This Activity Space is used in the MyPage, Knowledge Directory, and other portal pages.

Recently used Activity Spaces are cached on the user's HTTP Session. (A caching algorithm helps ensure a scalable HTTP Session size limit.)

A custom Activity Space allows you to add new pages to your portal. As long as you maintain the contract dictated by the portal interfaces, your code will plug in seamlessly. This chapter provides details on Activity Space components as well as step-by-step instructions on creating a custom Activity Space.

Note: To customize existing pages, the recommended approach is to use Adaptive Layouts; for details, see Chapter 3, "Using Adaptive Page Layouts". To change existing UI code or add new components not available via Adaptive Layouts, use View Replacement; for details, see Chapter 13, "Using View Replacement".

Activity Space Components

Each Activity Space includes the following classes:

Activity Space
Display Page
Model
View
Control (optional)

Activity Spaces can include multiple implementations of DisplayPage, Model, View and Control.

Activity Space

The Activity Space class contains the Model-View-Control (MVC) framework and is responsible for initializing the Model, View and Control objects. It also stores data that is globally accessed by the UI.

Display Page

A DisplayPage class returns the View(s) used for the page. This simple class puts together the HTML and makes it viewable to the user. Each DisplayPage corresponds to an actual portal page; there is a one-to-one mapping between DisplayPages and portal pages.

Model

A Model class defines how data is accessed and set for a given page, including any functions necessary for security or data validation and modification. This class also encapsulates calls to the Portal Server API and stores UI-specific data. Control classes use a Model class to perform changes requested by the user. View classes use a Model class to retrieve data for display.

Note: Model classes must implement a "Read-Only" Model interface in order to discourage data manipulation in View classes. In most cases, you should add all public accessor methods to this read-only interface.

View

A View class contains the HTML for the component it represents and describes how the data from the associated Model should be displayed to the user.

Control

A Control class contains an action or set of actions that will be executed when a specific event is triggered. For example, a mouse click could trigger a popup window that displays a View.

Step 1: Creating an Activity Space

When you modify a piece of the portal UI, you should never change existing source code. You can create new, separate pages by using custom Activity Spaces, or overwrite existing code in a class through View Replacement. The UI source code is shipped with the portal, and you can view or download the API documentation for the portal UI packages.

To create a custom Activity Space, follow the steps below. For a simplified example, see the Example: Sample Activity Space sample code that follows.

Create your own custom project, including the custom classes listed in the previous section.
Edit each class in your custom project, following the Requirements and Best Practices below:
- The Create() method must return a new instance of the custom class (i.e., CustomActivitySpace()). Otherwise, when the portal attempts to instantiate a new instance of the custom classes using the Create method, it will not work. A common problem is cutting and pasting code from an existing Model, View or Control class and then forgetting to update this method.
- The GetRepostControlName() method inside the SampleActivitySpaceAS class must return the name for the Control you want to use.
- The name returned by the GetName() method must be unique for each type. For example, you can only have one View named "test" and only one Model named "test".
Compile each class into a new jar/dll file with an intuitive name (for example, CustomActivitySpaceAS).

Example: Sample Activity Space

This sample customization demonstrates how to create a sample Activity Space with a simple change text feature to illustrate the use of a Control for repost actions. It contains two modes to display two different looks for the page: display and edit. An Activity Space can have more than one View, but in this example, the code for the two possible Views overlaps, so it is easier to use a variable to switch between the two modes. When the user first accesses the sample Activity Space, the page is displayed in Display Text mode as shown below.
Description of the illustration activityspace.gif

When the user clicks the Change Text button, the page is reloaded and displayed in Edit Text mode as shown below. The user can then type a different message in the text box. When the user clicks Save, the page is reloaded again, and displays the new message in Display Text mode. EditText mode
Description of the illustration activityspace_2.gif

This sampleactivityspace project uses the form framework and repost actions. The code does not allow guest users to access the custom Activity Space. This Activity Space has one custom View class, and utilizes a mode mechanism to display two different looks. The DisplayPage class extends PlumtreeDP, so the page also utilizes common Views (i.e., navigation, header and footer).

The name of the files is important; each one must follow the naming convention for the class it inherits or interface(s) it implements. For example, the name of the custom Activity Space class must end in "AS" (i.e., SampleActivitySpaceAS).

The CheckBasicAccess() method guarantees that the guest user will not be able to access this Activity Space.

Java:

public boolean CheckBasicAccess(String_strPage,String_strControl,
     boolean bSameSpace) 
   { 
     super.CheckBasicAccess(_strPage,_strControl,bSameSpace);
     //guest users cannot have access 
     return !PlumtreeHelpers.IsGuestSession(this);
   }

C#:

public override bool CheckBasicAccess(String _strPage, String _strControl,
bool bSameSpace) 
 {
base.CheckBasicAccess(_strPage, _strControl, bSameSpace);  
//guest users cannot have access 
return !PlumtreeHelpers.IsGuestSession(this); 
 }

The GetRepostControlName() method is required if the Activity Space has a Control. This method will return the name of the repost control class. If this method is not included, the repost control will not work. (If your Activity Space does not have a Control, this method is not needed.)

Java:

public String GetRepostControlName()
   { 
return SampleActivitySpaceRepostControl.STR_MVC_CLASS_NAME; 
   }

C#:

public override String GetRepostControlName()
 { 
return SampleActivitySpaceRepostControl.STR_MVC_CLASS_NAME;
 }

The Init() method registers the Model, DisplayPage, View, and Control.

Java:

public void Init(){
 
super.Init();
  
// Model
RegisterModel(SampleActivitySpaceModel.STR_MVC_CLASS_NAME); 
IModel myModel=GetModel(SampleActivitySpaceModel.STR_MVC_CLASS_NAME);   

// Display Page 
SampleActivitySpaceDPmyPage= new SampleActivitySpaceDP();
// use the form framework 
myPage.SetAddMainForm(true); 
RegisterPage(myPage);   

// View     
RegisterView(SampleActivitySpaceView.STR_MVC_CLASS_NAME,myModel);  
 
//Control 
RegisterControl(SampleActivitySpaceRepostControl.STR_MVC_CLASS_NAME, myModel); 
}

C#:

public override void Init() 
{ 
base.Init();  
 
// Model 
RegisterModel(SampleActivitySpaceModel.STR_MVC_CLASS_NAME); 
IModel myModel =   GetModel(SampleActivitySpaceModel.STR_MVC_CLASS_NAME);  
 
// Display Page 
SampleActivitySpaceDP myPage = new SampleActivitySpaceDP(); 
// use the form framework 
myPage.SetAddMainForm(true); 
RegisterPage(myPage);  
 
// View 
RegisterView(SampleActivitySpaceView.STR_MVC_CLASS_NAME,   myModel); 
  
//Control 
RegisterControl(SampleActivitySpaceRepostControl.STR_MVC_CLASS_NAME, myModel); 
}

Open the SampleActivitySpaceDP file (.java or .cs) in the sampleactivityspace project.

The GetTitleForBanner() method returns the title to be displayed on the header.

Java:

public String GetTitleForBanner() 
{ 
return "Sample Activity Space"; 
}

C#:

public override String GetTitleForBanner() 
{ 
return "Sample Activity Space"; 
}

The GetSubtitleForBanner() method returns the subtitle to be displayed on the header.

Java:

public String GetSubtitleForBanner()
{ 
return "Page 1";   
}

C#:

public override String GetSubtitleForBanner()
{ 
return "Page 1"; 
}

The PageDisplay() method gets all the HTML from the View(s) and puts it together to build the page's display.

Java:

public HTMLElement PageDisplay() 
{ 
return m_asOwner.GetView(SampleActivitySpaceView.STR_MVC_CLASS_NAME).Display(); 
}

C#:

public override HTMLElement PageDisplay() 
{ 
return m_asOwner.GetView(SampleActivitySpaceView.STR_MVC_CLASS_NAME).Display(); 
}

Open the SampleActivitySpaceModel file (.java or .cs) in the sampleactivityspace project. The class contains a field m_nMode to store the page's current mode. The text that is displayed is stored by the m_strDisplayText variable.

The SavePage() method saves the text entered in the text box while the page is in edit mode.

Java:

public int SavePage(String_sPageName, XPHashtable_htFormData) 
{ 
String[]data;   
data=(String[])_htFormData.GetElement(SampleActivitySpaceView.EDIT_TEXT_BOX); 
if((data!=null)&&!(0==data.length))
{
       m_strDisplayText=data[0]; 
}    
return RepostControl.PAGE_STATUS_VALID; 
}

C#:

public virtual int SavePage(String _sPageName, XPHashtable _htFormData) 
{ 
String[] data;   
data = (String[])     _htFormData.GetElement(SampleActivitySpaceView.EDIT_TEXT_BOX); 
if ((data != null) && !(0 == data.Length)) 
{ 
     m_strDisplayText = data[0];
}   
return RepostControl.PAGE_STATUS_VALID; 
}

The ChangeToEditMode() method sets the mode variable to EDIT_TEXT_MODE.

Java:

public void ChangeToEditMode() 
{ 
 m_nMode = EDIT_TEXT_MODE; 
}

C#:

public virtual void ChangeToEditMode() 
{ 
 m_nMode = EDIT_TEXT_MODE;
}

The ChangeToDisplayMode() method sets the mode variable to DISPLAY_TEXT_MODE.

Java:

public void ChangeToDisplayMode() 
{ 
m_nMode = DISPLAY_TEXT_MODE; 
}

C#:

public virtual void ChangeToDisplayMode() 
{ 
 m_nMode = DISPLAY_TEXT_MODE;
}

Open the SampleActivitySpaceRepostControl file (.java or .cs) in the sampleactivityspace project.

The PerformAction() method calls the method in the Model associated to the action performed on the View. For example, a repost action takes the input and saves it under a hidden variable to be passed as an argument to the Control's PerformAction method. In this example, the POSTTOSELF_ACTION_CHANGE_TEXT action includes another method call to the model, which alters the mode variable.

Java:

protected void PerformAction(int _nAction){ 
super.PerformAction(_nAction);     
switch(_nAction){        
       case POSTTOSELF_ACTION_CHANGE_TEXT: 
         ((SampleActivitySpaceModel)m_model).ChangeToEditMode(); 
         break;        
       case POSTTOSELF_ACTION_DISPLAY_TEXT: 
                  ((SampleActivitySpaceModel)m_model).ChangeToDisplayMode(); 
         break;      
     } 
   }

C#:

protected override void PerformAction(int _nAction) 
{ 
  base.PerformAction(_nAction); 
  switch (_nAction){     
    case POSTTOSELF_ACTION_CHANGE_TEXT: 
     ((SampleActivitySpaceModel) m_model).ChangeToEditMode(); 
      break;   
    case POSTTOSELF_ACTION_DISPLAY_TEXT: 
     ((SampleActivitySpaceModel) m_model).ChangeToDisplayMode(); 
      break; 
 } 
}

Open the SampleActivitySpaceView file (.java or .cs) in the sampleactivityspace project.

The Display() method calls the GetHTMLForDisplayText() and GetHTMLForEditText() helper methods to display the HTML Elements.

Java:

public HTMLElementDisplay(){ 
int nMode; 
HTMLElement myResult = new HTMLElementCollection(); 
try
{ 
    // extract the mode from the model 
    nMode=((SampleActivitySpaceModel)m_model).GetMode();   
       switch(nMode){   
         case DISPLAY_TEXT_MODE: 
           myResult.AddInnerHTMLElement(GetHTMLForDisplayText()); 
           break;   
         case EDIT_TEXT_MODE: 
           myResult.AddInnerHTMLElement(GetHTMLForEditText()); 
           break; 
       }   
}
catch(Exception e){ 
       log.Error(Component.Portal_Admin, 
 "Unexpected exception when displaying the sample activity space."); 
       } 
     } 
return myResult; 
}

C#:

public virtual HTMLElement Display() 
{ 
int nMode; 
HTMLElement myResult = new HTMLElementCollection(); 
try 
{ 
   // extract the mode from the model 
   nMode = ((SampleActivitySpaceModel) m_model).GetMode(); 
    switch (nMode){   
        case DISPLAY_TEXT_MODE: 
           myResult.AddInnerHTMLElement(GetHTMLForDisplayText()); 
           break;   
        case EDIT_TEXT_MODE: 
           myResult.AddInnerHTMLElement(GetHTMLForEditText());
           break; 
   } 
} 
catch (Exception e) 
{ 
   log.Error(Component.Portal_Admin, "Unexpected exception when displaying the sample activity space.");
} 
return myResult; 
}

The following portion of the helper method GetHTMLForDisplayText() displays the page in Display Text mode and simply shows the text and a change button.

Java:

private HTMLElement GetHTMLForDisplayText(){
HTMLElement myResult= new HTMLElementCollection();  
     HTMLTable myTable; 
     HTMLTableRow myRow; 
     HTMLTableCell myCell; 
     HTMLB myBold; 
     HTMLInput myInput;

     myTable = new HTMLTable(); 
     myResult.AddInnerHTMLElement(myTable); 
     myTable.SetBorder("0"); 
     myTable.SetCellPadding("5"); 
     myTable.SetCellSpacing("0");
     myRow = new HTMLTableRow(); 
     myTable.AddInnerHTMLElement(myRow);   

     // text that can be altered 
     myCell = new HTMLTableCell(); 
     myCell.SetStyleClass(PTStyleClass.OBJECT_TEXT); 
     myRow.AddInnerHTMLElement(myCell); 
     myBold = new HTMLB(); 
     myCell.AddInnerHTMLElement(myBold);        myBold.AddInnerHTMLString(((SampleActivitySpaceModel)m_model).GetDisplayText());
 
     // Change button 
          myInput= new HTMLInput(HTMLInputTypes.BUTTON,HTMLBUTTON_CHANGE,""); 
     myInput.SetValue("Change Text"); 
     myInput.SetStyleClass(PTStyleClass.FORM_EDITOR_BTN_TEXT); 
     myInput.SetOnClick( 
       "postToSelf(" 
        +SampleActivitySpaceRepostControl.POSTTOSELF_ACTION_CHANGE_TEXT 
         +");"); 
         
     // add some spacing between input box and button 
     myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
     myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
     myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE);     
 
     // add button 
     myCell.AddInnerHTMLElement(myInput); 
     return myResult; 
}

C#:

private HTMLElement GetHTMLForDisplayText()
{ 
  HTMLElement myResult = new HTMLElementCollection(); 
  HTMLTable myTable; 
  HTMLTableRow myRow; 
  HTMLTableCell myCell; 
  HTMLB myBold; 
  HTMLInput myInput;
 
  myTable = new HTMLTable(); 
  myResult.AddInnerHTMLElement(myTable); 
  myTable.SetBorder("0"); 
  myTable.SetCellPadding("5"); 
  myTable.SetCellSpacing("0");
  myRow = new HTMLTableRow(); 
  myTable.AddInnerHTMLElement(myRow);
 
  // text that can be altered 
  myCell = new HTMLTableCell(); 
  myCell.SetStyleClass(PTStyleClass.OBJECT_TEXT); 
  myRow.AddInnerHTMLElement(myCell); 
  myBold = new HTMLB(); 
  myCell.AddInnerHTMLElement(myBold); 
  myBold.AddInnerHTMLString(((SampleActivitySpaceModel)   m_model).GetDisplayText());
 
  // Change button 
  myInput = new HTMLInput(HTMLInputTypes.BUTTON,   HTMLBUTTON_CHANGE, ""); 
  myInput.SetValue("Change Text"); 
  myInput.SetStyleClass(PTStyleClass.FORM_EDITOR_BTN_TEXT); 
  myInput.SetOnClick("postToSelf(" +   SampleActivitySpaceRepostControl.POSTTOSELF_ACTION_CHANGE_TEXT +   ");");  
 
  // add some spacing between input box and button 
  myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
  myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
  myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE);
 
  // add button 
  myCell.AddInnerHTMLElement(myInput); 
  return myResult; 
}

The following portion of the helper method GetHTMLForEditText() displays the page in Edit Text mode, showing a text box holding the previously entered text and a Save button.

Java:

private HTMLElement GetHTMLForEditText(){ 
     HTMLElement myResult = new HTMLElementCollection();
 
     HTMLTable myTable; 
     HTMLTableRow myRow; 
     HTMLTableCell myCell; 
     HTMLB myBold; 
     HTMLInput myInput;
 
     myTable = new HTMLTable(); 
     myResult.AddInnerHTMLElement(myTable); 
     myTable.SetBorder("0"); 
     myTable.SetCellPadding("5"); 
     myTable.SetCellSpacing("0"); 
     myRow = new HTMLTableRow(); 
     myTable.AddInnerHTMLElement(myRow);
 
     // text box for inputting new text 
     myCell = new HTMLTableCell(); 
     myRow.AddInnerHTMLElement(myCell); 
     myInput = new HTMLInput(HTMLInputTypes.TEXT,EDIT_TEXT_BOX,""); 
     myInput.SetStyleClass(PTStyleClass.FORM_EDITOR_BTN_TEXT); 
          myInput.SetValue(((SampleActivitySpaceModel)m_model).GetDisplayText()); 
     myCell.AddInnerHTMLElement(myInput);
 
     // Save button 
     myInput= new HTMLInput(HTMLInputTypes.BUTTON,HTMLBUTTON_SAVE_TEXT,""); 
     myInput.SetValue("Save"); 
     myInput.SetStyleClass(PTStyleClass.FORM_EDITOR_BTN_TEXT); 
     myInput.SetOnClick( 
       "postToSelf(" 
        +SampleActivitySpaceRepostControl.POSTTOSELF_ACTION_DISPLAY_TEXT 
         +");");
 
     // add some spacing 
     myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
     myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
     myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE);
 
     //add button 
     myCell.AddInnerHTMLElement(myInput); 
     return myResult;
 
}

C#:

private HTMLElement GetHTMLForEditText() {
 
  HTMLElement myResult = new HTMLElementCollection(); 
  HTMLTable myTable; 
  HTMLTableRow myRow; 
  HTMLTableCell myCell; 
  HTMLB myBold; 
  HTMLInput myInput;
 
  myTable = new HTMLTable(); 
  myResult.AddInnerHTMLElement(myTable); 
  myTable.SetBorder("0"); 
  myTable.SetCellPadding("5"); 
  myTable.SetCellSpacing("0"); 
  myRow = new HTMLTableRow(); 
  myTable.AddInnerHTMLElement(myRow);
 
  // text box for inputting new text 
  myCell = new HTMLTableCell(); 
  myRow.AddInnerHTMLElement(myCell); 
  myInput = new HTMLInput(HTMLInputTypes.TEXT, EDIT_TEXT_BOX, ""); 
  myInput.SetStyleClass(PTStyleClass.FORM_EDITOR_BTN_TEXT); 
  myInput.SetValue(((SampleActivitySpaceModel)m_model).GetDisplayText()); 
  myCell.AddInnerHTMLElement(myInput);
 
  // Save button 
  myInput = new   HTMLInput(HTMLInputTypes.BUTTON,HTMLBUTTON_SAVE_TEXT, ""); 
  myInput.SetValue("Save"); 
  myInput.SetStyleClass(PTStyleClass.FORM_EDITOR_BTN_TEXT); 
  myInput.SetOnClick("postToSelf(" +   SampleActivitySpaceRepostControl.POSTTOSELF_ACTION_DISPLAY_TEXT   + ");");
 
  // add some spacing 
  myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
  myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE); 
  myCell.AddInnerHTMLString(CommonHTMLStrings.SPACE);
 
  //add button 
  myCell.AddInnerHTMLElement(myInput);
 
  return myResult; 
}

Once you have written the code for your new Activity Space, you must deploy it for use by the portal, described next.

Step 2: Deploying a Custom Project

After you create a custom project as described in the previous section, you must deploy it to the portal using Dynamic Discovery. For detailed information and instructions, see Chapter 18, "Deploying Custom Code Using Dynamic Discovery". (To deploy a custom Activity Space, use jar or dll-based Dynamic Discovery.)

The example below deploys the sample Activity Space code detailed in the previous section. Once you have deployed your code, confirm that it was deployed correctly as explained in Viewing Your Customization in the Portal.

Example: Sample Activity Space

These instructions use Visual Studio in .NET and Ant scripts in Java to deploy code.

Java

Open a command prompt and change the directory to SOURCE_HOME\ptshared\5.1.x (the location of the buildui.xml script).
Run a clean build using the following Ant calls: ant build ant install

The build target compiles the project, and the install target deploys the .war file.

Build the project in Visual Studio.
Visual Studio should copy the sampleactivityspace.dll file from SOURCE_HOME\sampleactivityspace\dotnet\prod\bin to PORTAL_HOME\webapp\portal\bin for you. If there are problems with Dynamic Discovery on startup, you might need to do this step manually. This is necessary to allow Dynamic Discovery to find the new library.

Viewing Your Customization in the Portal

Once you have deployed your code, view the changes in the portal to confirm that they were loaded correctly. Use Logging Spy to catch any obvious errors.

Open Logging Spy. For details, see Administrator Guide for Oracle WebCenter Interaction.
Start the portal.
Open a new browser window and navigate to the portal. Try to access the sample Activity Space by appending ?space=SampleActivitySpace to the current URL (i.for example, http://localhost:8080/portal/server.pt?space=SampleActivitySpace). It should fail because the the guest user should not be able to access the page.
Login as administrator and try to access the Activity Space again. You should be directed to the page in Display Text mode as shown in the first image in Step 1: Creating an Activity Space.
Click the Change Text button to see the page in Edit Text mode.
Type "Hello World" in the text box and click Save. The page should reload and the new message should appear in Display Text mode.
Change the text several times to make sure it works.

The next step is to debug your code, covered next.

Step 3: Debugging and Troubleshooting

This section lists technical tips for common problems and provides instructions on how to debug your new classes.

Technical Tips

If the page is not displayed in Edit Text mode when the Change Text button is clicked, make sure the GetRepostControlName() method in the SampleActivitySpaceAS class returns the name for the Control that you want to use. If this doesn't solve the problem, debug your code using the instructions below.

Debugging

These instructions use the sample Activity Space classes created in the previous sections as an example.

Java

In Eclipse, stop the Tomcat debugging session and open SampleActivitySpaceModel.java.
Add a breakpoint as shown below:
Description of the illustration javadebug.gif
In the Eclipse menu, click Run | Debug… and select the Tomcat application.
Choose the Classpath tab, select Add Projects, and add the sampleactivityspace project.
Hit Debug (and Save to retain your changes).
Open a browser and navigate to your Java portal. You should hit the breakpoint, since you are debugging the login page.

Stop the Visual Studio debugger (and close your browser if it is still open) and open SampleActivitySpaceModel.cs in Visual Studio.
Add a breakpoint as shown below:
Description of the illustration dotnetdebug.gif
Start the Visual Studio debugger (F5 or Debug | Start).
Navigate to your portal and log in again. You should hit this breakpoint, since you are debugging the login page.