Home   What's New    Inmagic Software    Consulting Services    Web Publishing Products    WebPublisher Examples
For IT Professionals    Web Database Hosting    Training Workshops    Bar Code Services    About Crew-Noble    Site Index    Contact Us

Inmagic® DB/Text® WebPublisher PRO
Inmagic® DB/Text® WebPublisher PRO Lite
Version 1.0 Technical Notes

Copyright © 2002 Inmagic, Inc. All Rights Reserved.

Contents

Welcome

Congratulations on your purchase of DB/Text WebPublisher PRO!

DB/Text WebPublisher PRO lets you add, update, and delete records in DB/TextWorks® textbases from a Web browser, making your textbases interactive over your corporate intranet, extranet, or the Internet.

WebPublisher PRO combines the searching power of DB/Text® WebPublisher with Extensible Markup Language (XML) and Simple Object Access Protocol (SOAP) capabilities. This allows you to integrate your DB/TextWorks textbases with other applications and create interactive forms using standard third-party tools (such as, Microsoft FrontPage).

To help you get started with WebPublisher PRO, we have created a Web tutorial, which is installed with the software. The tutorial walks you through adding a record via the Web to the Cars textbase, which is also installed with WebPublisher PRO and WebPublisher PRO Lite.

Crew-Noble, also provides consulting services (service@crewnoble.com). If you are an information professional with an idea—but not the XML skills to make it happen—we can help design screens and forms for you.

Note to WebPublisher PRO Lite Customers: These technical notes apply to your application, but you can only use the power of the product on a single textbase.

Audience

Before your users can start searching, editing, and deleting records over the Web, you must first design an interface that will allow for XML to be submitted and returned.

The designer and end users require the following:

WebPublisher PRO designer: Must have knowledge of XML and the ability to design a Web interface. Experience with Extensible Stylesheet Language transforms is useful, but not required. Use a third-party tool, such as Microsoft FrontPage or Microsoft ASP.NET, to design the Web interface. In 2003, Inmagic will provide an XML Forms Library, which will be accessible via the Web. The Forms Library will contain templates you can use to make the design process easier. In addition, an XSL transform for SOAP will soon be available on our Web site so you can enable WebPublisher PRO to accept SOAP calls.

WebPublisher PRO end users: To use the read-write capabilities of WebPublisher PRO, users need an Internet/intranet connection and, if the interface is client-based, Microsoft Internet Explorer.

Getting Started

Before you start designing an interface for WebPublisher PRO, take some time to familiarize yourself with the read-write features available to you. We have provided the following to help you get started:

There are three general phases you need to follow when you design an interface to let WebPublisher PRO end users edit, add, and delete records via the Web.

Phase 1: Create the XML query
Using the <Query> tag as the root element, develop a request to WebPublisher PRO asking it to perform an action (for example, a query, insert, update, or delete). The action you request will be enclosed in the <AC> element.

There are numerous ways to build your XML query, including using JavaScript in an .ASP page, which is displayed via an HTML page. You can even type the XML in Microsoft Notepad.

For more information about the actions you can submit and for sample code, see Submitting Actions to WebPublisher PRO.

Phase 2: Send the XML query to WebPublisher PRO
Once you have a valid, well-formed query, you must send it to WebPublisher PRO. There are a variety of ways you can do this.

For example, you can use Microsoft XML Core Services 4.0 (MSXML4), which was installed with WebPublisher PRO. MSXML4 has an HTTP response-and-request mechanism. You can also use other methods, such as Microsoft ASP.NET or SOAP.

Phase 3: Get a response back in XML
When you submit an action in XML (for example, a query, insert, update, or delete), WebPublisher PRO returns results in XML format.

The XML returned is enclosed in the <inm:Results> root element. The "inm" prefix is used in all element names in a WebPublisher PRO response.

For more information about WebPublisher PRO responses and sample output code, see Submitting Actions to WebPublisher PRO.

Note: If you only want to search for records, you can submit queries with a standard HTML query screen and get results back in HTML or XML format. You will not be able to modify the records using standard HTML WebPublisher commands.

Tutorial

During installation, an interactive tutorial is placed in the SAMPLE folder of the installation directory. You can use this tutorial to help you get started with WebPublisher PRO. The tutorial is made up of two files, ADDPRODUCT.HTM and ADDRECTUTORIAL.ASP. Created with Microsoft ASP, this tutorial lets you add records via the Web to the Cars textbase, which is also installed with WebPublisher PRO.

Note: During WebPublisher PRO Lite installation, the Cars textbase is specified by default as the textbase that can be searched/modified on the Web. Because WebPublisher PRO Lite allows for only one textbase to be Web enabled, you should accept the default if you plan to use the tutorial. You can change the textbase later.

An HTML document (WebPublisher PRO Tutorial.htm) provides information about and instructions for the tutorial.

During installation, if you are using IIS, the SAMPLE folder is given read and execute scripts access. If you are using other HTTP server software, you must give the folder this access, as it will not be done automatically.

Note: To use the read-write features of WebPublisher PRO, you must use Windows Explorer to give your IUSR account write permission to the directory containing the textbase(s) you plan to modify/delete. That means to use the tutorial, you must give your IUSR account write permission to the SAMPLE folder, as both the tutorial files and the Cars textbase reside there.

Use the tutorial to familiarize yourself with the read-write features of WebPublisher PRO. When you are ready to design your own interface, you can create it from scratch or modify the tutorial source code to meet your needs.

Input Schema Documentation

Before you start developing an interface, take some time to familiarize yourself with the structure of the WebPublisher PRO input schema. An HTML version of the schema documentation outlines all of the elements and attributes that can be submitted to WebPublisher PRO in XML.

The schema documentation is located at http://support.inmagic.com/webpublisher.

For more information about the input schema, as well as the two WebPublisher PRO output schemas, see the Schema section. For sample input code, see Submitting Actions to WebPublisher PRO.

Using Valid and Well-Formed XML

When submitting XML to WebPublisher PRO, all elements and attributes must be both: Important! Keep in mind that XML can be well formed but not valid. For example, <ac>update</ac> is well formed by the standard of the W3C because the starting and ending tags match. However, it is not valid because the <AC> element is uppercase in the WebPublisher PRO schema. The same holds true for attributes and their values. For example, <AC VALIDATION="Override"></AC> is well formed, but not valid. This is because the attribute "VALIDATION" and value "Override" are defined as lowercase in the WebPublisher PRO schema.

Required Namespace

Any action submitted to WebPublisher PRO must use the following namespace in the <Query> tag: "http://www.inmagic.com/webpublisher/query".

For example:


<Query xmlns="http://www.inmagic.com/webpublisher/query">

Using Valid Tag Names for Fields

When submitting field names to WebPublisher PRO in XML, all tags must be valid.

Field names containing characters that are unacceptable in XML should be modified as follows when being used as XML tags or when referring to the field name in a <MatchField> or <KeyField> tag:

Preserving White Space

If you want to preserve white space in the content of a field, wrap the content in CDATA.

For example:


<?xml version="1.0"?>
<Query xmlns="http://www.inmagic.com/webpublisher/query">
	<AC trim="y" validation="none">insert</AC>
	<TN>cars</TN>
	<KeyFields>
		<KeyField>Product-Number</KeyField>
	</KeyFields>
	<Recordset>
		<Record>
			<Product-Number>DH0001</Product-Number>
			<Name>Honda Civic</Name>
			<Description><![CDATA[    This model car has a working
			radio. Sold in California only.]]></Description>
			<Colors>Blue</Colors>
		</Record>		
	</Recordset>
</Query>

Submitting Actions to WebPublisher PRO

Any "action" you want WebPublisher PRO to perform is enclosed between the opening <AC> tag and closing </AC> tag.

The recognized actions are:

  • query. Searches for records in a textbase.
  • update. Modifies one or more existing records in the textbase. Update works like the DB/TextWorks® import feature in that it checks for matching records, then replaces fields when a match is found. If no match is found, the information is added as a new record.
  • insert. Adds one or more records to the textbase.
  • delete. Deletes one or more records from the textbase.
  • batch_delete. Deletes records from the textbase that satisfy a query.
  • tb_schema_query. Generates the output schema for the specified textbase. All fields in the textbase are included, except those hidden by a password.
  • rf_schema_query. Generates the output schema for the specified report form. A query must be specified. Only fields specified in the <RF> form are included.
  • tb_schema_output. Generates the output schema for results returned after a record has been modified using insert, update, delete, or batch_delete. Provides information about the textbase that you need to know when modifying records.
  • schema_input. Generates the input schema.

All actions are submitted within the <Query> root element. All results, except for those that return schemas, are returned within the <inm:Results> root element.

Important! Do not confuse the <Query> root element with the <AC>query</AC> command. The <Query> root element tells WebPublisher PRO that you are asking it to do something (for example, delete a record). The query command is used within the <AC> element to tell WebPublisher PRO that you are searching for records.

Using the Query Command

Use the query command to search for records in a particular textbase and return record information in XML format.

Note: You can search a textbase with standard HTML WebPublisher commands or with an XML interface. However, you cannot modify records (that is, insert, update, delete, or batch_delete) using standard WebPublisher commands; you must use XML input.

Sample input for a query:

Note that the proper namespace must be included in the <Query> root element.


<?xml version="1.0"?>
<Query xmlns="http://www.inmagic.com/webpublisher/query">
	<AC>query</AC>
	<TN>cars</TN>
	<QY>Find Name =supra</QY>
	<KeyFields>
		<KeyField>Name</KeyField>
		<KeyField>Retail-Price</KeyField>
		<KeyField>Dealer-Price</KeyField>
		<KeyField>Features</KeyField>
	</KeyFields>
</Query>

Sample output from a query:


<?xml version="1.0" standalone="yes"?>
<inm:Results productTitle="Inmagic DB/Text WebPublisher PRO" productVersion="1.0" 
xmlns:inm="http://www.inmagic.com/webpublisher/query">
	<inm:QY>Find Name =supra</inm:QY>
	<inm:Recordset AC="query" setCount="2">
		<inm:Record>
			<inm:Name>Supra</inm:Name>
			<inm:Retail-Price>266</inm:Retail-Price>
			<inm:Dealer-Price>133</inm:Dealer-Price>
			<inm:Features>Cleaning kit</inm:Features>
			<inm:Features>Independent suspension</inm:Features>
			<inm:Features>Interchangeable wheels</inm:Features>
			<inm:Features>Oil-filled shocks</inm:Features>
			<inm:Features>Tube tires</inm:Features>
			<inm:Features>Variable speed</inm:Features>
		</inm:Record>
		<inm:Record>
			<inm:Name>Supra</inm:Name>
			<inm:Retail-Price>428</inm:Retail-Price>
			<inm:Dealer-Price>214</inm:Dealer-Price>
			<inm:Features>Cleaning kit</inm:Features>
			<inm:Features>Independent suspension</inm:Features>
			<inm:Features>Interchangeable wheels</inm:Features>
			<inm:Features>Oil-filled shocks</inm:Features>
			<inm:Features>Tube tires</inm:Features>
			<inm:Features>Variable speed</inm:Features>
		</inm:Record>
	</inm:Recordset>
</inm:Results>
Sample error output from a query: 

<?xml version="1.0" standalone="yes"?>
<inm:Results productTitle="Inmagic DB/Text WebPublisher PRO" productVersion="1.0" 
xmlns:inm="http://www.inmagic.com/webpublisher/query">
	<inm:QY>Find name =volkswagen</inm:QY>
	<inm:Error code="110" extra="">No records found by latest query.</inm:Error>
	<inm:Recordset AC="query" setCount="0">
	</inm:Recordset>
</inm:Results>

Notes about the query command

  • There are two ways to specify what fields are returned after a query.
    • <KeyFields>. Use the <KeyFields> element to specify which fields you want the query to return in its XML output. If you do not specify any <KeyFields>, all fields are returned. Records are sorted using the textbase default sort, if any.
    • <RF>. Use the <RF> element to specify a sort other than the textbase default sort and/or if you want to show secondary textbase fields. That is, specify a report form that has a compulsory form sort and/or shows information from the secondary textbase fields you want. The XML output includes each of the fields specified in the form. For example, if a Report Form named Titles by Author sorts by the Author field, you can specify that form be used to sort by Author:
      • 
	<?xml version="1.0"?>
	<Query xmlns="http://www.inmagic.com/webpublisher/query">
		<AC>Query</AC>
		<TN>catalog</TN>
		<QY>Find Author CT Rand</QY>
		<RF>Titles by Author</RF>
	</Query>