2.7 Using Merge Includes to Format Responses

You can use a MergeInclude to format your results from a Content Server request based on an IdocScript include, rather than an entire template page.

A MergeInclude is a feature often used to integrate ASP pages using the IdcCommandX ActiveX module. The Content Server architecture is essentially a modular, secure, service-based application with multiple interfaces, although its architecture was designed to optimize the web interface. Services such as 'GET_SEARCH_RESULTS' will generate response data based on the 'QueryString' passed, and the user's security credentials. This response data is internally represented in the form of a HDA file. To see this in action, simply perform a search then add 'IsJava=1' to the URL. You will now see how data is internally represented for the response.

Because this HDA representation is not particularly useful for web-based users, so we use IdocScript includes and templates to format the response into a readable HTML page. A user can modify how this HTML is displayed by changing the template or a few resource includes with a component.

However, to retrieve only a small portion of this search result (for example, to display it on an ASP, JSP, or PHP page where the majority of the code is not IdocScript), or have an IFRAME or DIV element pop up and display the results, or to dynamically change how to display the results, you can simply add these parameters to your URL:

MergeInclude=my_custom_include&IsJava=1

This will cause the Content Server to bypass formatting the response according to the template that is specified in the service. It will instead format the response based on the IdocScript in 'my_custom_include'. For example, if you executed a search, then added the above line to the URL, and the include looked like this in your component:

<@dynamichtml my_custom_include@>
<html>
<table width=300>
<tr>
    <td><b>Name</b></td>
    <td><b>Title (Author)</b></td>
</tr>
<$loop SearchResults$>
<tr><td><a href="<$URL$>"><$dDocName$></a></td>
    <td><$dDocTitle$> (<$dDocAuthor$>)</td></tr>
<$endloop$>
</table>
</html>
<@end@>

This would display a search result page devoid of all images and formatting that you may not need. Consequently, you can format any Content Server response with any IdocScript include that you want. In theory, the IdocScript include can contain any kind of formatting that you want: XML, WML, or simply plain text.

For example, if you wanted to return search results in a format that can be read in an Excel Spreadsheet, you could create a resource include that returns a comma-delimited list of entries. You could then save the returned file to your hard drive, and then open it up in Excel. Another useful trick would be to create a resource include that formats the response into a record set that can be read in as a file by the IdcCommandX utility, or the BatchLoader. Such an include could be used with a search result, or an Active Report created with the Weblayout Editor, to build up batch files specific to arbitrary queries against the database or against the search index.

MergeInclude variables are cached differently than normal resource includes. Therefore, you must restart the Content Server if you make changes to the resource include. This can be bypassed if you execute a 'docLoadResourceInclude()' function to dynamically load different includes from within the MergeInclude.
The content type of the returned data is 'text/plain' and not 'text/html' for data returned by a MergeInclude. Some clients (such as IE and many versions of Netscape) still display plain text as html if you have valid HTML in the response, others clients may not. If you experience problems, you may need to manually set the content type when you link to it.