View source for How to manage external objects with RuntimeContentHandler

[[Category:Howto]]
{{FeatureInfo
|editions=wcm,ecm,comm
|fromversion=6.0
|wikicomplete=80%
|interest=developer
|enduserlink=
|builderlink=
|developerlink=
|sysoplink=
}}
 
{| style="margin-left:2em;" align="right"
| __TOC__
|}

=Overview=
Sense/Net supports managing external objects using the portal infrastructure. For more details please check the [[External objects]] article. This page describes how can you manage external object on the portal using '''RuntimeContentHandler'''. This method supports displaying or editing individual items. To display lists of external items or handle them in more complex scenarios you should use the [[How to manage external objects with ISupportsDynamicFields|ISupportsDynamicFields interface]].

=Details=
You can wrap legacy types into regular portal content and display or edit them with well-known mechanisms: collection or editor portlets, using content views and field controls. To achieve this you should follow the steps below.

===Define a content type===
You should define a [[Content Type]] for the external type first. Note that it '''does not need to be installed as a regular content type''', you only have to create the content type XML and store it somewhere - you can even store it in the source code itself.
The new content type XML should contain all the fields of the external type that you want to display or edit. The field definitions are the same as in any other content type XML, the name of the fields will be used to map to the properties of the external type.

===Create a content view===
To display an individual external object you need to create a regular [[Content View]] for it. You can use common [[Field Control|field controls]] to edit the fields you defined in the previous step. The content view cannot contain the regular [[Command Buttons]] control to execute the '''Save''' action, you need to place an ASP.NET button into the view and handle the action in the portlet as seen in the next section.

Name the view as you want and place it somewhere in the ''/Root/Global/renderers'' folder.

===Create an editor portlet===
You need a simple editor [[Portlet|portlet]] to display a content that was made from an external object. This editor portlet consists of a few lines of code that creates a content and loads a content view created in the previous step. After editing the object it can be saved to the external database.

Put the following lines into the source code of the portlet:

<syntaxhighlight lang="csharp">
private IButtonControl _button;
protected IButtonControl SaveButton
{
 get { return _button ?? (_button = this.FindControlRecursive("BtnSave") as IButtonControl); }
}

protected override void CreateChildControls()
{
   //TODO:load the item you want to edit from the external database or web service
   _myObject = DB.LoadExternalItem();
   
   //wrap the object into a content using the predefined content type XML string
   var content = Content.Create(_myObject, ctdString);

   //load the content view
   var viewPath = "..."; //this is where you put the content view before
   _contentView = ContentView.Create(content, Page, ViewMode.InlineEdit, viewPath);

   Controls.Add(contentView);

   //add Save event handler
   if (this.SaveButton != null)
      this.SaveButton.Click += BtnSave_Click;

   ChildControlsCreated = true;
}
</syntaxhighlight> 

You need to implement the external object loading mechanism for your item. For example using a URL parameter or session variable to pass the identifier of the item to load.

The '''ctdString''' above is the whole content type XML that you created for the content.

When the user clicks the Save button, you only have to update the content and call the '''Save''' method and your external object will contain the data that the user gave on the UI.

<syntaxhighlight lang="csharp">
protected void BtnSave_Click(object sender, EventArgs args)
{
   _contentView.UpdateContent();
   var content = _contentView.Content;

   if (!_contentView.IsUserInputValid || !content.IsValid)
        return;

   //here the data will be saved to the external object
   content.Save();
   
   //TODO:implement the saving algorithm for the external object to the database
   DB.SaveObject(_myObject);

   CallDone();
}
</syntaxhighlight>

===Create a page for the editor===
The place of the editor page depends on the scenario you want to use it in. If the external object can be connected to one of the content in the Content Repository, you may create an action page for that content. For example an AddComment action for a blog post or an EditSubscription for a library.

You have to place the editor portlet created above onto this page. To be able to access this page, you need to place links to the page somewhere in the portal, where these external objects are listed. The link should contain a URL parameter for the particular object you want to display or edit for the portlet created above.

<syntaxhighlight lang="html4strict">
<a href="...?action=EditSubscription&itemID=1234">Edit this item</a>
</syntaxhighlight>

=Video=

=Related links=
*[[How to manage external objects with ISupportsDynamicFields]]
*[[Content Type]]
*[[Content View]]
*[[Portlet]]

=References=