As you might guess evalIdcScp stands for “Evaluate Idoc Script” and it’s purpose is to allow IDOC script execution inside of a JSP page. This is great because even though IDOC/HCSP and JSP sites utilize completely different languages, the general interation with the content server can occur in a similar way.

An example of how evalIdcScp is commonly used is with fragment parameters. Consider these two examples, one in IDOC the other in JSP:

BackgroundColor = getValue("#active",ssFragmentInstanceID + "_BackgroundColor")

String BackgroundColor = serverbean.evalIdcScp("getValue(\"#active\",ssFragmentInstanceID + \"_BackgroundColor\")");

Both examples use the IDOC function getValue to retrieve the background color parameter. While it might look a little kludgy from a Java perspective, the fact is that there are a number of functions in IDOC that are coded for specific interactions within the content server, being able to leverage those functions in Java and JSP can make things quite a bit easier.

That’s great and all but are you seriously posting about a method?

Leveraging IDOC functions in JSP is nice but hardly ground breaking. Where I think things do get a little more interesting is when you realize that evalIdcScp is less of an eval function and more of an IDOC parser.

Here’s some code for a very simple yet traditional JSP static list fragment. The fragment will render a little “call out” list, basically a vertical group of link/title and description blocks.

//get a count of the number of rows in the list
String titleCountRaw = serverbean.evalIdcScp("ssGetXmlNodeCount(SS_DATAFILE, [Root]/Title')");
//convert the count to a number
int titleCount = Integer.parseInt(titleCountRaw);

//loop through all the nodes of the static list
for(int counter=1;counter<= titleCount;counter++){
//get the title
String Title = sb.evalIdcScp("ssIncludeXml(SS_DATAFILE, '[Root]/Title[" + counter + "]/node()')");
//get the link
String Link = sb.evalIdcScp("ssIncludeXml(SS_DATAFILE, '[Root]/Link[" + counter + "]/node()')");
//get the description
String Desc = sb.evalIdcScp("ssIncludeXml(SS_DATAFILE, '[Root]/Desc[" + counter + "]/node()')");
//render the html call out. note the ugly inline html.
%>
<div><h1><a href="<%=Link%>"><%=Title%></a></h1><%=Desc%></div>
<%
}


Again a pretty basic example, but one which reveals a fundamental weaknesses in many fragment designs; The HTML is often embedded in the code. This makes creating re-usable fragments much tougher and often when attempted involves just parameterizing CSS or other HTML attributes.

Using the evalIdcpScp method we may have an additional option in designing a more flexible, reusable fragment. Using out static list example from before, let’s also assume we have a BigText fragment parameter called “CallOutHTML”. We’ll also assume that when the example static list is added to a template the following mark up is placed in the parameter(notice the embedded IDOC):

<div>
<h1><a href="<$Link$>"><$Title$></a></h1>
<$Desc$>
</div>


We’ll then make some adjustments to the static list code, this time leveraging our new fragment paramter along with the evalIdcScp method.

//get the CallOutHTML html parameter
String CallOutHTML = sb.evalIdcScp("getValue('#active', ssFragmentInstanceId & '_CallOutHTML')");
//get a count of the number of rows in the list
String titleCountRaw = serverbean.evalIdcScp("ssGetXmlNodeCount(SS_DATAFILE, [Root]/Title')");
//convert the count to a number
int titleCount = Integer.parseInt(titleCountRaw);

//loop through all the nodes of the static list
for(int counter=1;counter<= titleCount;counter++){
//get the title
String Title = sb.evalIdcScp("ssIncludeXml(SS_DATAFILE, '[Root]/Title[" + counter + "]/node()')");
//get the link
String Link = sb.evalIdcScp("ssIncludeXml(SS_DATAFILE, '[Root]/Link[" + counter + "]/node()')");
//get the description
String Desc = sb.evalIdcScp("ssIncludeXml(SS_DATAFILE, '[Root]/Desc[" + counter + "]/node()')");

//put the title, link and desc back in to the binder as local values
sb.putLocal("Title",Title);
sb.putLocal("Title",Link);
sb.putLocal("Desc",Desc);

//and now the cool part...render the list
out.println(sb.evalIdcScp("$>" + CallOutHTML + "<$"));
}

So what just happened?

• We defined a big text parameter called CallOutHTML that contained all the HTML needed to render a call out. In the spots where we needed output values we placed IDOC variables using the standard IDOC syntax(not the HCSP variety).
• We began a standard loop through the static list pulling out our values from the the data file
• Rather than rendering the values right away to the page with inline HTML, we put those values back in to the binder as local data.
• evalIdcScp was called, passing CallOutHTML in as a parameter along with some funny syntax to close out and then open IDOC script before and after our CallOutHTML string. We did this because evalIdcScp evaluates the contents of it’s only argument as IDOC script, so immediately closing out the script allows us to pass HTML through and then only render the scripts inside the string.
• The server bean then executes CallOutHTML as IDOC script and since our three values (Title, Link and Desc) are in the local binder, the IDOC parser evaluates them and injectes them in to the HTML.

If this were another system, say one that used PHP or Python as it’s scripting language, I would have a real problem with this technique. If you generate presentation via a server side eval function you need to think long and hard about where the data being evaluated comes from because If it can come from a user prompt you’ve opened your application up to injection attacks.

Fortunately for us IDOC is no python. It’s a fundamentally safe language that can’t do very much other that read values you already have access to (workflow functions being the only exception). IDOC can call services but they are secured both by permissions as well as by type of use. As a general rule, if it makes a change in UCM you can’t script it.

A Simple MVC Pattern for Fragments?

In our static list example we’ve demonstrated how to separate the layer presentation from the fragment code and implemented it in more of a template-specific manner. The static list code with it’s generic Title, Link and Desc elements can now be re-used across a many different template and web sites. Very little consideration needs to be given for how the static list will be displayed, knowing that virtually any presentation requirement can be met with the fragment. As long as the situation calls for a static list with Title, Link and Description elements this fragment can be used. While I wouldn’t start calling this an MVC framework, I think we can start to see the hallmarks and benefits of MVC design.

New Bloggers

I’m adding a couple new bloggers to my recommended reading section which just shows as “recommended” because of the word wrap.

Alan Evan’s blog - www.cleverthink.com.  Alan, as the blog title goes, is a pretty clever guy who writes about technology, business and many of the new trends coming our way.  He’s a pretty active blogger, posting just about every other day.  It’s kinda funny because he sits about 30 feet from me at work and I never knew…now I do and I dig his blog so give it a read.

John Sim - www.bluestudios.co.uk/blog.  John’s blog apparently has been around for some time, but it appears he’s now starting working with Oracle’s Universal Content Server.  He has quite a bit of content on a variety of subjects, but is also posting some UCM examples.

New Component Version

All of my UCM examples and components are developed right here(as if you could see me) on my local laptop.  I’m running W2K03 server R2, Oracle enterprise 11g and Oracle UCM 10gr3 1.3.3.3(something like that…just patched so it ends with 3 now).  If your environment is different most of these examples will still work, but ocassionally there are issues.  For instance,  I had a request for a Stellent 7.5.1 and JVM 1.4.2 version of the IDOC Developer interface.  I don’t have a great 751 test environment, but I managed to dig one up at work.  It needed a couple tweaks, but over all pretty much the same.  Here’s the link though if you need that earlier version(rememebr you will need scriptaculous).

idocdeveloper_stellent751_java_142

Really, Really old Refinery Example

Way back in the day I had a lot of fun playing with Stellent’s inbound refinery.  In fact the first project ever posted to content on content management was a .NET example and framework to create a custom conversion engine for the 7.5.1 refinery.  Basically it was two projects; The framework which is just an assembly that provides an abstract class you inherit to create the conversion engine and an example conversion engine using the framework.  I wrote the post, threw it up on the site(then in DotNetNuke..yuck) and proceeded to ignore the blog for the better part of a year(I am pretty sure no one ever visited the site either).  By the time I actually started blogging 10gr3 was out with it’s whole new refinery and I never re-posted the project.  Then a few weeks ago on the Oracle forums I mentioned the example and there was a bit of intrest in the project.  I’ve actually had it posted for download for a little while now, but figured I would call some attention to it with this post.

Here’s the link:

.NET Custom Refinery Converter

The one issue I’ve run in to though is when developing web sites in Site Studio I find it’s hard to tap in to all of that wonderful localization functionality without changing the default system locale.  The problem appears to be that the localization is based on the user and since all anonymous users are essentially using the same account, they all appear to have the same locale.  I’ve read some posts on how to change the user’s locale by updating a cookie, either server side or by Javascript, but to be honest I’m not super crazy about that method.  Odds are everything will work fine 99.99% of the time, but what if a user has cookies disable or if the user is actually a search crawler which is ignoring cookies? It’s probably not going to work so well.

Enter the IdcLocale object

Changing the user’s locale during a service execution is actually an extremely easy thing to do.  Localization data is held in the IdcLocale object(intradoc.common package), which is stored during exection as a cached object named “UserLocale”.  If you wanted to access a user’s IdcLocale object, the syntax looks something like this:

IdcLocale MyLocale = (IdcLocale)context.getCachedObject("UserLocale");

Changing the locale take a couple more steps.  You first need load a new IdcLocale object specific to your locale and then you need to overwrite the old one.  Creating a new IdcLocale object is pretty simple, you use the LocaleResources object and call the static method, getLocale.  It takes a single argument, the name of the Locale you’re loading:

IdcLocale ItalianLocale = LocaleResources.getLocale("Italiano");

Once you have the new IdcLocale object, you only need to overwrite the old one and your locale is changed :

context.setCachedObject("UserLocale", ItalianLocale);

Putting it in action

I’ve put together a sample component which adds functionality for changing the user’s locale dynamically.  In tinkering with user locales, there are two customizations which I think can come in handy.

The first is customization is a filter attached to the ‘afterInitLocale’ event, which is fired right after the user’s locale is set during a service call and I’m pretty sure was put there specifically for changing the locale. In the component, the filter looks for a local binder value called ForceUserLocale. If it’s there and it’s a valid Locale name, then it swaps out the current user’s IdcLocale object with a new one. Post-switch, the service continues it’s execution evaluting the new Locale object.

The other customization basically wraps that same code in a new IDOC script function called setLocale. SetLocale takes a single argument, LocaleName, which is of course the name of a valid locale in the system. Calling the function immediatly switches out the user’s Locale with a new one. This is pretty cool if you’re working on a web page or template and wish to show the same or multiple strings in different languages.

Using the new setLocale function, the following code would display the same string on the same page in different languages:
<$setLocale("Italiano")$>
<$lc("wwPoweredBy")$>
<$setLocale("Italiano")$>
< $lc("wwPoweredBy")$>

Controllato dal sistema di gestione dei contenuti
Powered by Content Management System

Changing the Locale dynamically with a local binder value might not be the best fit for all implementations. If you install the sample component adding ForceUserLocale=Italiano to the URL will change the locale to Italian, which may or may not be undesirable. Nevertheless, I think the component demostrates some of the cool things you can do with the IdcLocale object.

The sample Anonymous User Locale component is can be downloaded here:
Anonymous User Locale Component

The component adds an admin-accessible interface for developing and executing IDOC Script.  Users can enter their script in to the very simple editor(just a textarea) and then execute it.  The resulting HTML is displayed in another area below the script editor.  Where I think it gets a little cooler though, is that it also outputs all local values created in the binder as well all resultset values in to windows-like box areas off to the side.  In addition you can also run the script as another user in the system to test out permissions and security. (NOTE: nice for development but probably bad for production so please be careful where you deploy this).

You essentially get a pretty clear view of what’s occurring with your script, but without restarting the server, saving a resource file or even refreshing a page.  The interface uses AJAX calls to execute the script and the parse the response.  The result is a responsive interface and what I think is a smooth experience…no jumping around to different windows or adding output variables to check values.

The app leverages the script.aculo.us/prototype javascript frameworks to handle the AJAX callbacks as well as the parsing and rendering of the data in the windows.  From an application architecture perspective, I basically added an admin only service called RUN_DEV_IDOC, which in turn calls a custom service handler class.  That class then creates and calls a new “stub” service to open up “clean” data binder and pager merger objects under the account of the requested user.  After that the IDOC script is executed, the results are returned and the data binder is parsed for local data and result sets.  All of that data is then wrapped in XML and dropped back in to the RUN_DEV_IDOC’s as a local data field.  The server then sends the response back to the page, where it’s parsed using javascript and used to create the output on the page.

My sort of grandiose idea on the plane was to create an editor with breakpoints, variable inspecting and watches.  I still may come back to that with a later updated version, but unfortunately the level of effort on that was a little more than two cross country trips.  Still this was a pretty fun app to work on and I personally look at it as unfinished, so check back in a few weeks and hopefully I’ll be able to add more to it.  Also if you have any ideas, I would love to hear them.

Feel free to download the component here:

IDOC Developer Interface

You will also need the script.aculo.us framework, which I’ve already wrapped in a component and can be downloaded here:

Script.aculo.us Component for Oracle/Stellent   

This sample project utilizes the YUI library to create that pop up as well as to provide a “slide” effect seen when the pop up appears and disappears. I was hoping to use a variety of YUI features, but unfortunately this example turned out to be extremely simple. It uses a similar “Panel” object to the one used in the Security Overrides example, however as you’ll see from this project it does not make any Connection Manager based AJAX calls like that one does.

This component has a couple IDOC resource overrides to add Pop Up Preview links to the Stellent UI, but in terms of actual code there’s a single Javascript class with really just a single major method, callPopUpPreview:

this.callPopUpPreview = function(id,name){
 //set the dID
 _dID = id;
 //set the dDocName
 _dDocName = name;//start the build of our URL
 var url = _httpCgiPath + "?IdcService=GET_DYNAMIC_CONVERSION"//if we have a dID add it to the url
 if(_dID)
  url += "&dID=" + _dID;//if we have a dDocName add it to the url
 if(_dDocName)
  url += "&dDocName=" + _dDocName;//if we have a revisionselectionmethod add it to the url
 if(_RevisionSelectionMethod)
  url += "&RevisionSelectionMethod=" + _RevisionSelectionMethod;//if we have a conversion template add it to the url
 if(_conversionTemplate)
  url += "&conversionTemplate=" + _conversionTemplate;//This line create the panel object
 YAHOO.popUpPreview.container.popupPreview = new YAHOO.widget.Panel("popUpPreviewDiv",
 { //set the width and hieght to the values set in the class
  width : _width + "px",
  height : _height + "px",
  //the pop up should be fixed to the center of the screen
  fixedcenter : true,
  //show a close link
  close:true,
  //don't allow dragging of the pop up
  draggable:false,
  //the panel starts out invisible
  visible:false,
  //this line sets the transision effect, where we are using the slide
  //effect and setting it's duration to .25 seconds.
  effect:[{effect:YAHOO.widget.ContainerEffect.SLIDE,duration:0.25}]
  } );//Sets the header / menu bar of the pop up
 YAHOO.popUpPreview.container.popupPreview.setHeader("Dynamic Conversion Preview");
 //Sets the body, note the use of the iframe to load the content. The onload event calls the handleiFrameLoad method to display the pop up
 YAHOO.popUpPreview.container.popupPreview.setBody("<iframe id='popUpPreviewBody' onload='Javascript:" + _objectName + ".handleiFrameLoad();' src='" + url + "'></iframe>");
 //render the panel to the page. this just starts the dynamic conversion call
 YAHOO.popUpPreview.container.popupPreview.render(document.body);
}}

The code does not come through so great on the blog, but what’s occurring is the URL to the dynamic conversion is assembled and then placed in the “src” attribute of an iFrame which is then written to a YUI panel object.  Why the iFrame?  Well when I started I intended to make more of a traditional AJAX call to get the dynamic conversion.  The problem though is that the dynamic converter creates a full HTML document complete with head and body elements, which can wreak havoc on the panel’s divs.  Using the iFrame let’s us encapsulate the dynamic conversion output in it’s own private little window and protects the rest of our panel and page from the variety of HTML that may be rendered in it. 

The callPopUpPreview method takes care of creating the URL to the dynamic conversion, creating the panel object and adding the iFrame to it, but it does not actually cause the panel display on the page.  Dynamic conversions can sometimes take a second or two to render and it’s a much nicer effect if we wait for the conversion before displayiing the pop up window.  So instead of just rendering the panel to the page, the onload event for the iFrame is used to call another method(handleiFrameLoad) in the popUpPreview class that can display the pop up once everything is loaded.  This way the pop up window will only appear once the conversion is complete.

Adding the actual links to the content server’s search results and content information pages requires a couple of resource include overrides: 

Append an additional PopupProps row in the extra_setup_search_results_action_popups include to add a links in the Search Results.
<@dynamichtml extra_setup_search_results_action_popups@> <$exec rsAppendNewRow("PopupProps")$>
<$exec setValue("PopupProps", "label", "Pop Up Preview")$>
<$exec setValue("PopupProps", "function", "Javascript:popUp.callPopUpPreview('<$url(dID)$>','<$url(dDocName)$>');")$>
<$exec setValue("PopupProps", "ifClause", "dcShowExportLink()")$>
<$exec setValue("PopupProps", "class", "document")$> <$exec setValue("PopupProps","id", "popuppreview")$>
<@end@>

The docinfo_conversion_link include can be used to add a link on the Content Information page
<@dynamichtml docinfo_conversion_link@>
<$include super.docinfo_conversion_link$>
<tr><td nowrap align="right"><span class="infoLabel"></span></td>
<td><span class="tableEntry">
<a href="Javascript:;" mce_href="Javascript:;" onclick="Javascript:popUp.callPopUpPreview('<$dID$>','<$dDocName$>');">Pop Up Preview</a></span>
</td></tr>
<@end@>


Also of note is that I used a new editor to create the popuppreview.js file. Rather than my standard text editor, I gave Adobe’s JSEclipse plug in a try. I am not sure I was using it correctly as the experience was not that much different from my text editor(only in eclipse), but as I figure out how to best use it’s features I’ll keep you informed.

The Pop Up Preview component is available for download here:

Pop Up Preview Component

The concept behind the example component, Security Overrides, is an IDOC enabled version of the Security Filter example, which is part of Stellent’s HowToComponents Bundle.  Stellent’s SecurityFilter component is an example of how to use the alterUserCredentials filter to change the rights of a user during a specific service request.  The primary example is the BlackHole check in example which grants everyone write access when checking in an item using the Black Hole service.

Creating security filters or overrides with the alterUserCredentials can be a tricky proposition.  Depending on your implementation, you’re basically altering the behavior of the content server with no real visible indication that it’s being done.  In addition the alterUserCredentials filter is called with every service call, so it’s a great place to cause a performance problem with inefficient code, or just by adding multiple security filter components.

So how does the Security Overrides component and more importantly IDOC help the situation?  The component creates a central, administrator controlled, interface for creating and managing overrides. What’s more, each service configured has an IDOC script prompt, which is used in the final decisioning of whether to apply the override or not.  For example if an administrator desired to only allow the “sysadmin” account access to the providers page, they would configure an override  that removed all permissions for the “GET_ALL_PROVIDERS” service.  In the IDOC prompt script would be added to evaluate the dUser variable, ensuring it was the “sysadmin” account.

The beautiful thing here is that because the component is processing IDOC for it’s final decsioning logic, the override becomes extremely simple to alter as well as include addtional actions down the road if desired.  And as you’ll see in the code, creating a component which can support IDOC scripting takes very little additional work.

In addition to integrating IDOC scripting in a Java-based component, the component also demonstrates:

• Creating an installation filter, which creates a database table after start up
• Working with the YUI library to create a model, pop-up form as well as creating and handling AJAX requests
• The run-time creation and altering of environment variables
• Customizing the Stellent / Oracle interface

As you might have guessed from the word “Introduction” in the title, I plan on making the review of this component a multi-part series, rather then one long post.  The component along with it’s source code will be available for download here.

I should also mention that Oracle has a fully supported component available for download which has some of the same features as this one.  It’s called the “Need to Know” component and if you are considering using my example in a production system, please take a look at their component first.

Security Overrides Component for Stellent / Oracle

Personally I find the renamed DOC_INFO method to be effective, but also a bit clunky.  I don’t like the idea of needing code on the page in order make my fragment work properly.  I’m even less of a fan of using the DOC_INFO_BY_NAME service.  The service consists of twelve actions which check, set and return values, 99% of which you will not need, just to get the DOC_INFO resultset, which was already loaded with the page(twice) prior to loading the fragment.  One or two fragments on a page calling the DOC_INFO_BY_NAME service probably won’t cause much of a problem, but add a few more and you’ll notice a perceptible delay in your load time.

What I’ve been looking for is a way to create fragments which can utilize the content region’s metadata, not cause a preformace drag on my page and also allow me to encapsulate all of my code in the fragment.  I want to just drop the fragment on the page and watch it magically start working.  Bonus:  I need it to work in IDOC or JSP.  Does Stellent have an out of the box way to answer this need?  I haven’t found one but there really should be, not only because it makes sense, but because they already have most of the code in place to support this functionality.

In the Site Studio classes folder there’s a class called SSCommon, which appears to provide a set of common(go figure) functions for Site Studio.  There are quite a few methods in the class, but two of them stand out, “getDocInfo” and “createCachedResultSet”.  Apply a little deductive logic, a little testing and you’ll quickly find that calling “getDocInfo” will retrieve or create a cached DOC_INFO resultset.

To make calling getDocInfo a bit easier as well as possible in IDoc,  I’ve created a component which adds an IDoc function called “ssGetCachedDocInfo”.  The code is pretty simple, remember Stellent/Oracle has done most of the work for us.

//create a new binder so we don't overwrite the fragment's doc_info
DataBinder CacheBinder = new DataBinder();
//call getDocInfo from SSCommon
SSCommon.getDocInfo(dDocName, service, CacheBinder, false, null);
//Retrieve the new DOC_INFO resultset
ResultSet myResultSet = CacheBinder.getResultSet("DOC_INFO");
//Create a dataresultset so we can save it
DataResultSet myResultSetdr = new DataResultSet();
myResultSetdr.copy(myResultSet);
//add it to the binder with a new name
binder.addResultSetDirect("DOC_INFO_" + dDocName, myResultSetdr);

As you can see the new Idoc function, ssGetCachedDocInfo, uses the getDocInfo method to retrieve the cached DOC_INFO resultset and then places it back in to the binder named DOC_INFO_ followed by the content id of the item.  I’ve left out all the code used to support an IDoc function, but the full version is available for download.

To test the ssGetCachedDocInfo function, create a new IDoc fragment and add the following code to a drop point/reference snippet.

Content ID: <!--$dDocName-->
Title: <!--$dDocTitle-->
Security Group: <!--$dSecurityGroup-->
Type: <!--$dDocType-->
<!--$endloop-->

<!--$result = ssGetCachedDocInfo(region1)-->
<!--$if rsExists("DOC_INFO_" & region1)-->
<!--$result = rsFirst("DOC_INFO_" & region1)-->
Content ID: <!--$getValue("DOC_INFO_" & region1,"dDocName")-->
Title: <!--$getValue("DOC_INFO_" & region1,"dDocTitle")-->
Security Group: <!--$getValue("DOC_INFO_" & region1,"dSecurityGroup")-->
Comments: <!--$getValue("DOC_INFO_" & region1,"xComments")-->
Type: <!--$getValue("DOC_INFO_" & region1,"dDocType")-->
<!--$endif-->

Add the fragment to a page with a content region and you’ll see the results.  The first block of code will retrieve and display the active DOC_INFO resultset, which will relate to the fragment not the region’s content item.  The second block executes the new ssGetCachedDocInfo IDoc function and retrieves the region’s metadata.  If you run a couple of SQL traces before and after adding the fragment to the page, you’ll note the lack of any additional doc info queries.

Since creating the function, we’ve found quite a few uses for it.  I’ve used it to create a related links call out, which uses the content region’s metadata in a search call to build a dynamic list of links in the site which relate to the content area.  I’ve also created a title fragment, which builds out the title tag dynamically for my pages, using the content region’s title.  Most interestingly though was what one of my colleagues did, which was use the function to retrieve cached metadata for items in a static list and therefore not actually found in a region on the page.

Feel free to download the component and the code here.