Inmagic® DB/Text® WebPublisher PRO Tutorial

Inmagic DB/Text WebPublisher PRO allows users to add, modify and delete records in their textbases via the web using XML. This tutorial demonstrates adding a new record to a textbase with an ASP page. The web page will read information from an HTML form and submit that information to WebPublisher PRO. The ASP page will then display the response from WebPublisher PRO stating the status of the update.

The purpose of this tutorial is to illustrate the creation of a new record in a textbase with WebPublisher PRO. An understanding of ASP and JavaScript is assumed. This tutorial will focus on the following steps that are essential to the use of WebPublisher PRO:

  1. Creating an XML file/string to submit to WebPublisher PRO
  2. Sending that XML to WebPublisher PRO and catching the XML returned by WebPublisher PRO
  3. Processing the returned XML

 

Requirements

Inmagic DB/Text WebPublisher PRO

Internet Information Services 3.0 (IIS) for the ASP page

MSXML 4 Core services (installed by WebPublisher PRO)

Note: These requirements apply to this tutorial not to WebPublisher PRO. The same basic concepts shown here could apply to any technology that supports XML including but not limited to: ASP.NET, Java, ColdFusion, PHP, etc.

 

Installing the tutorial

  1. Place AddProduct.htm and addRecTutorial.asp in a directory that is accessible by IIS.
  2. Use the Internet Services Manager to give the directory permissions to run scripts.
  3. Verify that the Cars textbase exists in the Sample folder under the WebPublisher PRO install directory. This folder should have write permissions set for the default account (usually IUSR_computername) used by IIS for authentication. The sample directory and the Cars textbase are created during the WebPublisher PRO install, if you did not choose to install the sample textbase when installing WebPublisher PRO you will need to run the install again.

Adding new records with WebPublisher PRO

AddProduct.htm is a simple HTML form that submits data to the addRecTutorial.asp page. The ASP page pulls the information submitted from the form and formats that information into an XML Query that is then submitted to WebPublisher PRO. The ASP page then receives the XML response from WebPublisher PRO and pulls information from that response to notify the user of the success or failure of the update.

There are three pieces of information displayed by the ASP page. The top of the page displays the status of the update in HTML. The HTML text will notify the user if the record insert succeeded or failed and the reason why the insert may have failed. Below the text are two textarea boxes that display the raw XML that is sent to WebPublisher PRO and the XML that WebPublisher PRO returns in response to the XML insert.

Creating the XML Query for WebPublisher PRO

The ASP page creates an XML Query by building an XML string using information submitted from the HTML form via the GET method. This task is accomplished with the buildWpQuery function. This function simply creates a string of XML using basic string concatenation, the Request.QueryString method and the makeMultiple function.

The string concatenation is straightforward: here is an example that includes the AC, and TN elements:


strXmlInput   = '<?xml version="1.0" ?>\n' +
		'<Query xmlns="http://www.inmagic.com/webpublisher/query">\n'+
		'<AC>INSERT</AC>\n' +
		'<TN>Cars</TN>\n' +

                                                           continued . . .

The code above starts the XML Query and creates a string of XML. The new line "\n" is for readability in the XML Query that is displayed on the screen. It is not required by WebPublisher PRO. In the <Record> section of the XML, fields that do not require multiple entries use the Request.Querystring method to get information from the form and place the data between the appropriate field elements.

' <Product-Number><![CDATA[' + Request.QueryString("Product-Number") + ']]></Product-Number>\n' +

In the case of the "Product Number" field the space in the field name is replaced with "-" to create valid XML. CDATA is used to allow the end user to enter any non-extended character in the field and is used by wrapping the data submitted to WebPublisher PRO with the special CDATA tags, for example <![CDATA[ field data ]]>.

The makeMultiple function uses a delimiter to allow the user to create multiple entries within a field.


function makeMultiple(field, delimiter)
{  
   var xmlString = '';
   
   var strField = new String(Request.QueryString(field));
   var arrField = strField.split(delimiter);
   
   for(i=0;i<arrField.length;i++)
   {
      xmlString += '      <' + field + '><![CDATA[' + arrField[i] + 
']]></' + field + '>\n'; } return xmlString; }
This function takes two parameters, field and delimiter. The field name in this example must be valid XML so a space in the name is replaced with a hyphen. The delimiter can be any combination of characters that can be accepted by the JavaScript split function. In the tutorial the comma and space ", " are used as the delimiters because this will create multiple entries from a list.

Multiple entries are created by splitting the text from the Querystring on the delimiter. The loop then creates a field entry for every element in the array created by the split. The result turns a string like:

Cleaning kit, Custom decals, Glass

Into:

<Features><![CDATA[Cleaning kit]]></Features>
<Features><![CDATA[Custom decals]]></Features>
<Features><![CDATA[Glass]]></Features>

The XML for the field information is then added to the larger XML Query string.

Sending the XML Query and Receiving the XML Response

The submitWpXml function takes the XML Query as a string and sends it to WebPublisher PRO using the ServerHTTPRequest object of MSXML 4. MSXML 4 Core services provide a rich set of developer tools to develop XML applications. For more information see the resource section below. MSXML 4 is installed and used by WebPublisher PRO. If you would like to use MSXML 4 on a server without WebPublisher, it is available as free download from Microsoft.

The submitWpXml function uses ServerHTTPRequest which provides methods and properties that enable you to establish an HTTP connection between files or objects on different Web servers. While sending an XML file to a server and "catching" a response from the server may sound daunting, with MSXML 4 this is accomplished with 5 lines of JavaScript.


function submitWpXml(xmlString)
{  
   var xmlhttp = new ActiveXObject("MSXML2.ServerXMLHTTP.4.0");
   
   xmlhttp.open( "POST", "http://localhost/dbtwwpd/exec/dbtwpub.dll", 
false, "", "" ); xmlhttp.setRequestHeader( "Content-Type", "text/xml" ); xmlhttp.send (xmlString); return xmlhttp.responseText; }

The first line creates the ServerHTTPRequest object. The Open method of this object is the first called and specifies the method, URL, when control is returned to the script, username and password.

xmlhttp.open( "POST", "http://localhost/dbtw-wpd/exec/dbtwpub.dll", false, "", "" );

Open(Method, URL, ASync, UserName, Password ) method details:

Method- You should always use the POST method to send XML query information; WebPublisher PRO will not accept the GET method.

URL- The URL is the location of WebPublisher PRO, in this case we use localhost because it is assumed that this page will reside on the same server as WebPublisher PRO. This is not a requirement though. WebPublisher PRO can accept data from remote machines via the intranet or Internet.

ASync- This parameter determines whether the script waits until it gets a response from the server before it performs another action. The default False actually tells the MSXML not to return control to the script until it receives a response. There is a waitForResponse method that allows you to set the time the script will wait for a response.

UserName- The user to use for authentication, blank because we assume that the default IIS account for web access has the appropriate rights and permissions to modify the textbase.

Password- The password for the user above.

Once we have used open to set the properties for the connection to WebPublisher PRO, we use the setRequestHeader method to set the content-type to XML.

xmlhttp.setRequestHeader( "Content-Type", "text/xml" );

The Send method passes the JavaScript variable holding the XML Query to WebPublisher PRO at the URL we specified in the open method.

Xmlhttp.send(xmlString);

The last line in this function "catches" the WebPublisher PRO response.

Return xmlhttp.responseText;

In this function we return the response from the function so that it can be used elsewhere. It could easily be placed in a variable or displayed on the screen.

Process the XML returned by WebPublisher PRO

The last function in the ASP page processWpXml uses the MSXML 4 DOM document object to pull information from the WebPublisher PRO XML response. This is not the only way to handle the returned XML and the method you choose should depend on your skill set. The XML returned could have an XSL transform applied to it or be loaded into a dataset if that best suits your needs.

To process the WebPublisher PRO XML response, start by creating a DOM Document.

Var objWpResponse = new ActiveXObject("Msxml2.DOMDocument.4.0");
objWpResponse.async = false;

You must set the namespace to the Inmagic "records-processed" namespace.

objWpResponse.setProperty('SelectionNamespaces',
'xmlns:inm="http://www.inmagic.com/webpublisher/records-processed"');

Then load the document. If the document loads, then process the XML. If not, return the text of the error.

if (objWpResponse.loadXML(strXml))
{

Check for a WebPublisher PRO error such as "Unable to access textbase" by getting the error node and placing it in a variable.


	var ErrorNode = objWpResponse.selectSingleNode('//inm:Error');
         
   	if (ErrorNode == null) 
   	{

If the ErrorNode variable is null, there is no WebPublisher PRO error. Then we check for the results of the record processing and load the data returned into strings to use later for display.


      var objRecProcNode =
objWpResponse.selectSingleNode('/inm:Results/inm:Records-
Processed'); strAc = objRecProcNode.getAttribute("AC"); intSucceeded = objRecProcNode.getAttribute("succeeded"); intFailed = objRecProcNode.getAttribute("failed"); //set the value of Global Var that displays action status if(intSucceeded > 0) strStatus = "succeeded"; if(intFailed > 0) strStatus = "failed"; //Get Result attribute of the first record processed. var objIndvRecProcNode = objRecProcNode.firstChild; strRecResult = objIndvRecProcNode.getAttribute("Result"); //loop through the child elements of the first Rec processed. //This will be the keyFields and error if(objIndvRecProcNode.hasChildNodes) { var recNodeList = objWpResponse.selectNodes('/inm:Results/inm:Records-Processed/
inm:Record-Processed/*'); for(i=0;i<recNodeList.length;i++) { var objNode = recNodeList.nextNode(); strRecInfo += '<b>' + stripPrefix(objNode.nodeName) + ':</b> ' strRecInfo += objNode.text + '<br/>'; } } }

Display the text of the WebPublisher PRO error element if it exists.


   else
   {
      queryError = ErrorNode.text;    
   }
}

Display the error if the XML response fails to load.


      else
      {
         queryError = "Error: " + objWpResponse.parseError.reason;
      }

The end result of this function is that a group of variables are populated with the information about the results of the query and then that information is displayed as HTML output.

 

Resources

Web Resources

Perfect XML- PerfectXML Web site is designed to help you learn XML technologies and use them in your applications.

http://www.perfectxml.com/default.asp

w3schools XML Tutorial- In this XML tutorial you will learn what XML is, and the difference between XML and HTML. You will also learn how to start using XML in your applications.

http://www.w3schools.com/xml/default.asp

Microsoft MSDN XML- Probably not where you want to start as a beginner but the comprehensive resource for Microsoft’s XML tools.

http://msdn.microsoft.com/library/default.asp?url=/nhp/default.asp?contentid=28000438

XML in Libraries- How does XML help Libraries?

http://www.infotoday.com/cilmag/sep02/Banerjee.htm

Books

XML in a Nutshell, 2nd editon http://www.oreilly.com/catalog/xmlnut/

By W. Scott Means, Elliotte Rusty Harold

O'Reilly & Associates; ISBN: 0596002920; 2nd edition (June 15, 2002)

XML Application Development with MSXML 4.0 http://www.wrox.com/books/186100589x.htm

By Stephen Mohr, Steven Livingstone, Darshan Singh, Danny Ayers, Michael Corning

Wrox; ISBN: 1-861005-89-X

XSLT http://www.oreilly.com/catalog/xslt/
by Doug Tidwell (Paperback)

O'Reilly & Associates; ISBN: 0596000537; 1 edition (August 15, 2001)