Xtags for QuarkXPress Server

The Xtags Pro for QuarkXPress Server 6/7/8 XTension is an enhanced version of the corresponding client Xtags 6/7/8 XTension, with exactly the same core features, but with additional logic for operating in the QuarkXPress Server environment, and minus its normal user interface. (Preferences are controlled at invocation time by URL/form parameters.)

This Server version is also a Pro version, meaning it supports all the table-handling features of Xtags Pro.

Prerequisites

Before you can use this information effectively, you must understand the basics of installing, administering and using QuarkXPress Server as a web service, since we can’t really cover that all that here. (QuarkXPress Server 6 is called QuarkDDS in its current 3.5+ incarnation.)

Installation

To install Xtags Server, shutdown the XPress Server if it’s running, download the Xtags Server binaries (see right sidebar) appropriate to your platform (Mac/Win), and drag the appropriate version in the Xtensions subfolder of the XPress Server folder. Then restart the server, select the Server XTensions Manager and verify that the Xtags Server Xtension has status “Active”.

Operation

To invoke Xtags in the server environment, you use only one of the following Xtags URL parameters (or HTML form parameters) along with an otherwise standard DDS request:

• xtagsinputtext provides the actual input stream for Xtags;
• xtagsinputfile references a DDS document-pool relative file (using Web-style paths with / as the separator) to use as the input stream.

Xtags will attempt to find the autoflow text stream on the first page in the document being rendered, and import its input stream into that set of text boxes (one or more—contents are assumed to be empty). If it can’t find an autoflow stream, it will fail with an appropriate error message. (This means any Xtags-driven templates must have an autoflow text chain, even if it’s just a tiny “toe hold” invisible (no background color, no runaround) text box somewhere on the master page.)

The general intent with both of these control parameters is that Xtags will do its normal document-building with the given input, and then XPress Server will render the results.

For example, the simple URL (where host:port represents your DDS server’s host address and port, ignoring any line wrapping):

http://host:port/jpeg/mydoc.qxd?xtagsinputtext=Hello%20World.

asks XPress Server to render the document mydoc.qxd as a JPEG graphic, after giving Xtags as input the characters “Hello world.” (Awfully simple, but you get the idea.) Of course, in most cases, you’d send xtagsinputtext as an encoded HTML form <input type="text"> parameter of any length and content.

For another example, using xtagsinputfile, the URL (ignoring any line wrapping here)

http://host:port/pdf/myfiles/mydoc.qxd?xtagsinputfile=myfiles/builddoc.xtg

asks XPress Server to render the document myfiles/mydoc.qxd as a PDF file, after giving Xtags as input the contents of the file builddoc.xtg found in the myfiles folder under the Server document pool top-level folder. Of course, use of xtagsinputfile presumes you’ve managed to get that file uploaded to the server somehow.

Three boolean (value 1 for yes, or 0 for no) parameters control Xtags’ operation (these are the same as the UI preferences):

• convertquotes controls whether Xtags converts straight quote characters to their typographically correct cousins (default, if missing, is true);
• reporterrors controls whether Xtags inserts error messages inline or not (default false);
• suppresspictureerrors controls Xtags ignores errors when importing pictures or not (default false), if the presence or absence of any particular picture isn’t urgent.

So, for example, the URL (again, ignoring any line wrapping)

http://host:port/mydoc.qxd?xtagsinputfile=input.xtg&convertquotes=0&reporterrors=1&suppresspictureerrors=1

will render mydoc.qxd using the given Xtags input file, with quote conversion off, error reporting on, but with picture errors suppressed.

Xtags picture creation tag file paths (and translation tables) are looked up normally, using either absolute or relative paths. Relative paths are evaluated in the following order:

• if the path exactly matches a parameter name (in the current Server request form) whose mime type indicates that it’s an image file, then the given uploaded file is used;
• relative to the server document pool root folder;
• relative to the document itself;

and no file alias resolution is done (under XPress Server, unlike the client Xtags).

The general idea is that you can, in the server request HTML POST form, supply all text and graphics needed to build the current document, without reference to external files. You can also upload all graphics and text input files to somewhere in the document pool and reference them relatively. Or, you can mix and match these two approaches at will.

Using the sample files

With the sample files downloaded, unpack the .zip archive, and copy or move the xtags/ subfolder to the top level of your XPress Server document’s folder. Then (re)start XPress Server.

As a simple but complete end-to-end test that the files are in place and the Xtags Server XTension is working, try some URLs such as:

http://localhost:8080/jpeg/xtags/Demo%20template.qxd?xtagsinputfile=xtags/Basic%201.txt

http://localhost:8080/jpeg/xtags/Demo%20template.qxd?xtagsinputfile=xtags/Basic%201.txt

where you may have to replace localhost:8080 with your XPress Server hostname/IP address and port. You should see a page of (single large JPEG) output (that produced by importing the xtags/Basic 1.txt Xtags file into the Demo template.qxd template document. Try appending &page=2 to the end of this URL to see the second page (just a handful of lines, normally).

Then, move or copy the sample file .zip archive’s forms/ subfolder somewhere you can use it easily. From that folder, open demofile.html in your favorite web browser, and follow the directions embedded in the form. From there, you can select any of the other three demonstration forms, or open them in the web browser directly from the file system.

As another demonstration, you can build documents and retrieve results entirely from the command line, using utilities like curl. For example, in Terminal under macOS X, you can use something like

$ curl "localhost:8080/xtags/Demo%20template.qxd?xtagsinputtext=Hello%20world." >hello.jpg
$ open hello.jpg

to create and view the JPEG file resulting from processing the given Xtags input text with the given template.

Known limitations

Known limitations and problems with the current set of releases are:

• Imported .eps graphics files may not render properly.
• There are encoding interactions that XPress Server isn’t handling properly (or isn’t handling in its interaction with particular browsers, e.g., Safari under macOS). In particular, form data sent to XPress Server is assumed to be in the default ISO Latin 1 character set, so any Mac Roman (“high ascii”) characters in a form are not handled properly. This shows up on the Mac, for example, if you use curly quotes, chevrons, etc., in the sample forms we provide for testing and demonstration purposes. One simple workaround, for now, is to use <e1> as the first line in any form data, which tells Xtags to interpret the data it receives as being in the Windows extended character set (very close to ISO Latin 1).