Getting Started


Copyright © 2006 Inmagic, Inc. All rights reserved.

Overview

The process of updating textbase records involves sending commands, parameters, and field data to WebPublisher PRO in XML format. This document describes the commands, parameters, and format of the XML. A sample application is also included, demonstrating how the components can be assembled from information taken from an edit page. The application consists of a set of HTML edit pages that send information to an ASP page that, in turn, formats the information and sends it to WebPublisher PRO. The phrase WebPublisher PRO is used generically to refer to either DB/Text  WebPublisher PRO or CS/WebPublisher PRO, unless indicated otherwise.

The reader is assumed to have some knowledge of and comfort with XML, as well as the ability to construct Web applications.


Creating the XML Query for WebPublisher PRO

The root element of any XML input to WebPublisher PRO is the Query element. This is true for updates as well as searches or other activities. References in this document to an XML Query refer to this root element, not to a query that will perform a search.

Here is an example of XML to add a simple record to the textbase:

   <?xml version="1.0" ?>
   <Query xmlns="http://www.inmagic.com/webpublisher/query">
     <AC>INSERT</AC>
     <TN>CARS</TN>
     <Recordset>
       <Record>
         <Product-Number>ZZ1234</Product-Number>
         <Name>Porsche</Name>
         <Features>Working doors</Features>
         <Features>Working lights</Features>
       </Record>
     </Recordset>
   </Query>

Field entries are submitted within XML elements identified by the field name. Multiple entries in a field are represented by repeating the field element. Due to constraints on characters that may appear in XML element names, spaces in field names will be changed to hyphens or underbars. The default is hyphen ("-") for DB/Text WebPublisher PRO. For CS/WebPublisher PRO, the default is underbar ("_"), and it is substituted for hyphens in a field name, as well. Use the SOAPFormat attribute of the Query element to select the option you prefer, if it is different from the default.

The HTML forms in the example submit information to the ASP page using the GET method. The ASP page then creates an XML Query by building an XML-formatted string using the submitted information. This task is accomplished with the buildWpQueryXXX functions. These functions create 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>OPERATION</AC>\n' +
                 '<TN>TextbaseName</TN>\n' +
                 ...

The code above starts the XML Query and creates a string of XML. The \n (new line) 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.

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

CDATA is used to allow the end user to enter any non-extended character in the field (including characters such as < and &, which otherwise are special signal characters in XML).

The makeMultiple function constructs XML representing all of the entries in the 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 (spaces in the name replaced with a hyphen or underbar). The delimiter can be any combination of characters that can be accepted by the JavaScript split function. In the sample code, the vertical bar ( | ) is used as the delimiter.

Multiple entries are created by splitting the text from the Query string 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 WinHTTPRequest object of WinHTTP. MSXML 4 Core services along with WinHTTP provide a rich set of developer tools to develop XML applications. For more information, see the resource section below. MSXML 4 and WinHTTP are installed and used by WebPublisher PRO. If you would like to use WinHTTP and MSXML 4 on a server without WebPublisher PRO, it is available as a free download from Microsoft.

The submitWpXml function uses WinHTTPRequest 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 can be accomplished with the following lines of JavaScript:

   function submitWpXml(xmlString)
   {
      var xmlhttp    = new ActiveXObject("WinHttp.WinHttpRequest.5.1");
      xmlhttp.open("POST", "http://localhost/dbtwwpd/exec/dbtwpub.dll",false,"", "");
      xmlhttp.setRequestHeader( 'Content-Type', 'application/x-www-form-urlencoded' );
      xmlhttp.send (xmlString);

      return xmlhttp.responseText;
   }

The first line creates the WinHTTPRequest object. The Open method of this object is called first 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:

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 'application/x-www-form-urlencoded' - this encodes the request string to be a valid URL format.

   xmlhttp.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded'); 

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 recordsprocessed namespace.

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

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:RecordsProcessed');
         strAc = objRecProcNode.getAttribute("AC");
         intSucceeded = objRecProcNode.getAttribute("succeeded");
         intFailed = objRecProcNode.getAttribute("failed");  // get status of operation
         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: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.