Prior to QuarkXPress Server 9.0, you had to use different URL constructions when sending
requests to an instance of QuarkXPress Server Manager in a QPS installation than you did
when sending requests to a free-standing instance of QuarkXPress Server Manager. In
versions 9.0 and later, both can use /qxpsm/request/ after [port]/ .
You can now use both absolute and relative paths when you modify a project with SDK
objects or classes. Relative paths are almost always relative to the document pool. If you
use multiple QuarkXPress Server instances, you should use a common document pool.
Interpreting the QXP Server Manager response
When QuarkXPress Server Manager successfully processes a request through the HTTP
interface, the response is the same as QuarkXPress Server's response unless the user has
supplied additional parameters to QuarkXPress Manager. For more information, see
"Working with QuarkXPress Server Manager" in A Guide to QuarkXPress Server.
If an error occurs, QuarkXPress Server Manager retries the request, either on the same
QuarkXPress server instance or a different one (depending on the error and global settings
established in the QuarkXPress Server Manager client). If QuarkXPress Server Manager
cannot process the request, it returns an XML response describing the error, plus any
header error codes returned by QuarkXPress Server. For example:
<?xml version="1.0" encoding="UTF-8" ?>
<error>
<httpresponsecode>500</httpresponsecode>
<xpressservererrorcode>-43</xpressservererrorcode>
<xpressservererrormessage>File not found.</xpressservererrormessage>
<xpressserverextendedmessage> <![CDATA[ Error #-43 - File not found. ]]>
</xpressserverextendedmessage>
<xpressservermanagererrorcode>M8000001</xpressservermanagererrorcode>
<xpressservermanagererrormessage>The server could not locate the specified
file.
</xpressservermanagererrormessage>
</error>
HTTP GET and POST Requests
The topics below describe how you can use HTML to interact with QuarkXPress Server.
QuarkXPress Server supports both the GET and POST HTML methods. When you use the
GET method, the browser encodes form data into a URL. When you use the POST method,
form data is passed within the message body. Use the GET method only when the form
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 15
GETTING STARTED
processing is idempotent. In short: GET is for retrieving data, whereas POST can involve
storing or updating data, ordering a product, or sending an e-mail.
Using HTTP GET with QXP Server
Use HTML like the following to specify a server and port where you want to send a request.
You can specify the name of the target project, the output type, and a scaling value. You
can specify the name of a box and the path of a text or picture files to import into that
box, as long as the file's path is on the server's file system. You can also use HTML like the
following to specify the page number and layout number of the project.
The form section of the HTML should begin with the following line of code:
<form id = form1 method="GET" enctype="application/x-www-form-urlencoded">
For both GET and POST, the browser constructs a form data set and encodes it according
to the ENCTYPE attribute (you can use multipart/form-data for POST and
application/x-www-form-urlencoded (the default) for both POST and GET).
To create fields that let the user specify the server IP address, the port, and the project
with the QuarkXPress Server Manager computer's IP address and [port] with the
QuarkXPress Server Manager port number.
These classes can be chained together to form compound QuarkXPress Server requests.
The sample applications (see "Sample applications") show how to use these classes to invoke
a QuarkXPress Server command and manipulate the response.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 19
GETTING STARTED
For more information, see "Using the Web interface." In addition to the classes listed there,
the Web services interface includes the following:
•
RequestService processes QuarkXPress Server requests. This object's generic
processRequest() method takes a QRequestContext argument and returns a
QContentData object containing the response. For more information, see the sample
applications and "Using the Web interface."
•
QRequestContext is the argument you pass to RequestService's generic
processRequest() method.This object contains settings which must be set once per
request. Set all chained requests inside the request context.
•
QRequest is the base class for all request objects (such as PDFRenderRequest).
Consequently, all request objects share some common data members.
•
RequestParameters is a generic class for executing any request and for adding dynamic
properties to a request.
•
NameValueParam is a generic class for adding dynamic properties to a request. This class
is specifically for requests that take a box's name and/or ID as the parameter name and
the box's content as the value.
QRequestContext
Description
•
QContentData is the response returned when a request is executed. QContentData is a
hyperlink that follows the same pattern as the classes above.
•
QException is the exception class for QuarkXPress Server Manager. Web services returns
a QException object if an error occurs with any Web service method. You can use try/catch
blocks to handle QException objects.
If you've written a Server XTensions module, you can extend the WIG to include any
changes it makes to the Modifier DTD by simply modifying an XML file and regenerating
the stubs.
To exclude empty tags in the request HTML, set the value of the appropriate variable to
null.
For Javadocs, WSDL schemas, and JSP samples, see the Welcome page that displays when
you launch QuarkXPress Server Manager.
The following topics describe the general Web services classes.
An argument passed to RequestService. Contains settings that must be set once per request. All
chained requests must be set inside the request context.
Web service data objectType
NameMembers
documentName
20 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
DescriptionTypes
File or object name on which the command will be rendered.String
GETTING STARTED
serverName
serverPort
userName
userPassword
maxRetries
requestTimeout
useCache
responseAsURL
bypassFileInfo
context
String
Integer
Boolean
Boolean
Boolean
Server name. Default is NULL. Load balancer searches for the host
itself in this case.
Port at which the desired server is listening.Integer
Server admin username.String
Server admin password.String
Max number of times to try executing the command before
returning failure.
Max time out in milliseconds.Integer
Indicates whether the cache should be checked for an existing
result or if the command should be executed again.
This value indicates whether the server should send the response
as-is (text or binary) or store the response on the server and return
its location as a URL. Because the object model works on SOAP,
which can be slow when transferring large binary files, you might
choose to set this value to "true" if you suspect that the response
is going to be several megabytes or larger.
Indicates whether file info should be fetched before executing the
command.
Context in which the command is being executed.String
//Create the service and call it QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Web service called to process the QuarkXPress Server request. RequestService has a generic method
named processRequest() that takes QRequestContext as an argument and returns QContentData
as the QuarkXPress Server response.
Web serviceType
processRequest
Processes the request context and returns the result.
QuarkXPress Server request is instances of request objects chained
together.
DescriptionTypeParameter
QRequestContextrequestCmd
Argument passed to
RequestService. Contains settings
that must be set once per request.
All chained requests are set inside
the request context.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 21
GETTING STARTED
createSession
closeAlldocs
closeDoc
Creates a new session and returns a session ID.
DescriptionTypeParameter
timeout
Closes all open documents in the session without saving them. If the session
does not exist, an error is returned. If an error occurs while closing the
document, it is logged and the document is marked closed in the internal
cache. No error is returned.
sessionId
Closes the specified document without saving it. If the session does not exist,
an error is returned. If the document is not open, and error is returned. If the
document is open in another session, an error is returned. If an error occurs
while closing the document, it is logged and the document is marked closed
in the internal cache. No error is returned.
Long
String
Timeout for the session in
milliseconds. If no call is executed
in that time, session is expired and
all the open documents in that
session are closed without saving. If
0 is passed as value of timeout,
default timeout is used. If a negative
value is passed as timeout, the
session never expires.
DescriptionTypeParameter
Session whose documents are to be
closed.
closeSession
getOpenDocs
getOpenSessions
getPreferences
setPreferences
DescriptionTypeParameter
docName
sessionId
Closes the specified session. If the session does not exist, an error is returned.
If any documents are still open in the session, an error is returned.
sessionId
Gets all the open documents in the session. If the session does not exist, an
error is returned.
sessionId
Gets all open sessions.
Gets QuarkXPress Server preferences.
Sets QuarkXPress Server preferences.
String
String
Document to be closed.String
Session in which document was
opened.
DescriptionTypeParameter
Session to be closed.String
DescriptionTypeParameter
Session whose open documents are
sought.
getXPressDOM
Creates a DOM for the specified document.
22 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
GETTING STARTED
newDoc
Creates a new document for modification and keeps it open until further
notice. The document is created with a single layout. To create a more complex
document, use the processRequestEx API. If a document with the same name
is already open, an error is returned. If the session does not exist, an error is
returned.
DescriptionTypeParameter
docName
jobJacketName
jobTicketName
host
String
String
String
Document to be opened for
modification. Provide the name
only. You can proivde a relative
path when you save the document.
Name of the Job Jackets file to be
used. The Job Jackets file is assumed
to be already available on the
QuarkXPress server computer.
Name of the Job Ticket to be used.String
The QuarkXPress Server instance
that should be used for this
document modification. If null, this
value is supplied by the load
balancer. If the indicated server is
not an active registered server, an
error is thrown.
openDoc
port
sessionId
Opens the specified document and keeps it open until further notice. If the
document is already open, an error is returned. If the session does not exist,
an error is returned.
docName
host
port
sessionId
Integer
String
String
String
Integer
String
The port for the server specified in
the host parameter.
Session in which the document
should be opened.
DescriptionTypeParameter
Document (along with relative path
if required) to be opened for
modification.
QuarkXPress Server instance which
should be used for this document
modification. If null, this value is
supplied by the load balancer. If the
indicated server is not an active
registered server, an error is thrown.
The port for the server specified in
the host parameter.
Session in which the document
should be opened.
processRequestEx
Executes the request context. If a session ID is specified, the document is kept
open after the request is executed. If no session ID is specified, the request is
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 23
GETTING STARTED
executed normally without keeping the document open. If the document is
open in another session, an error is returned. If the document is marked dirty,
an error is returned (a document is marked dirty when the server that opened
the document has become inactive; in such a case, the document must be
closed and opened again).
DescriptionTypeParameter
saveAllDocs
QRequestContextreqContextObj
sessionId
Saves all open documents in the session. The documents are saved one by
one. If error occurs while saving a document, an error is returned immediately
and the rest of the documents remain unsaved. If a document is marked dirty,
an error is returned (a document is marked dirty when the server that opened
the document has become inactive; in such a case, the document must be
closed and opened again).
relativePath
String
String
Request to be executed.
Session in which the request should
be executed. This value may be null.
If a session ID is provided, the
document is kept open. If no session
ID is provided, the request is
executed normally, as if
processRequest had been called.
DescriptionTypeParameter
Relative path where open
documents should be saved. If this
value is provided, copies of open
documents with changes made so
far are saved in the new location.
The open documents are not saved
but have all of the changes made so
far.
saveDoc
sessionId
Saves the open document. If a document is marked dirty, an error is returned
(a document is marked dirty when the server that opened the document has
become inactive; in such a case, the document must be closed and opened
again).
docName
newName
relativePath
String
String
String
String
Session in which the document
exists.
DescriptionTypeParameter
Document to be saved. Must be the
same name that was used when
opening or creating the document.
New name of the document. If null,
the document is saved with the old
name.
Relative path where the document
should be saved. The relative path
can also contain the new name of
the document. If this is provided, a
copy of the open document with
24 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
GETTING STARTED
changes made so far is saved in the
new location. The open document
is not saved but has all of the
changes made so far.
JPEGRenderRequest jpegRequest = new JPEGRenderRequest();
rc.request = jpegRequest;
RequestService svc = new RequestService();
QContextData response = svc.processRequest(rc);
Base class for all request objects (such as PDFRenderRequest). All request objects share some common
data members, which are described below.
Web service data objectType
Lets you create a DOM of a particular layout or portion of a layout.
Creates an XML string out of the DOM.
Takes a raw XML representation of a project as a string and returns an object
model representing that project, with Project as the root class.
String
Session in which the document
exists.
Additional
comments
NameMembers
RequestParameters
Generic class for executing any request and for adding dynamic properties to a request.Description
Web service data objectType
NameMembers
requestNamespace
You can use this class to send any request for which a specific class does not exist. When this
request exists in the chain, its namespace is concatenated with the namespaces of other requests.
That means the namespace provided here can be null.
The parameters of this class can be used to parameterize a request being sent to the server.
DescriptionTypes
QRequestrequest
QuarkXPress Server request that includes instances of request objects
chained together.
DescriptionType
Namespace of the request (for example, jpeg).String
NameValueParam[]params
Parameter array for the specified request (for
example, jpegquality).
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 25
GETTING STARTED
Example, object
model
NameValueParam
Description
QRequestContext rc = new QRequestContext();
RequestParameters request = new RequestParameters();
request.setRequestNamespace("jpeg");
rc.setRequest = request;
NameValueParam p1 = new NameValueParam();
p1.setParamName = "jpegquality";
p1.setTextValue = "4";
request.setParams(new NameValueParam[]{p1});
Generic class for adding dynamic properties to a request. This class is specifically for requests that take
a box name/id as the parameter name and the box content as the parameter value.
Web service data objectType
NameMembers
paramName
textValue
streamValue
String
String
byte[]
DescriptionType
Name of the parameter. In most cases this will be the name/ID of
the box.
Text value of the box. (You can set either textValue or
streamValue.)
Stream value of the box. (You can set either textValue or
streamValue.)
contentType
QContentData
A response to a Web Services call to QuarkXPress Server.Description
Web service data objectType
NameMembers
contentType
textData
responseURL
streamValue
encodingType
actualServerPortUsed
The MIME content type of the parameter.String
String
String
String
binary
String
DescriptionTypes
The type of the response. For example, "text/xml" or
"text/plain."
If the response type is text, this contains the text.
Otherwise, this value is null.
If the responseAsURL parameter was set to "true" in the
request, this contains the URL of the response.
Otherwise, this value is null.
If the response type is binary, this contains the byte
array. Otherwise, this value is null.
If the response type is text, this value indicates the
encoding of the text (for example, UTF-8 or ANSI).
Identifies the server port.String
actualServerUsed
26 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Identifies the server.String
GETTING STARTED
Example, object
model
QException
Type
headers
multipartResponse
QRequestContext context = new QRequestContext();
context.setDocumentName("sample.qxp");
context.setResponseAsURL(true);
JPEGRenderRequest request = new JPEGRenderRequest();
request.setJPEGQuality("4");
context.setRequest(request);
RequestService requestService = new RequestServiceStub();
QContentData response = requestService.processRequest(context);
System.out.println(response.getResponseURL());
Exception class for QuarkXPress Manager.Description
Exception
NameMembers
httpResponseCode
managerErrorCode
String
String
If the response returned by the server is a set of headers,
this array contains the header response.
If the response returned by the server is multipart, this
array contains the multipart response parts.
DescriptionTypes
HTTP response code.String
QuarkXPress Server Manager error code.String
Example,
object model
QXP Server Manager
managerErrorMessage
serverErrorCode
serverErrorMessage
serverExtendedMessage
String docName = "notexisting.qxp";
try {
QRequestContext ctx = getRequestContext(docName);
QRequest request = getJPEGRequest();
ctx.setRequest(ctx);
QContentData response = getService().processRequest(ctx);
System.out.println(response.getResponseURL());
} catch (QException ex) {
// QuarkXPress Manager threw an QException and it is not
// a runtime exception. QException object will be returned.
System.out.println(ex.getServerErrorCode());
}
QuarkXPress Server Manager localized error message.String
QuarkXPress Server error code.String
QuarkXPress Server response message.String
QuarkXPress Server extended error message.String
The following topics are for people who want to enhance QuarkXPress Server Manager or
integrate it with other software.
Please refer to http://localhost:8090/qxpsmdocs/apidocs/index.html for manager
API documentation. (Note that the port number used to retrieve the API documentation
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 27
GETTING STARTED
is 8090 by default, but you should use whatever port number you specified when installing
QuarkXPress Server Manager.)
QuarkXPress Server Manager was developed using interface-based programming and uses
the Spring Framework to instantiate pluggable objects. When QuarkXPress Server Manager
starts up, it reads the contents of a Spring context definition file named
"ManagerContainerConfig.xml" and instantiates all of the beans listed in the file.
QuarkXPress Server Manager then initializes by reading various configuration options
from a file named "ManagerConfig.xml."
You can deploy QuarkXPress Server Manager in its own Tomcat container, in an external
Tomcat container, or in a shared Spring context. For more information, see "Deploying
QuarkXPress Server Manager" in the QuarkXPress Server ReadMe.
28 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Using the Web interface
The topics below describe the features available via the QuarkXPress Server Web interface.
The topics covered here include the following:
• Render types are namespaces you can use to return a QuarkXPress project in a specified file
format.
• Render modifiers let you control which parts of a project are rendered and set the scale of
the returned renderings.
USING THE WEB INTERFACE
• Content modifiers let you alter the content and formatting of boxes in layouts without using
the XML modify parameter.
• XML modify lets you modify QuarkXPress projects using XML.
•
The xml namespace deconstructs a project according to the Modifier DTD. The construct
namespace lets you turn an XML representation of a QuarkXPress project back into a
QuarkXPress project.
• Administrative request handlers let you change the behavior of QuarkXPress Server.
QuarkXPress Server uses case-sensitive XML.
Understanding rendering
Rendering is the process in which QuarkXPress Server opens a QuarkXPress project,
transforms it into a different format (the render type), and then sends a response to the
requestor. Depending on the type of rendering operation, the response may be a message
or a rendered file.
For information on how to submit a render request, see "Getting started: HTTP and HTTPS."
Alerts
document type.
Please select a
QuarkXPress
document or
template.
HTTP Error #500Cannot open this
This alert displays if you try to render a file that is not a QuarkXPress project.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 29
USING THE WEB INTERFACE
read or write to disk.
required volume or
folder.
HTTP Error #404File not found
QuarkXPress Server Error #–43
This alert displays if you try to render a project that does not exist.
HTTP Error #500I/O error trying to
QuarkXPress Server Error #–36
This alert displays if QuarkXPress Server is running on Windows and a shared
network folder was selected as the document pool, but the folder is no longer
shared.
What to do: In the QuarkXPress Server administration interface, choose
Administration > Preferences > General and set Document Root Folder
to a shared folder.
HTTP Error #404Cannot find
QuarkXPress Server Error #–35
This alert displays if QuarkXPress Server is running on Mac OS and a shared
network volume was selected as the document pool, but the volume is no
longer shared.
What to do: In the QuarkXPress Server administration interface, choose
Administration > Preferences > General and set Document Root Folder
to a shared folder.
Example, GET
URL
Understanding logging
If a request succeeds, a transaction success message is written to the QuarkXPress Server
transaction log file. This message includes the transaction ID, date, time, request type,
project name, response type, response size in bytes, and client IP address. For example:
If an alert is displayed, an error message is written to the QuarkXPress Server transaction
log file. The transaction entry contains the date and time of the request, the error code,
and the error message. The following is a sample of an error log transaction entry:
See Understanding loggingLogs
http://localhost:8080/sample.qxp
There are two ways to specify a render format:Notes
1. Enter the render type directly in the browser address
field:http://localhost:8080/pdf/project.qxp.
2. In the QuarkXPress Server administration interface, choose Administration > Preferences >General and choose the default render type from the Default Renderer Type drop-down menu.
09/03/2011 13:54:33 - RequestURI = /sample.qcd TransactionUUID =
dffc3a7e-11fd-4d97-b3fe-8f2129353d58 Client = 10.91.30.216 Error #10120 Cannot open this document type. Please select a QuarkXPress document or template.
30 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
The "QuarkXPress Server Log.log" file also contains system-level log information. For
example, if a request makes a renderer stop working, you can figure out which request it
was using the transaction ID and the transaction log.
09/03/2011 014:00:07 ERROR
[com.quark.qxps.core.server.ServerRendererMonitor][pool-1-thread-1] - The
QuarkXPress Server Renderer with processId 2620 had quit while processing the
transaction 87212dae-6ba3-4b3f-97bb-ea8f0c255bf9.
To download all logs to a non-server computer, click Show Transaction Log in the
QuarkXPress Server Web interface, then click Download Logs on the upper right.
Understanding render types
Render types are namespaces you can use to return a QuarkXPress project in a specified file
format. The topics covered here include the following:
USING THE WEB INTERFACE
QuarkXPress Server Manager object model classesDescriptionFunction
ave
raw
Returns a .zip file containing an App Studio
AVE issue file and its corresponding manifest.
Returns an EPS file.eps
Returns an ePUB file.epub
Returns a JPEG image.jpeg
Returns a PDF file.pdf
Returns a PNG image.png
Returns a PostScript file.postscript
Returns a QuarkCopyDesk article.qcddoc
Returns a QuarkXPress project file.qxpdoc
Returns an RLE Raw Custom format image.qxpr
Returns a project in a QuarkXPress internal
format.
Returns a low-resolution PDF file.screenpdf
Returns a SWF file.swf
AVERenderRequest
EPSRenderRequest
EPubRenderRequest
JPEGRenderRequest
PDFRenderRequest
PNGRenderRequest
PostScriptRenderRequest
CopyDeskDocRequest
QuarkXPressRenderRequest
RLERawCustomRenderRequest
RawCustomRenderRequest
ScreenPDFRenderRequest
SWFRenderRequest
The default render type is JPEG.
Developers can implement additional rendering formats through server XTensions software.
ave
The ave render type returns a .zip file containing an App Studio AVE issue file and its
corresponding manifest.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 31
USING THE WEB INTERFACE
Namespace
Parameters
Render modifier
parameters
AVE
outputstyle
format
layout
page
pages
stylename
String
String
range)
Lets you specify an output style. To
use a named output style, use the
name of that output style. For
example:
//STEP1: Create the QuarkXPress Server Request
//Context and set the necessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
This alert displays if you submit a render request with
the box parameter.
This alert displays if you specify a nonexistent output
style.
This alert displays if you specify an output style that
is incompatible with this render type.
HTTP Error #10120Cannot open this document type. Please
This alert displays if you submit an ave request for a
QuarkCopyDesk article.
HTTP Error #10545AVE-Doc for an App Studio layout is not
This alert displays if you submit an ave request with
//STEP 2(SPECIFIC TO REQUESTS):
//Create the AVE renderer
//request and embed it in the request context.
AVERenderRequest avereq = new AVERenderRequest();
avereq.setAVEData(request.getParameter("AVEData"));
avereq.setFormat(request.getParameter(
"Format"));
avereq.setLayout(request.getParameter(
"Layout"));
requestCtx.setRequest(avereq);
//STEP3: Create the WIG service and call the
//processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data =
service.processRequest(requestCtx);
The default AVE output style is used.Notes
The eps render type returns an EPS rendering of a page or spread.
Namespace
Parameters
EPS
outputstyle
epsformat
epspreview
epsdata
epstransparent
stylename
color
tiff | none
ascii | binary |
clean8bit
1 | 0 | true | false
| yes | no
Lets you specify an output style. To
use a named output style, use the
name of that output style. For
example:
//STEP1: Create the QuarkXPress Server Request
//Context and set the necessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
1 | 0 | true | false
| yes | no
HTTP Error #406The renderer for this image type has no
This alert displays if you submit a render request with
the pages or box parameter.
This alert displays if you specify a nonexistent output
style.
This alert displays if you specify an output style that
is incompatible with this render type.
Lets you specify whether to
download all fonts required by
imported PDF and EPS files.
//STEP 2(SPECIFIC TO REQUESTS):
//Create the EPS renderer
//request and embed it in the request context.
//STEP3: Create the WIG service and call the
//processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data =
service.processRequest(requestCtx);
USING THE WEB INTERFACE
Notes
epub
Namespace
Render modifier
parameters
Alerts
You can specify an output style and set additional local parameters of that output style. For
example, if no bleed setting is specified in the output style named "mystylename", you can
specify a bleed setting with a URL like the following:
You can override settings in an output style. For example, if an asymmetric bleed is specified
in the output style named "mystylename," you could override it with the same URL.
If you do not specify an EPS output style, the default EPS output style is used.
The epub render type returns an ePUB rendering of a layout or layout family.
ePUB
layout
outputstyle
An ePUB (.epub) file.Response
way of rendering the desired objects.
String
String
HTTP Error #406The renderer for this image type has no
This alert displays if you submit a render request with
the pages or box parameter.
Lets you specify a layout by name
or ID. The first layout is Layout 1.
Lets you specify an ePUB output
style by name or ID.
Example, GET URL
Example, object
model
HTTP Error #10543ePub not created. There is no reflow
//STEP1: Create the QuarkXPress Server Request
//Context and set the necessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
//STEP 2(SPECIFIC TO REQUESTS):
This error appears if there is no reflow layout.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 35
USING THE WEB INTERFACE
jpeg
The jpeg render type returns a JPEG rendering of a page or spread.
//Create the ePUB renderer
//request and embed it in the request context.
EPubRenderRequest epubreq = new EPubRenderRequest();
epubreq.setEPubData(request.getParameter("EPubData"));
epubreq.setCreateTOC(request.getParameter(
"CreateTOC"));
epubreq.setLayout(request.getParameter(
"Layout"));
requestCtx.setRequest(epubreq);
//STEP3: Create the WIG service and call the
//processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data =
service.processRequest(requestCtx);
You can only create an ePUB file from a project that includes a reflow article.Notes
Namespace
Parameters
Render
modifier
parameters
JPEG
jpegquality
upadateimage
updateflow
pasteboard
showboxoutline
boxes
page
scale
1 | 2 | 3 | 4
true | false
true | false
true | false
Float .1 to 6.92 for
Windows .1 to 8
on Mac OS)
Lets you specify the image quality of a rendered JPEG
image. The valid values are: 1 (highest quality), 2 (high
quality), 3 (medium quality), and 4 (lowest quality). The
default value is 1.
Lets you specify whether to update imported pictures.true | false
Lets you specify whether to update the text flow version
of a project to the current version.
Lets you specify whether to display pasteboard items.
Works only with spread parameter. The default value is
true. For example:
http://localhost:8080/jpeg/document.qxp?
spread=1&pasteboard=true
Lets you specify whether to include bounding box outlines
in the response JPEG image even if the boxes have no
content.. The default value is false.
Lets you request multiple boxes.String
Lets you request a single page.Integer
Lets you specify a scaling percentage. The valid values are
from .1 (10%) to 8 (800%) on Mac OS or 6.92 (692%) on
Windows.
box
spread
layout
Integer
String
36 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Lets you request a single box.String
Lets you specify a spread. The first spread is spread 1. In a
facing-page document, spread 1 consists of the first page.
Lets you specify a layout by name or ID. The first layout
is Layout 1.
// STEP1: Create the QuarkXPress Server Request
// Context and set the necessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
// STEP2: Create the JPEG renderer request and attach it
// to the request context.
JPEGRenderRequest jpreq = new JPEGRenderRequest();
jpreq.setJPEGQuality(request.getParameter("jpegQuality"));
jpreq.setLayout(request.getParameter("Layout"));
requestCtx.setRequest(jpreq);
// STEP3: Create the WIG service and call the processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data = service.processRequest(requestCtx);
The literal render type returns the contents of a file without any attempt to process it
as a template. Depending on the file's MIME type, the requested project can be displayed
within the browser (for example, if the response is a JPEG file) or saved to disk (for example,
if the response is a Microsoft Word document).
Namespace
Alerts
Example, GET URL
Example, object
model
literal
The requested file returned in the HTTP response.Response
Incorrect
administration
realm username
and password.
See Understanding loggingLogs
http://localhost:8080/literal/Story.doc
Request object name: LiteralRequest
com.quark.qxpsm.QRequestContext rc =
new com.quark.qxpsm.QRequestContext();
if(!this.DocumentSettings1.documentName.Text.Equals(""))
rc.documentName = this.DocumentSettings1.documentName.Text;
rc.request = new LiteralRequest();
//Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
HTTP Error #401
This alert displays if you specify an invalid administrator user name and
password.
What to do: Use the user name and password set in the Authentication pane
of the General Preferences dialog box (Administration > Preferences >General) in the QuarkXPress Server Web interface.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 37
USING THE WEB INTERFACE
pdf
The pdf render type returns a PDF rendering of a project.
Namespace
Parameters
PDF
outputstyle
title
subject
author
keywords
includehyperlinks
exportlistsashyperlinks
stylename,
document
1 | 0 | true |
false | yes | no
1 | 0 | true |
false | yes | no
Lets you specify an output style. To use a named
output style, use the name of that output style.
For example:
Lets you specify the subject of the PDF file.String
Lets you specify the author of the PDF file.String
Lets you specify keywords for the PDF file.String
Lets you specify whether to include hyperlinks
in the PDF file.
Lets you specify whether to export lists as
hyperlinks. To use this parameter, you must set
includehyperlinks to true.
exportindexesashyperlinks
exportlistsasbookmarks
mode
printcolors
plates
produceblankpages
useopi
1 | 0 | true |
false | yes | no
1 | 0 | true |
false | yes | no
composite or
separations
cmyk, rgb,
grayscale,
cmykandspot,
asis
inripseps
1 | 0 | true |
false | yes | no
false | yes | no
Lets you specify whether to export the index as
hyperlinks. To use this parameter, you must set
includehyperlinks to true.
Lets you specify whether to export lists as
bookmarks. To use this parameter, you must set
includehyperlinks to true.
Lets you specify whether the PDF file is a
composite or includes separations.
Lets you specify the color space of the PDF file.
This option is available only when mode is set to
composite.
Lets you specify a separation method. This option
is available only when mode is set to
separations.
Lets you specify whether to include blank pages.
This option is available only when mode is set to
composite.
Lets you specify whether to use OPI.1 | 0 | true |
38 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
images
registration
offset
bleed
offsetbleed
spreads
lowresolution
colorimagedownsample
grayscaleimagedownsample
includeimages,
omittiff,
omittiffandeps
off, centered,
offcenter
points)
symmetric
0–6 (in inches)
false | yes | no
false | yes | no
9–2400
Lets you specify whether to include TIFF and EPS
images from an OPI server.
Lets you include, omit, and configure registration
marks.
Lets you specify the offset of registration marks.0–30 (in
Lets you specify a bleed type.pageitemsonly,
Lets you specify a bleed offset to use. This option
is available only when bleed is set to
symmetric.
Lets you specify whether to output spreads.1 | 0 | true |
Lets you request a low-resolution (36 dpi) PDF.1 | 0 | true |
Lets you specify the resolution of color images.9–2400
Lets you specify the resolution of grayscale
images.
monochromeimagedownsample
colorcompression
grayscalecompression
monochromecompression
pdffile
psfile
thumbnail
mode
9–2400
true | false
true | false
true | false
String
String
separations
Lets you specify the resolution of monochrome
images.
Lets you specify whether medium-quality manual
JPEG compression should be applied to color
images.
Lets you specify whether medium-quality manual
JPEG compression should be applied to grayscale
images.
Lets you specify whether ZIP compression should
be applied to monochrome images.
Lets you specify the PDF name. This option is
available only when PDF to Folder is selected in
QuarkXPress Server PDF preferences.
Lets you specify the PostScript file name. This
option is available only when PostScript for laterDistilling is selected in QuarkXPress Server PDF
preferences.
Lets you embed a thumbnail in the PDF file.bw | color
Lets you specify the PDF file's color mode.composite |
fontdownload
yes | no
Lets you turn font download on or off. You
cannot specify which fonts are downloaded.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 39
USING THE WEB INTERFACE
layers
verification
separate
produceblankplates
download
layoutstart
String
yes | no
1 | 0 | true |
false
1 | 0 | true |
false | yes | no
Lets you specify which layers should be included,
as a comma-separated list.
Lets you use PDF/X–1a or PDF/X–3 verification.pdfx1a | pdfx3
Lets you specify whether to output each page as
a separate file.
Lets you specify whether to include blank plates.yes | no
When download is true, the browser always
displays a dialog box that lets the end user save
the returned file, even if the browser can display
it.
When download is false, the browser attempts
to display the returned file. If the browser cannot
display the file, it lets the end user save the
returned file.
The default value is false.
Lets you specify the number of the first layout
to render when you render multiple layouts as
separate PDF files. PDF files are saved at the
location specified in QuarkXPress Server
preferences (Administration > Preference >General > Server > Document Root Folder). The
first layout in a project is layout 0. For example:
Lets you specify the number of the last layout to
render when you render multiple layouts as
separate PDF files. PDF files are saved at the
location specified in QuarkXPress Server
preferences (Administration > Preference >General > Server > Document Root Folder). The
first layout in a project is layout 0. For example:
This alert displays if you try to render a a project that
contains only blank pages.
This alert displays if you specify a nonexistent output style.This Output Style does not exist.
This alert displays if you specify an output style that is
incompatible with this render type.
Example, object
model
Request object name: PDFRenderRequest
// STEP1: Create the QuarkXPress Server Request Context
// and set the nescessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
// STEP 2(SPECIFIC TO REQUESTS):
// Create the PDF renderer request
// and embed it in the request context.
PDFRenderRequest pdfreq = new PDFRenderRequest();
pdfreq.setAuthor(request.getParameter("Author"));
pdfreq.setTitle(request.getParameter("Title"));
pdfreq.setLayout(request.getParameter("Layout"));
pdfreq.setSpread(request.getParameter("Spread"));
pdfreq.setPage(request.getParameter("mPage"));
pdfreq.setPages(request.getParameter("Pages"));
if( strLowResolution !=null &&
strLowResolution.equals("True"))
pdfreq.setLowResolution("true");
requestCtx.setRequest(pdfreq);
// STEP3: Create the WIG service and
// call the processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data =
service.processRequest(requestCtx);
For more information about the object model, see the samples.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 41
USING THE WEB INTERFACE
Notes
Namespace
Parameters
png
There are three ways to generate PDF files with QuarkXPress Server. You can generate a PDF file in
QuarkXPress Server and return it to the end user, generate the PDF in QuarkXPress server and save
it to a folder on the server computer, or generate a PostScript file for later distilling and save it to
a folder on the server computer. To choose one of these output methods in QuarkXPress Server,
choose Administration > Preferences > Renderer > PDF) and then click DirectPDF, PDFtoFolder,
or PS4D (PostScript for Later Distilling). If you choose either of the last two options, click Browse
and navigate to the target folder, then choose an option from the Default Name drop-down menu.
You can specify an output style and set additional local parameters of that output style. For example,
if no bleed setting is specified in the output style named "mystylename", you can specify a bleed
setting with a URL like the following:
You can override settings in an output style. For example, if an asymmetric bleed is specified in
the output style named "mystylename," you could override it with the same URL.
If you do not specify a PDF output style, the default PDF output style is used.
The png render type returns a PNG rendering of a page or spread.
PNG
pngcompression
1 | 2 | 3 | 4
Lets you specify the compression of a PNG response. The valid
values are: 1 (lowest compression), 2 (medium compression),
3 (high compression), and 4 (highest compression). The default
value is 1.
Render modifier
parameters
transparentpng
upadateimage
updateflow
boxes
page
scale
box
spread
layout
A PNG file.Response
true | false
true | false
Float .1 to
6.92 for
Windows .1
to 8 on
Mac OS
Integer
String
Lets you specify whether to generate a PNG file that uses
transparency.
Lets you specify whether to update imported pictures.true | false
Lets you specify whether to update the text flow version of a
project to the current version.
Lets you request multiple boxes.String
Lets you specify a single page.Integer
Lets you specify a scaling percentage. The valid values are
from .1 (10%) to 8 (800%) on Mac OS or 6.92 (692%) on
Windows.
Lets you request a single box.String
Lets you specify a spread. The first spread is spread 1. In a
facing-page document, spread 1 consists of the first page.
Lets you specify a layout by name or ID. The first layout is
Layout 1.
// STEP1: Create the QuarkXPress Server Request
// Context and set the nescessary properties
com.quark.qxpsm.QRequestContext rc =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
rc.setDocumentName(docName);
// STEP 2(SPECIFIC TO REQUESTS):Create the PNG renderer
// request and embed it in the request context.
PNGRenderRequest pngreq = new PNGRenderRequest();
pngreq.setPNGCompression(request.getParameter(
"PNGCompression"));
pngreq.setLayout(request.getParameter("Layout"));
pngreq.setSpread(request.getParameter("Spread"));
pngreq.setPage(request.getParameter("mPage"));
rc.setRequest(pngreq);
// STEP3: Create the WIG service and call the processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data = service.processRequest(rc);
The postscript render type returns a PostScript rendering of a project.
To use settings that have been captured with the Capture
Settings in the QuarkXPress Print dialog box, use
document. For example:
http://localhost:8080/
postscript/
sample.qxp?outputstyle=document
Render modifier
parameters
Alerts
updateimage
updateflow
page
pages
spread
layout
A PostScript file.Response
invalid.
The document
requested contains
only blank pages.
Lets you specify whether to update imported pictures.true | false
true | false
range)
Integer
String
HTTP Error #500This page range is
QuarkXPress Server Error #147
This alert displays if you try to render an invalid page range.
HTTP Error #500No file produced.
This alert displays if you try to render a a project that contains only blank pages.
Lets you specify whether to update the text flow version of
a project to the current version.
Lets you specify a single page.Integer
Lets you specify a range of pages.String (page
Lets you specify a spread. The first spread is spread 1. In a
facing-page document, spread 1 consists of the first page.
Lets you specify a layout by name or ID. The first layout is
Layout 1.
Example, GET
URL
Example, object
model
HTTP Error #500PostScript printer
mapped to file not
found
does not exist.
This Output Style
cannot be used
with this render
type.
See Understanding loggingLogs
http://localhost:8080/postscript/Sample.qxp
Request object name: PostScriptRenderRequest
// STEP1: Create the QuarkXPress Server Request
// Context and set the nescessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
This alert displays if the PostScript printer or driver is not set to Print to File.
This alert displays if you specify a nonexistent output style.This Output Style
This alert displays if you specify an output style that is incompatible with this
render type.
44 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
// STEP 2(SPECIFIC TO REQUESTS):
// Create the Post Script renderer
// request and embed it in the request context.
PostScriptRenderRequest pscreq =
new PostScriptRenderRequest();
pscreq.setPrintBleed(request.getParameter("PrintBleed"));
pscreq.setPrintPPD(request.getParameter("PrintPPD"));
pscreq.setPages(request.getParameter("Pages"));
requestCtx.setRequest(pscreq);
// STEP3: Create the WIG service and call the
// processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data = service.processRequest(requestCtx);
To create a PostScript file, you must have a PostScript driver on the server computer.Notes
You can specify an output style and set additional local parameters of that output style. For example,
if no bleed setting is specified in the output style named "mystylename", you can specify a bleed
setting with a URL like the following:
You can override settings in an output style. For example, if an asymmetric bleed is specified in
the output style named "mystylename," you could override it with the same URL.
If you do not specify a PostScript-compatible output style, the default PostScript-compatible output
style is used.
Namespace
Parameters
qcddoc
The qcddoc render type returns a QuarkCopyDesk article.
qcddoc
article
component
format
saveastemplate
String
String
lightweight |
fullfeatured
true | false
Lets you specify which article in a project to render.
For example:
Lets you modify the article with XML. For more
information, see "Using XML modify."
Example, GET
URL
Example, object
model
qxpdoc
Namespace
Parameters
The article/component
name is not unique.
See Understanding loggingLogs
http://localhost:8080/qcddoc/copydesk/sample.qcd
Request object name: CopyDeskDocRequest
This alert displays if you create or change the name of an article or
component so that it is the same as the name of an existing article or
component.
The qxpdoc render type returns a QuarkXPress project.
qxpdoc
qxpdocver
upadateimage
8 | 9
true | false
Indicates the QuarkXPress version format to use. For example:
Lets you specify whether to return modified pictures in the
response or not. If set to false, modified pictures are not
returned. If set to true, modified pictures are returned. The
default value is true.
saveastemplate
true | false
46 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Lets you save a copy of a project as a template. The default
value is true. For example:
this image type
has no way of
rendering the
desired objects.
QuarkXPress
Project down to an
earlier version.
See Understanding loggingLogs
http://localhost:8080/qxpdoc/sample.qxp
Request object name: QuarkXPressRenderRequest
// STEP1: Create the QuarkXPress Server Request
// Context and set the nescessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
String
HTTP Error #500QuarkXPress
This alert displays if Disable QXD Return is checked in the QuarkXPress Server
administration interface (Administration > Preferences > General > Server).
HTTP Error #406The renderer for
This alert displays if you submit a qxpdoc render request with the page, pages,
box, or spread parameter.
HTTP Error #500Cannot save a
This alert displays if you attempt to save a QuarkXPress 6.x project to an earlier
version of QuarkXPress with the qxpdocver parameter.
Lets you specify a layout by name or ID. The first layout is
Layout 1.
// STEP 2(SPECIFIC TO REQUESTS):Create the QuarkXPress
// renderer request and embed it in the request context.
QuarkXPressRenderRequest qxpreq = new
QuarkXPressRenderRequest();
qxpreq.setDocumentVersion(request.getParameter(
"XpressDocVersion"));
qxpreq.setLayout(request.getParameter("Layout"));
requestCtx.setRequest(qxpreq);
// STEP3: Create the WIG service and call the processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data = service.processRequest(requestCtx);
screenpdf
The screenpdf render type returns a low-resolution PDF rendering of a project. This
render type overrides the PDF Workflow setting in the QuarkXPress Server administration
interface (Administration > Preferences > Renderer > PDF) and always sends the PDF
file to the browser.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 47
USING THE WEB INTERFACE
Namespace
Parameters
Screenpdf
outputstyle
title
subject
author
keywords
includehyperlinks
exportlistsashyperlinks
stylename
1 | 0 | true | false |
yes | no
1 | 0 | true | false |
yes | no
Lets you specify an output style. To use a named
output style, use the name of that output style.
For example:
Lets you specify the subject of the PDF file.String
Lets you specify the author of the PDF file.String
Lets you specify keywords of the PDF file.String
Lets you specify whether to include hyperlinks
in the PDF file.
Lets you specify whether to export lists as
hyperlinks. To use this parameter, you must set
includehyperlinks to true.
exportindexesashyperlinks
exportlistsasbookmarks
mode
printcolors
plates
produceblankpages
useopi
images
1 | 0 | true | false |
yes | no
1 | 0 | true | false |
yes | no
composite or
separations
cmyk, rgb,
grayscale,
cmykandspot, asis
inripseps
1 | 0 | true | false |
yes | no
yes | no
includeimages,
omittiff,
omittiffandeps
Lets you specify whether to export the index as
hyperlinks. To use this parameter, you must set
includehyperlinks to true.
Lets you specify whether to export lists as
bookmarks. To use this parameter, you must set
includehyperlinks to true.
Lets you specify whether the PDF file is a
composite or includes separations.
Lets you specify the color space of the PDF file.
This option is available only when mode is set to
composite.
Lets you specify a separation method. This option
is available only when mode is set to
separations.
Lets you specify whether to include blank pages.
This option is available only when mode is set to
composite.
Lets you specify whether to use OPI.1 | 0 | true | false |
Lets you specify whether to include TIFF and EPS
images from an OPI server.
48 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
registration
offset
bleed
offsetbleed
spreads
lowresolution
colorimagedownsample
grayscaleimagedownsample
monochromeimagedownsample
colorcompression
off, centered,
offcenter
symmetric
0–6 (in inches)
yes | no
yes | no
9–2400
9–2400
true | false
Lets you include, omit, and configure registration
marks.
Lets you specify the offset of registration marks.0–30 (in points)
Lets you specify a bleed type.pageitemsonly,
Lets you specify a bleed offset to use. This option
is available only when bleed is set to symmetric.
Lets you specify whether to output spreads.1 | 0 | true | false |
Lets you request a low-resolution (36 dpi) PDF.1 | 0 | true | false |
Lets you specify the resolution of color images.9–2400
Lets you specify the resolution of grayscale
images.
Lets you specify the resolution of monochrome
images.
Lets you specify whether medium-quality manual
JPEG compression should be applied to color
images.
grayscalecompression
monochromecompression
pdffile
psfile
thumbnail
mode
fontdownload
layers
transparencyres
true | false
true | false
String
String
separations
yes | no
String
Integer value from
36 to 3600
Lets you specify whether medium-quality manual
JPEG compression should be applied to grayscale
images.
Lets you specify whether ZIP compression should
be applied to monochrome images.
Lets you specify the PDF name. This option is
available only when PDF to Folder is selected in
QuarkXPress Server PDF preferences.
Lets you specify the PostScript file name. This
option is available only when PostScript for laterDistilling is selected in QuarkXPress Server PDF
preferences.
Lets you embed a thumbnail in the PDF file.bw | color
Lets you specify the PDF file's color mode.composite |
Lets you turn font download on or off. You
cannot specify which fonts are downloaded.
Lets you specify which layers should be included,
as a comma-separated list.
Lets you specify the resolution for flattened
content.
verification
Lets you use PDF/X–1a or PDF/X–3 verification.pdfx1a | pdfx3
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 49
USING THE WEB INTERFACE
Render
modifier
parameters
separate
produceblankplates
updateimage
updateflow
page
pages
spread
layout
spreads
A screen-resolution PDF fileResponse
yes | no
true | false
true | false
Integer
String
| false | yes | no)
HTTP Error #500This page range is invalid.Alerts
QuarkXPress Server Error #147
This alert displays if you try to render an invalid page range.
Lets you specify whether to output each page as
a separate file.
Lets you specify whether to include blank plates.yes | no
Lets you specify whether to update imported
pictures.
Lets you specify whether to update the text flow
version of a project to the current version.
Lets you specify a single page.Integer
Lets you specify a range of pages.String (page range)
Lets you specify a spread. The first spread is spread
1. In a facing-page document, spread 1 consists
of the first page.
Lets you specify a layout by name or ID. The first
layout is Layout 1.
Lets you specify that the output use spreads.Boolean (1 | 0 | true
Example, GET
URL
Example,
object model
HTTP Error #500No file produced. The
document requested contains
only blank pages.
// STEP1: Create the QuarkXPress Server Request Context
// and set the nescessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
String docName = request.getParameter("documentName") ;
requestCtx.setDocumentName(docName);
// STEP 2(SPECIFIC TO REQUESTS):
// Create the QuarkXPress renderer
// request and embed it in the request context.
ScreenPDFRenderRequest screenpdfRequest = new
ScreenPDFRenderRequest();
screenpdfRequest.setColorImageDownSample(
request.getParameter("ColorImageDownSample"));
screenpdfRequest.setCompression(request.getParameter(
"Compression"));
requestCtx.setRequest(screenpdfRequest);
This alert displays if you try to render a a project that contains only
blank pages.
// STEP3: Create the WIG service and
50 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
// call the processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data =
service.processRequest(requestCtx);
swf
The swf render type returns a SWF (Flash) rendering of a Print layout or an Interactive
layout.
SWFNamespace
USING THE WEB INTERFACE
Parameters
version
layout
page
pages
fullscreen
embedallfonts
compressswf
compressaudio
jpegquality
download
swf6 | swf7
string
true | false
true | false
true | false
true | false
1–100
true | false
Lets you specify the minimum compatible
version of Flash Player.
Lets you specify a layout by name or ID. The first
layout is Layout 1.
Lets you specify a single page.string
Lets you specify a range of pagesstring
Lets you specify whether the SWF file should run
in full-screen mode by default.
Lets you indicate whether to include any fonts
that are necessary to correctly render text in Text
Box objects within the exported SWF file
Lets you specify whether to compress the
exported file.
Lets you specify whether to compress audio in
the exported file.
Lets you specify the quality of JPEG images in
the exported file, with 100 being highest quality.
When download is true, the browser always
displays a dialog box that lets the end user save
the returned file, even if the browser can display
it.
When download is false, the browser attempts
to display the returned file. If the browser cannot
display the file, it lets the end user save the
returned file.
The default value is false.
spreads
updateimage
Boolean 1 | 0 |
true | false | yes
| no
true | false
Lets you specify that the output use spreads.
Applicable only to Print layouts.
Lets you specify whether to update imported
pictures.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 51
USING THE WEB INTERFACE
Alerts
Example, GET
URL
updateflow
A single SWF file or a multipart reply containing an SWF file and a set of support files.Response
A multipart reply can result if you render an Interactive layout that uses external assets -- for
example, if the layout includes a Video object containing a video file that has been specified by
choosing Choose from a drop-down menu. In this case, the reply includes a "RelativePath" parameter
for each file, and each file is saved in the directory indicated by this "RelativePath" parameter
You can use the saveas request handler to save the files that are included in a multipart reply in
a particular directory, using the relative folder hierarchy that was specified in the multipart reply.
exist.
exist.
Unknown swf player version.
Value of jpegquality is outside
range, valid values are 1 - 100.
See Understanding loggingLogs
This URL renders the Interactive layout named "Presentation" in the "sample.qxp" file as a
free-standing SWF file set to display in full-screen mode:
This alert displays if you try to render a nonexistent page.The requested page does not
This alert displays if you try to render an invalid page range.This page range is invalid.
This alert displays if you try to render a nonexistent leyout.The requested layout does not
This alert displays if you specify an invalid version parameter.
This alert displays if you specify an invalid jpegquality
parameter.
Lets you specify whether to update the text flow
version of a project to the current version.
Example, object
model
Request object name: SWFRenderRequest
// STEP1: Create the QuarkXPress Server Request Context
// and set the nescessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
// STEP 2(SPECIFIC TO REQUESTS):Create the SWF renderer request
// and embed it in the request context.
SWFRenderRequest swfreq = new SWFRenderRequest();
swfreq.setVersion(request.getParameter("Version"));
swfreq.setLayout(request.getParameter("Layout"));
swfreq.setPage(request.getParameter("Page"));
swfreq.setFullscreen(request.getParameter("Fullscreen"));
swfreq.setEmbedallfonts(request.getParameter(
"Embedallfonts"));
swfreq.setCompressswf(request.getParameter("Compressswf"));
swfreq.setCompressaudio(request.getParameter(
"Compressaudio"));
swfreq.setJpegquality(request.getParameter("Jpegquality"));
swfreq.setDownload(request.getParameter("Download"));
requestCtx.setRequest(swfreq);
// STEP3: Create the WIG service and call the processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data = service.processRequest(requestCtx);
52 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Understanding render modifiers
Render modifiers let you control which parts of a project are rendered and set the scale of
the returned renderings. The topics covered here include the following:
DescriptionProperty
USING THE WEB INTERFACE
Box
Boxes
Layer
Layout
Movepages
Page
Pages
Scale
Spread
Spreads
The box render modifier lets you render a single box.
The boxes render modifier lets you render multiple boxes.
The layer render modifier lets you show and hide layers prior to rendering. This render modifier also
lets you add and remove layers from a project on the server.
The layout render modifier lets you render a particular layout.
The movepages render modifier lets you move pages prior to rendering.
The page render modifier lets you render a single page.
The pages render modifier lets you render multiple pages.
The scale render modifier lets you specify the scale at which content is rendered.
The spread render modifier lets you render a single spread.
The spreads render modifier lets you render multiple spreads.
Additional render-type-specific parameters are listed on each render type's page.
In the QuarkXPress Server Manager API, render modifiers are properties of render request
classes.
Box
Parameters
Compatible with
Alerts
Render modifier names are not case-sensitive.
The box render modifier lets you render a single box.
box
overlap
jpeg, png, raw
the specified
identifier.
The box must be
within the page
boundaries.
String
HTTP Error #500There is no box with
This alert displays if you request a box that does not exist.
HTTP Error #500Cannot render box.
This alert displays if you request a box that is outside the page boundary.
Lets you specify which box to render.String
Lets you specify whether to show the area overlapped by
the specified box.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 53
USING THE WEB INTERFACE
image type has no
way of rendering the
desired objects.
See Understanding loggingLogs
HTTP Error #406The renderer for this
This alert displays if you try to use the box parameter with the eps, pdf,
or qxpdoc render types.
Example GET
URL
Notes
Boxes
Parameters
Compatible with
Alerts
http://localhost:8080/png/sample.qxp?box=pictbox
To render a box in a particular layout, use a URL like the following:
HTTP Error #500This layer does not
This alert displays if you specify an invalid layer name with the layer,
layerattribute, or deletelayer parameter.
HTTP Error #500Specify a layer name.
This alert displays if you do not specify a layer name with the layer,
layerattribute, addlayer, or deletelayer parameter.
HTTP Error #500A layer with the
This alert displays if you try to add a layer that already exists or change the
name of a layer to a name is already used in the project.
HTTP Error #500Cannot change the
This alert displays if you try to change the name of the default layer.
Lets you lock or unlock a layer. You can use this
parameter in conjunction with the addlayer and
layerattribute parameters. This parameter overrides
QuarkXPress layer locking preferences.
Lets you set or change a layer's Keep Runaround
setting. You can use this parameter in conjunction
with the addlayer and layerattribute parameters.
This parameter overrides QuarkXPress Keep Runaround
preferences.
Example GET
URL
HTTP Error #500Cannot delete the
default layer.
value.
locked and cannot be
modified.
See Understanding loggingLogs
To render a single layer, use a URL like the following:
This alert displays if you try to delete the default layer.
HTTP Error #500Invalid parameter
This alert displays if you do not specify additional attributes or specify
attributes with invalid values in an addlayer or layerattribute request.
HTTP Error #500This layer has been
This alert displays if you try to add or modify an item on a locked layer.
56 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
Example, object
model
Layout
To add a new layer to a project, use code like the following:
Layer layer = new Layer();
layer.name = "New Layer";
layer.operation = "CREATE";
RGBColor rgbcolor = new RGBColor();
layer.RGBColor = rgbcolor;
layout.layer = new Layer[]{layer};
To edit the properties of an existing layer, use the following object hierarchy:
ModifierRequest < Project < Layout < Layer
To delete a layer, set its operation attribute to "DELETE".
You cannot add, modify, or delete multiple layers in a single request.Notes
You cannot print layers whose visible and suppressoutput properties are set to false.
You can render a hidden or suppressed layer by referencing it with the layer parameter.
Suppressed layers are rendered for the jpeg, png, and qxpdoc render types, but not for the pdf,
postscript, and eps render types.
You can use the deconstruct and getdocinfo request handlers to view information about the
layers in a project.
When you add a layer using addlayer, any unspecified attributes use the settings in the
QuarkXPress Server layer preferences (Administration > Preferences > Renderer > Layers).
If the visible property is set to false, the suppressoutput property is automatically set to
true.
The layout render modifier lets you render a specific layout.
This alert displays if you supply an invalid layout value.
Lets you specify which layout to render. The first layout is layout
1.
The movepages render modifier lets you move pages prior to rendering.
movepages
afterpage
String
String
Lets you specify which pages to move. You can use a single
page number (for example, 2) or a range of pages with the
starting and ending page numbers separated by a hyphen
(for example, 2–5).
Lets you specify the page after which the page or pages
should be moved. To move pages to the beginning of a
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 57
USING THE WEB INTERFACE
layout, use afterpage=start. To move pages to the end
of a layout, use afterpage=end.
To move pages before rendering a layout, use code like the following:
// STEP1: Create the QuarkXPress Server Request Context
// and set the nescessary properties
com.quark.qxpsm.QRequestContext requestCtx =
new com.quark.qxpsm.QRequestContext();
Boolean responseAsURL = false;
requestCtx.setDocumentName(docName);
// STEP 2(SPECIFIC TO REQUESTS):Create the PDF
// renderer request and embed it in the request context. the request context.
PDFRenderRequest pdfreq = new PDFRenderRequest();
pdfreq.setMovePages("2-4");
pdfreq.setAfterPage("7");
requestCtx.setRequest(pdfreq);
// STEP3: Create the WIG service and call the
// processRequest() API
RequestService service = new RequestServiceStub();
com.quark.qxpsm.QContentData data = service.processRequest(
requestCtx);
Notes
The movepages operation executes only after all other modifications are complete. For example,
if you use movepages in a modify request, the pages are moved only after the modify request is
complete.
Page
The page render modifier lets you render a single page.
This alert displays if you specify an invalid spread.
Lets you specify which spread to render. Spread numbers
start with 1. The first spread is spread 1. In a facing-page
document, spread 1 consists of the first page.
Example, GET
URL
Example, Object
Model
Spreads
Parameters
Compatible with
See Understanding loggingLogs
http://localhost:8080/png/sample.qxp?spread=2
To add a spread to a project, use code like the following:
Spread spread = new Spread();
spread.UID = "5";
spread.operation = "CREATE";
layout.spread = new Spread[]{spread};
Spread is located at the following place in the object hierarchy:
ModifierRequest < Project < Layout < Spread
To delete a spread, set its operation attribute to "DELETE".
The spreads render modifier lets you render layouts in spreads mode, so that pages in
spreads are rendered side-by-side rather than as individual pages.
// STEP 2 (SPECIFIC TO REQUESTS):Create the Box Param
// renderer request and embed it in
RequestParameters request = new RequestParameters();
NameValueParam nameValue1 = new NameValueParam();
nameValue1.paramName = this.boxname1.Text;
if(!this.boxvalue1.Text.Equals(""))
nameValue1.textValue = this.boxvalue1.Text;
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 61
USING THE WEB INTERFACE
request.params = new NameValueParam[]{nameValue1};
rc.request = request;
// Create the service and
// call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Box names are case-sensitive.Notes
Use "&" to change the contents of multiple boxes in one request. The general URL for the
multiple-box request is:http://localhost:8080/sample.qxp?text1=
NewText1&text2=NewText2 where text1 and text2 are the names of the two different boxes.
You can use "&" to change the contents of multiple boxes in one request. For example:
If an error occurs, the error message is written to the QuarkXPress Server Error Log. The transaction
entry in the error log contains the date and time of the request, the error code, and the error
message. The following is a sample of an error transaction log entry:
To apply Comic Sans MS to text in the box named "HeadBox," use a URL like the following:
http://localhost:8080/png/sample.qxp?HeadBox=Headline&fontname=Comic Sans MS
Request object name: RequestParameters
com.quark.qxpsm.QRequestContext rc =
new com.quark.qxpsm.QRequestContext();
if(!this.DocumentSettings1.documentName.Text.Equals(""))
rc.documentName =
this.DocumentSettings1.documentName.Text;
The name of the font to be applied.String
// STEP 2(SPECIFIC TO REQUESTS):Create the fontname
// renderer request and embed it in
RequestParameters request = new RequestParameters();
NameValueParam nameValue1 = new NameValueParam();
nameValue1.paramName = this.boxname.Text;
if(!this.boxvalue1.Text.Equals(""))
nameValue1.textValue = this.fontname.Text;
request.params = new NameValueParam[]{nameValue1};
rc.request = request;
62 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
// Create the service and
// call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Inserting a picture
This topic explains how to import a picture into an empty box or replace an existing
picture with a new one.
USING THE WEB INTERFACE
Parameters
Logs
[box name[
A preview of the project with the imported picture.Response
HTTP Error #404File not found.Alerts
QuarkXPress Server Error #–43
This alert displays if the imported file is not available to QuarkXPress Server.
HTTP Error #500The specified file
failed to load in
the picture box.
If the request succeeds, a transaction success message is written to the QuarkXPress Server transaction
log file. For example:
com.quark.qxpsm.QRequestContext rc = new com.quark.qxpsm.QRequestContext();
if(!this.DocumentSettings1.documentName.Text.Equals(""))
rc.documentName = this.DocumentSettings1.documentName.Text;
//STEP 2(SPECIFIC TO REQUESTS):Create the Box Param
//renderer request and embed it in
RequestParameters request = new RequestParameters();
NameValueParam nameValue1 = new NameValueParam();
nameValue1.paramName = this.boxname1.Text;
if(!this.boxvalue1.Text.Equals(""))
nameValue1.textValue = this.boxvalue1.Text;
request.params = new NameValueParam[]{nameValue1};
rc.request = request;
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 63
USING THE WEB INTERFACE
//Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Box names are case-sensitive.Notes
You can use "&" to change the contents of multiple boxes in one request. For example:
The saveas content modifier lets you save modified QuarkXPress projects in any supported
format to the document pool or to any network location accessible to QuarkXPress Server.
If you send a saveas request to QuarkXPress Server Manager using HTTP or the Web
services interface while the common doc pool switch is set to off in the QuarkXPress Server
Manager client, the file is saved to all registered QuarkXPress Server instances. If the
common doc pool is enabled, the file can be saved to any one registered QuarkXPress
server instance.
Parameters
newname
path
savetopool
replace
The message "Document successfully saved."Response
pathname.
Lets you specify a name for the saved-as project.String
String
true | false
true | false
HTTP Error #404File not found.Alerts
QuarkXPress Server Error #–43
This alert displays if you supply an incorrect file name or the file is not available
to QuarkXPress Server.
HTTP Error #404Bad filename/
QuarkXPress Server Error #–43
This alert displays if you supply an incorrect file name or the file is not available
to QuarkXPress Server.
Lets you specify a location for the saved-as project (other than
the document pool).
Lets you specify whether the project should be saved to the
document pool.
The default value for this paramter is true. However, if you specify
a path value, the default value changes to false, which means if
you want the project saved to the document pool, you must
explicitly set savetopool to true.
Lets you specify whether the saved project should replace a project
with the same name. The default value is true.
HTTP Error #500The file path is
invalid.
folder is
Read-Only.
This alert displays if you supply an invalid path parameter.
What to do: Specify the correct file path with the path parameter.
HTTP Error #500The specified
This alert displays if you try to save a project to a folder with read-only access.
64 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
Logs
Example, GET
URL
Example, object
model
If the request succeeds, a transaction success message is written to the QuarkXPress Server transaction
log file. For example:
If an alert displays, an error message is written to the QuarkXPress Server error log file. For example:
11/16/2005 15:42:12 — Error — Error Code: 10371 — The file path is invalid.
To save a PDF file named "Customer1.pdf" in the folder HDD:temp and also in the document pool,
use a URL like the following. Note that this URL will cause the saved-as file to replace any existing
file with the same name.
// STEP 2 (SPECIFIC TO REQUESTS):
// Create the Save as request and chain it to the document context
SaveAsRequest saveasreq = new SaveAsRequest();
saveasreq.newName = this.newname.Text;
if((this.path.Text != null) &&
(!this.path.Text.Equals("")))
saveasreq.newFilePath = this.path.Text;
saveasreq.replaceFile = this.replace.Checked.ToString();
saveasreq.saveToPool =
this.savetopool.Checked.ToString();
rc.request = saveasreq;
Parameters
// Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Importing XML with placeholders
This topic explains how to import XML data into boxes using QuarkXPress placeholders.
To use this feature, you must have a QuarkXPress project that has been set up with
placeholders that correspond to the element types in a source XML file. For more
information, see A Guide to XML Import.
thexmldoc
layout
paginate
XML
String
XML
Lets you specify the XML file containing the data to import. The path
can be absolute or relative to the location of the XML file. You can
also supply XML as a string.
Lets you specify which layout to render. The first layout is layout 1.
You can also specify a layout by name.
Lets you specify the XML file containing the data to import. The
paginate parameter reates enough pages in the target layout to
accommodate the records in the XML.
This parameter works only with the pdf, postscript, and qxp render
types. If you use it with any other render type, the server returns only
the first page of the paginated layout.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 65
USING THE WEB INTERFACE
The layout with the imported XML.Response
If you do not supply an XML string or file (for example:
http://localhost:8080/pdf/Sample.qxp?paginate),
QuarkXPress Server attempts to use the XML file that was associated
with the layout in QuarkXPress.
Alerts
Logs
Example, GET
URL
HTTP Error #500Invalid XML
String
If the project is successfully rendered, a transaction success message is written to the
QuarkXPress Server transaction log file. The transaction entry consists of the date and time of the
request, the render type, the project name, the type of response produced by the server, the size
of the response returned in bytes, and the client IP address. The following is a sample of a transaction
entry:
This alert displays if you supply an invalid XML string in the thexmldoc parameter.
When QuarkXPress Server is running on Windows, use a URL like the following:
http://localhost:8080/Sample.qxp?thexmldoc=<?xml
version="1.0"?>
<BookReview><Book><Title>C:\Autumn.jpg</Title>
<Author> Brian Kernighan and Dennis Ritchie</Author>
</Book></BookReview>
When QuarkXPress Server is running on Mac OS, use a URL like the following:
http://localhost:8080/Sample.qxp?thexmldoc=<?xml version=
"1.0"?>
<BookReview><Book><Title>/Volumes/MacHD/Pictures/abc.tiff</
Title>
<Author> Brian Kernighan and Dennis Ritchie</Author>
</Book></BookReview>
Alternatively, you can specify a path to a file containing the XML:
com.quark.qxpsm.QRequestContext rc = new com.quark.qxpsm.QRequestContext();
if(!this.DocumentSettings1.
documentName.Text.Equals(""))
rc.documentName =
this.DocumentSettings1.documentName.Text;
// STEP 2 (SPECIFIC TO REQUESTS): Create the XML Import request
XMLImportRequest xmlimportreq = new XMLImportRequest();
xmlimportreq.XMLDocument = this.thexmldoc.Text;
rc.request = xmlimportreq;
// STEP 3(SPECIFIC TO REQUESTS): Create the JPEG renderer request
JPEGRenderRequest jpreq = new JPEGRenderRequest();
xmlimportreq.request = jpreq;
// Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
66 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Using XML modify
The modify parameter lets you modify a QuarkXPress project using XML.
This topic covers the modify parameter when it is used without the construct namespace.
You can also use the modify parameter to specify an XML file to use when constructing
a project; for more information, see "Constructing a project".
The xml namespace takes two arguments: the name of the project to be modified, and a
modify parameter with the string or the path of the XML file that describes how to create
the project:
http://QXPServer8:8080/project1.qxp?modify=
file:path to XML file on server http://QXPServer8:8080/
project1.qxp?modify=XML string
You can also modify QuarkCopyDesk articles. To modify a QuarkCopyDesk article:
If an alert is displayed, an error message is written to the QuarkXPress Server error log. The following
is a sample of the error log entry:
8/10/2005 10:39:07 — Error — Error Code: 10339 — The specified file failed to load in the picture
box.
String
Lets you specify an XML file or string that describes how to create a
project. The path can be absolute or a relative path in the document
pool. Use the file: indicator to specify the path.
Note that you can also include an XML file as part of a multipart HTTP
request.
Modifying box properties and content
To modify box properties and content, use the following parameters in the Modifier DTD:
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 67
USING THE WEB INTERFACE
• "BOX (Modifier DTD)"
• "ID (Modifier DTD)"
• "TEXT (Modifier DTD)"
• "PICTURE (Modifier DTD)"
• "GEOMETRY (Modifier DTD)"
• "CONTENT (Modifier DTD)"
• "SHADOW (Modifier DTD)"
• "FRAME (Modifier DTD)"
• "PLACEHOLDER (Modifier DTD)"
• "METADATA (Modifier DTD)"
The following XML shows how some of these parameters work.
//STEP 2(SPECIFIC TO REQUESTS):
//Create the BOX modifier renderer request and
//embed it in request context
ModifierRequest request = new ModifierRequest();
Project contents = new Project();
Geometry geo = new Geometry();
geo.moveUp = this.moveup.Text;
geo.color = this.color.Text;
geo.growDown = this.growdown.Text;
geo.shrinkAcross = this.shrinkacross.Text;
Box box = new Box();
box.UID = this.Boxid.Text;
box.geometry = geo;
Layout layout1 = new Layout();
layout1.name = this.layout.Text;
layout1.boxes = new Box[]{box};
if(this.runaround.Checked == true)
{
Runaround runaround = new Runaround();
runaround.type = this.runaroundtype.Text;
runaround.top = this.top.Text;
runaround.left = this.left.Text;
runaround.right = this.right.Text;
geo.runaround = runaround;
}
contents.layouts = new Layout[]{layout1};
request.project = contents;
rc.request = request;
Example 2, object
model
//Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
To edit the geometrical properties of an existing box in a QuarkXPress project, use the following
object hierarchy:
The order of the <BOXREF> elements in a <GROUP> indicates the order in which the boxes
were selected prior to grouping. The z-order of boxes in the layout is determined by the
order of the <BOX> elements in the XML, from rearmost to frontmost.
XML representations of groups created by versions of QuarkXPress Server prior to 8.1 are
ignored during construct and modify calls, as they were in earlier versions of QuarkXPress
Server.
Creating tables
To create a new table, use the following parameters in the Modifier DTD:
• "SPREAD (Modifier DTD)"
• "TABLE (Modifier DTD)"
• "COLSPEC (Modifier DTD)"
• "COLUMN (Modifier DTD)"
• "ROW (Modifier DTD)"
Logs
• "CELL (Modifier DTD)"
The following XML shows how some of these parameters work.
To add a new table to an existing spread, use code like the following:
Spread spread = new Spread();
Table table = new Table();
table.name = "textbox1";
Geometry geometry = new Geometry();
Position position = new Position();
To delete a table, provide the table's name or ID and set the operation attribute to "DELETE".
Using inline tables
The Inline Tables feature makes it easy to create an anchored table. Rather than having to
specify every attribute of a table, you can simply specify the content for a table as a series
of <TROW> and <ENTRY> elements in an <INLINETABLE> element, like so:
The number of rows in such a table is determined by the number of <TROW> elements.
The number of columns is determined by the maximum number of <ENTRY> elements in
a <TROW>.
In the <TBODY> element, each <TROW> contains one or more <ENTRY> elements. If you
don't style the text in an <ENTRY> element, it uses the default styling, which can be defined
in a <TROWSTYLE> or <TCOLSTYLE> element (see below).
The <THEAD> element lets you create a repeating header for the table. The <TCONTINUED>
element lets you create a "continued" row for the table. If you don't supply either of these
elements, you must create the header row manually as a <TROW> in the <TBODY>.
For each row and column, you can specify the following things:
•
COLOR: Cell background color.
•
SHADE: Cell background shade.
•
STORYDIRECTION: Story direction.
An <INLINETABLE> can also include optional <COLGROUP> elements, which allow you to
specify column attrbutes in the form of <TCOL> elements, like so:
The INDEX value indicates the column number. You can specify the WIDTH of a column
in points by omitting a unit indicator, or as a percentage of the table width by including
a % after the number.
If you deconstruct a table that was created with an <INLINETABLE> element, the resulting
XML describes the table as a <TABLE> element, not an <INLINETABLE> element.
Using table styles
Table styles make it easy to style inline tables. Rather than applying formatting directly,
you can define a table style, then apply the table style to inline tables like so:
<INLINETABLE TABLESTYLEREF="TableStyle1">
For example, assume you want to create a table where alternating rows are shaded, the
grid is a particular color, the insets are a particular amount, and so forth. Instead of
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 77
USING THE WEB INTERFACE
specifying the formatting for such a table manually for every row, you can define the
// STEP 2 (SPECIFIC TO REQUESTS):Create the Text Modifier
// renderer request and embed it in request context
ModifierRequest textReq = new ModifierRequest();
Project contents = new Project();
RichText richText1 = new RichText();
richText1.value = this.text1.Text;
richText1.color = this.color1.Text;
Text boxText1 = new Text();
Story story = new Story();
story.richText = new RichText[]{richText1};
boxText1.story = story;
if(this.fittextbox1.Checked)
boxText1.fitTextToBox = "true";
if(this.clearoldtext1.Checked)
boxText1.clearOldText = "true";
Box box1 = new Box();
box1.UID = txtBox1;
box1.text = boxText1;
Layout layout1 = new Layout();
layout1.name = layoutText;
layout1.boxes = new Box[]{box1};
contents.layouts = new Layout[]{layout1};
textReq.contents = contents;
rc.request = textReq;
// Create the service and call it with QRequestContext object
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 81
USING THE WEB INTERFACE
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Example 2,
object model
Notes
Modifying picture properties
To edit the properties of an existing text box in a QuarkXPress project, use the following object
hierarchy:
ModifierRequest < Project < Layout < Spread <
Box < Text < Story < Paragraph < RichText
For a list of the RichText object's properties, see the JavaDoc installed with QuarkXPress Manager.
The Story object also contains some text-related properties: fitTextToBox, includeStylesheets,
convertQuotes, and clearOldText.
The <FITTEXTTOBOX> attribute depends on two preferences: Allow Text to Grow and Font Size.
To set these preferences in QuarkXPress Server, choose QuarkXPress > Server > Preferences and
then click Modifier in the list on the left.
You can modify the properties (such as origin, scale, angle, skew, and orientation) of
pictures in a QuarkXPress project with XML. To modify picture properties, use the following
parameters in the Modifier DTD:
• "BOX (Modifier DTD)"
• "ID (Modifier DTD)"
• "PICTURE (Modifier DTD)"
The following XML shows how some of these parameters work.
// STEP 2(SPECIFIC TO REQUESTS):Create the Image
// Modifier renderer request and embed it in
ModifierRequest imgReq = new ModifierRequest();
Project contents = new Project();
Picture picture1 = new Picture();
picture1.scaleAcross = this.scaleacross1.Text;
picture1.scaleDown = this.scaledown1.Text;
if(this.fitpicturebox1.Checked == true)
picture1.fitPictureToBox = "true";
if(this.flipvertical1.Checked == true)
picture1.flipVertical = "true";
if(this.fliphorizontal1.Checked == true)
picture1.flipHorizontal = "true";
Box box1 = new Box();
box1.UID = txtBox1;
box1.picture = picture1;
Layout layout1 = new Layout();
layout1.name = layoutText;
imgReq.contents = contents;
84 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
contents.layouts = new Layout[]{layout1};
layout1.boxes = new Box[]{box1};
rc.request = imgReq;
// Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Example 2,
object model
Importing data
To edit the properties of an existing text box in a QuarkXPress project, use the following object
hierarchy:
For a list of the Picture object's properties, see the JavaDoc installed with
QuarkXPress Manager.
You cannot replace an image with the Modifier XTensions software.Notes
If you specify <FITPICTURETOBOX>, <FITBOXTOPICTURE>, and <FITPICTURETOBOXPRO> for a
picture, only the first of these elements will be applied.
Imports text or image data into a project. You can use import any text or picture file format
supported by QuarkXPress, including XPress Tags files.
You can import .doc, .docx, .dot, .dotx, and .docm files.
To import text or image data into a project, use the following parameters in the Modifier
DTD:
• "BOX (Modifier DTD) "
• "ID (Modifier DTD)"
• "PICTURE (Modifier DTD)" (this is not a required element when importing data)
• "TEXT (Modifier DTD)"
• "STORY (Modifier DTD)"
• "CONTENT (Modifier DTD)"
The following XML shows how some of these parameters work.
// STEP 2 (SPECIFIC TO REQUESTS):Create the data import
// request and embed it in request context
ModifierRequest request = new ModifierRequest();
Project requestContents = new Project();
Content boxContent1 = new Content();
Box box1 = new Box();
box1.UID = txtBox1;
box1.content = boxContent1;
Layout layout1 = new Layout();
layout1.name = layoutText;
if(!this.content1.Text.Equals(""))
{
boxContent1.value = this.content1.Text;
Text text1 = new Text();
text1.font = this.fontname1.Text;
box1.text = text1;
if(this.includestylesheets1.Checked == false)
boxContent1.includeStylesheets = "false";
if(this.convertquotes1.Checked == false)
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 87
USING THE WEB INTERFACE
boxContent1.convertQuotes = "false";
}
else if (null != uplTheFile.PostedFile)
{
Stream theStream = uplTheFile.PostedFile.InputStream;
StreamReader reader = new StreamReader(theStream);
boxContent1.value = reader.ReadToEnd();
}
layout1.boxes = new Box[]{box1};
requestContents.layouts = new Layout[]{layout1};
request.contents = requestContents;
rc.request = request;
// Create the service and call it with QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Notes
BoxParam XTensions software lets you import only files in the document pool. Modifier XTensions
software, however, lets you import files that are located anywhere on the server computer, at any
accessible network location, or supplied as part of a multipart HTTP request.
Exporting Job Jackets files during deconstruction
While using the xml namespace to deconstruct a QuarkXPress project, you can specify the
jjname parameter in the same request to output the Job Jackets file to the document pool.
You can then use the construct namespace to create new QuarkXPress projects that are
based on that Job Jackets file's resources and layout specifications.
The jjname parameter exports QuarkXPress project resources and layout specifications to
a Job Ticket. Resources defined at the Job Jackets level are not exported to the Job Ticket.
Using interactivity
The <INTERACTIVITY> element describes an asset used as an interactive element for a
format such as App Studio, ePUB, or Blio.
The specific schema for an interactive element is determined by the XTensions module
that owns that element, so such schemas are not defined here. The best way to create or
modify an <INTERACTIVITY> element is to deconstruct it and then use the deconstructed
XML as a template.
Using XML deconstruct and construct
The xml namespace deconstructs a project according to the Modifier DTD. The construct
namespace lets you turn an XML representation of a QuarkXPress project back into a
QuarkXPress project.
This means you can deconstruct a project into an XML representation, change the XML
in accordance with the Modifier DTD, and then have the server generate an updated
88 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
version of the QuarkXPress project. You can even create new QuarkXPress projects from
scratch using XML.
In addition, you can use the construct namespace to:
• Create a page based on a master page
• Create a project from XML, using a Job Jackets file as the basis for the project
• Modify text font and style, including OpenType styles
• Apply style sheets and local formatting to text
• Create and populate tables
• Import pictures into picture boxes and specify picture attributes
The DTD used for XML construction and deconstruction is completely Unicode-compliant,
making it ideal for use in international publishing. Furthermore, the use of this DTD
ensures that the schema of XML output created by Constructor does not change when
server preferences change. For more information, see "Modifier DTD (annotated)."
Some minor QuarkXPress features are not available through the Modifier DTD. However,
this DTD represents the majority of all user-editable aspects of a QuarkXPress project.
The deconstruct namespace/request no longer exists. If you try to use it in this version of
QuarkXPress Server, an error is returned.
Deconstructing a project
The xml namespace returns an XML representation of the target project. To use this
namespace, use a URL like the following:
http://QXPServer8:8080/xml/project1.qxp
When you use the xml namespace, QuarkXPress Server returns an XML file that represents
the deconstructed project. This XML file adheres to the Modifier DTD (see "Modifier DTD
(annotated)").
An XML file that represents a deconstructed project does not contain all of the information
necessary to reconstruct the project. The definitions of the project's resources (such as style
sheets, colors, and master page definitions) are stored in a Job Jackets file. For example,
you can apply a style sheet to a paragraph by indicating the style sheet’s name, like so:
<PARAGRAPH PARASTYLE="BodyText">
<RICHTEXT>The sun has risen.</RICHTEXT>
</PARAGRAPH>
The above information is included in the deconstructed project’s XML file. The definition
of the “BodyText” style sheet, however, is stored in the Job Jackets file.
The URL of a deconstructed Job Jackets file is indicated by the PROJECT@JOBJACKET
attribute. If you need access to new colors, style sheets, master pages, or other resources,
add them to the Job Jackets file indicated by this URL.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 89
USING THE WEB INTERFACE
Projects can also refer to resources defined with the QuarkXPress Server Document Controls
submenu (Server/QuarkXPress Server menu). QuarkXPress Server looks for resources first
in the Job Jackets file and then in the server-defined resources.
XML
Creates an XML file from a QuarkXPress project. The XML is returned in a fixed format
that adheres to the Modifier DTD. You can use the returned XML to create or modify a
QuarkXPress document using the construct namespace or modify parameter.
Namespace
Parameters
xml
Modifier DTDDTD
box
boxes
XSL
layout
relativegeometry
relativetopage
copyfitinfo
Returns XML only for the box with the given ID or name.
Returns XML only for the boxes with the IDs or names supplied as a
comma -separated list.
Specifies the path of an XSL file for transforming the returned XML. Use
the file: indicator to specify the path.
Specifies the name or number of the layout containing the box to render.
The first layout is layout 1. Note that this parameter works only with the
box parameter.
Tells the xml namespace to describe <GEOMETRY> elements using
<RELPOSITION> rather than <POSITION>. This allows an item's position
to be defined either in relation to the page or in relation to the entire
spread.
Use only with the relativegeometry parameter. Tells the xml
namespace to describe <GEOMETRY> elements using <RELPOSITION>
elements in which ORIGIN@RELATIVETO="page" (as opposed to
"spread").
QuarkXPress Server returns copyfitting information for QuarkCopyDesk
articles by default. To retrieve copyfitting information when
deconstructing a QuarkXPress project, include copyfitinfo=true in
the xml request. For example:
You can also deconstruct QuarkCopyDesk articles. To deconstruct a QuarkCopyDesk article, use
the following:
http://localhost:8080/xml/copydesk/abc.qcd
Request object name: XMLRequest
XMLRequest xmlRequest = new XMLRequest();
QRequestContext context = new QRequestContext();
context.setDocumentName("SAMPLE_DOCUMENT.qxp");
context.setResponseAsURL(false);
context.setRequest(xmlRequest);
QContentData response = new RequestServiceStub().processRequest(context);
System.out.println(response.getTextData());
The construct namespace takes two arguments: The name of the project to be created,
and a modify parameter that points to the XML file or string that describes how to create
the project. For example:
http://QXPServer8:8080/construct/project1.qxp?
modify=file:path to XML file on server
There is a length limitation of 4096 characters on URLs, so you will probably want to use
an XML file rather than an XML string.
If you are using QuarkXPress Server Manager, you can send a similar command with a
QuarkXPress Server Manager URL or through Web services.
Every project created with the construct namespace must be based on a Job Ticket in a
Job Jackets file. Using construct to create a project is roughly equivalent to using the
File > New > Project from Ticket command in QuarkXPress.
When you create a project using the construct namespace, you must supply the path to
the Job Jackets file that will supply the project's resources. To do so, indicate the URL of
the Job Jackets file in the PROJECT@JOBJACKET attribute and the name of the Job Ticket
in the PROJECT@JOBTICKET attribute. (<PROJECT> is the root element of the Modifier
DTD. For more information, see "Modifier DTD (annotated).")
For example, to create a project from a Job Ticket named "Tall US Brochure Ticket" in a
Job Jackets file named "BrochureJJ.xml," use XML like the following:
This alert displays if you specify an invalid XML file or request a document
that is not available to QuarkXPress Server. For example, this error can
occur if an image or text file file mentioned in a <CONTENT> element is
invalid or missing.
HTTP Error #404Bad filename/pathname.
QuarkXPress Server Error #–37
This alert displays if you specify an invalid file name or path.
HTTP Error #500The XML document is
not valid or well formed.
contains an invalid tag
value.
If the request succeeds, a transaction success message is written to the QuarkXPress Server transaction
log file. For example:
To construct a new QuarkXPress project by editing an existing document, first deconstruct a
QuarkXPress project using code like the following:
XMLRequest dcnstrq = new XMLRequest();
rc.request = dcnstrq;
Next, alter the project by manipulating the XML. When you're done, pass the modified XML
document to ConstructStreamRequest to create a new QuarkXPress project. For example:
ConstructStreamRequest cnstrq =
new ConstructStreamRequest();
cnstrq.modify = Buffer; // Byte[] for the modified XML
rc.request = cnstrq;
QuarkXPressRenderRequest qxprq =
new QuarkXPressRenderRequest();
cnstrq.request = qxprq;
Alternatively, you can deconstruct a QuarkXPress project using code like the following:
RequestServiceService svc =
new RequestServiceService()
Project proj = svc.getDOM("document.qxp");
Next, alter the project by manipulating the XML. When you're done, pass the modified Project
instance to ConstructRequest to create a new QuarkXPress project. For example:
ConstructRequest cnstrq =
new ConstructRequest();
cnstrq.project = proj;
QRequestContext rc = new QRequestContext();
rc.request = cnstrq;
QuarkXPressRenderRequest qxprq =
new QuarkXPressRenderRequest();
cnstrq.request = qxprq;
Notes
The construct namespace takes two arguments: The name of the project to be created and a
modify parameter with the string or the path of the XML file that describes how to create the
project:
http://localhost:8080/qxpdoc/construct/project1.qxp?
modify=file:path to XML file on server
It's important to understand that although the construct namespace uses the same DTD
that you use when you modify an existing project, the construct namespace uses it
differently. When you use the construct namespace, the XML you pass simply contains
a description of everything in the document you want to create — much as an HTML file
describes a page you want to display in a browser. There is no need to use a command
and create elements such as ADDCELLS, OPERATION, and MOVERIGHT; you simply describe
each item in the layout with elements such as <BOX> and <TABLE>, and specify each item's
position with the <POSITION> element type. When you use the modify attribute without
the construct namespace, however, the XML you pass must contain commands that
show how you want QuarkXPress Server to modify the project.
For more information, see "Modifier DTD (annotated)."
Working with pages and spreads
The root element of a deconstructed QuarkXPress project is <PROJECT>. Within each
<PROJECT> element are one or more <LAYOUT> elements. Each layout contains one or
more <SPREAD> elements, and each <SPREAD> contains one or more <PAGE> elements.
Each layout, spread, and page has a unique name, indicated by its <ID> element.
USING THE WEB INTERFACE
Each layout can have a unique name, indicated by its <ID> element's NAME attribute. You
can use a layout's name when referring to that layout in a non-construct call that uses the
MODIFY attribute. The ID@NAME attribute is ignored for <SPREAD> and <PAGE> elements,
but you can refer to them numerically with their <ID> element's UID attribute, with "1"
being the first, "2" being the second, and so forth.
With most element types, it is best to assign an ID@NAME value to an element and use that
to refer to the element, because ID@UID values are defined by QuarkXPress Server and thus
ignored for construct calls. <PAGE> and <SPREAD> are exceptions to this rule.
Each page has a POSITION attribute that indicates which side of the spine it is on. (In
single-sided layouts, every page is given a POSITION of RIGHTOFSPINE).
You can assign items to a page using the GEOMETRY element, which is a child of the BOX
and TABLE elements. For example:
Master pages are stored in a deconstructed project’s Job Jackets file. To create a page from
this master page, insert a MASTER attribute into the PAGE element and indicate the number
of the target master page. Master page numbering is as follows:
1 = blank single page
2 = blank facing-page
3 = the first user-defined master page in the Job Jackets file (by default, the master page
named "A-Master A")
For example, to create a master page based on the first user-defined master page in the
Job Jackets file, you could use XML like the following:
To add text and pictures to a project, you must add text boxes and picture boxes to the
project’s <SPREAD> element. Both are represented by <BOX> elements, but text boxes have
a BOXTYPE attribute of CT_TEXT, and picture boxes have a BOXTYPE attribute of CT_PICT.
You can read about how <BOX> elements are put together in the Modifier DTD, but for
96 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
USING THE WEB INTERFACE
purposes of illustration, the sample XML below describes a spread that contains a text box
and a picture box.
<SPREAD>
<ID UID="1" />
<!-- TEXT BOX -->
<BOX BOXTYPE="CT_TEXT" COLOR="White">
<ID NAME="Headline Box" />
<GEOMETRY LAYER="Default" PAGE="1" SHAPE="SH_RECT">
<POSITION>
<TOP>200</TOP>
<LEFT>80</LEFT>
<BOTTOM>450</BOTTOM>
<RIGHT>475</RIGHT>
</POSITION>
</GEOMETRY>
<TEXT>
<STORY>
<PARAGRAPH PARASTYLE="Normal">
<RICHTEXT>This is text in a box.</RICHTEXT>
</PARAGRAPH>
</STORY>
</TEXT>
</BOX>
This example will work for a construct request. For a modify request, add the attribute
value OPERATION="CREATE" in the BOX element.
All BOX elements can contain a GEOMETRY element that indicates the position and size of
the box, a FRAME element that describes the box's frame (if any), and a SHADOW element
that describes the box's drop shadow. Additional BOX elements are described in the following
sections.
The z-order (stacking order) of boxes in the layout is determined by the order of the <BOX>
elements in the XML, from rearmost to frontmost.
Fitting a box to text or a picture
The <FIT> element type lets you automatically adjust the size of a box to fit the text or
picture in that box.
The default behaivior is to not fix a box to its content. To use this feature, you must supply
<MAX> and <MIN> elements. Each <MAX> or <MIN> element lets you specify a maximum
or minimum size for the box, a maximum or minimum location for the resized box, or a
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 97
USING THE WEB INTERFACE
maximum or minimum scale percentage for the box. Note that you can use different types
of <MAX> and <MIN> elements in a <FIT> element, but you can use only one <MAX> element
and one <MIN> element per <FIT> element.
The FIT@POINT attribute lets you indicate the direction in which the box should grow or
shrink. The available options are TOPLEFT, BOTTOMLEFT, TOPRIGHT, and BOTTOMRIGHT.
The FIT@AVOIDBOXESBY attribute lets you specify the distance between the POINT side
or corner of a resized box and any other items around it. A box will expand only until it
is this distance from an adjacent item.
The FIT@PROPORTIONAL attribute lets you specify whether the resized box should have
The order of the <BOXREF> elements in a <GROUP> indicates the order in which the boxes
were selected prior to grouping. The z-order of boxes in the layout is determined by the
order of the <BOX> elements in the XML, from rearmost to frontmost.
Working with pictures
The <PICTURE> element supports a variety of features, including the ability to specify
runaround, opacity, and drop shadow characteristics. For more information, see the
Every <BOX> element for text contains a <TEXT> element, and every <TEXT> element
contains a <STORY> element. A <STORY> element can contain <PARAGRAPH> elements,
each of which contains <RICHTEXT> elements. A <STORY> element can also simply contain
<RICHTEXT> elements.
A text <BOX> element can also contain a <CONTENT> element that indicates the origin of
the text in that box.
A text <BOX> element in a deconstructed project can also contain <PLACEHOLDER> elements,
which allow XML Import XTensions software to insert text from a different XML source.
<PLACEHOLDER> elements are ignored by the construct namespace and the modify
parameter; placeholders must be inserted in QuarkXPress using XML Import XTensions
software.
Applying style sheets
Like other resources, style sheets are defined in a deconstructed project’s Job Jackets file.
To apply a paragraph style sheet to text, use the PARASTYLE attribute of the <PARAGRAPH>
element. For example, to apply the paragraph style sheet named “BodyText” to a paragraph,
use XML like the following:
<PARAGRAPH PARASTYLE="BodyText">
<RICHTEXT MERGE="true">The sun has risen.</RICHTEXT>
</PARAGRAPH>
To apply a character style sheet to text, use the CHARSTYLE attribute of the <RICHTEXT>
element. For example, to apply the character style sheet named “Emphasis” to a word, use