Atomik Roundtrip 2.1: Tutorials << >>

Chapter 4 Tutorial 1 : Basic Functions of Atomik Roundtrip

In this tutorial, you will learn about the basic functionality of Atomik Roundtrip by importing content into a QuarkXPress document.

The tutorial will use sample XML documents, but the principles and procedures involved can be applied to a wide variety of documents.

Tutorial 1 will address the most simple process of using Atomik Roundtrip: getting your XML content into QuarkXPress.

The key stages to this tutorial are:

  1. Importing the XML file.
  2. Importing content from the XML file and onto the QuarkXPress page.


The objective of this tutorial is to ensure that your copy of Atomik Roundtrip is correctly installed, and to introduce you to importing XML content into QuarkXPress using Atomik Roundtrip.

4.1 Setting up Atomik Roundtrip

  1. Launch QuarkXPress with Atomik Roundtrip enabled. If you have not yet installed Atomik Roundtrip, refer to the installation instructions elsewhere in this guide for a description of the installation procedure.
  2. Note that the ‘Roundtrip XML’ and ‘Roundtrip Control’ palettes should be visible on screen.
  1. If these palettes are not already visible on your screen, select ‘Show Roundtrip Control’ and ‘Show Roundtrip XML’ from the ‘Roundtrip’ menu in QuarkXPress.
  2. If these menu options are not available in QuarkXPress, then the Atomik Roundtrip XTension is not properly installed, and you should review the installation instructions before proceeding.
  3. From the ‘File’ Menu, select ‘Open’.
  4. Locate the QuarkXPress template document ‘RT_Tutorial1.qxp’ from the Tutorials folder, and select the ‘Open’ button in the dialog.
  5. Click ‘Keep Document/Project Settings’ in the resulting dialog box.
  6. You should now see an incomplete document page on your screen.

The Tutorial 1 document is a blank template for a magazine layout - which we’re going to build into a finished layout from an XML source document throughout these tutorials. You can see how the document will look when it’s finished by taking a look at the ‘RT_Tutorial_finished.qxp’ document in the ‘Tutorials’ folder. Alternatively, take a look at the end of the Tutorial section, where this document is pictured.

Although the layout which is being used in the tutorials is a magazine, the principles which you will learn can be applied to a newspaper, book, directory, catalogue, or any other type of publication.

4.2 Setting Atomik Roundtrip preferences

The next step is to setup your Atomik Roundtrip preferences for the Tutorial files.

  1. Select ‘Application’ from the ‘Preferences’ sub-menu of the ‘Edit’ menu in QuarkXPress.

Note that you can also bring up the preferences by selecting ‘Application Preferences’ from the Roundtrip menu, or by clicking the Preferences button in the Roundtrip control palette.

The Application preferences dialog will appear. The preferences dialog has a list on the left hand side listing all the categories for the preferences. Select ‘Roundtrip Folders’ from this list.

  1. You must select the appropriate folders for DTD files, rulesets and entities. The folders which you should use for the tutorials are all located within the Tutorials folder.

    To set the folder, simply click on the ‘Choose’ button, and select the folder from the dialog which appears.

    Set Default Ruleset location to “Tutorials:Rulesets”

    Set Default DTD location to “Tutorials:DTD”

    Set Default Entity location to “Tutorials:Entities”

    Set Default Image location to “Tutorials:Images”

    Once you’ve selected the folders, click the ‘OK’ button to continue.

    4.3 Importing an XML file

    The next step is to import an XML file, the content of which we can bring onto the QuarkXPress page.

    1. Select ‘Import XML’ from the ‘Roundtrip’ menu. An ‘Open’ dialog will be displayed.
    1. In this dialog, select the ‘RT_Tutorial1.xml’ file, which is located in the ‘Tutorials’ folder.
    2. Before you click ‘Import’, make sure that you’ve selected the ‘Easy_Magazine.rls’ ruleset from the ‘Ruleset’ pop-up menu at the bottom of the dialog box.

    We’ll explain what a ruleset is in Tutorial 3, and how you can create your own rulesets. For now, just continue using the ruleset we have already created for you.

    1. You’ll notice that the ‘focus’ tab of your XML palette now has the name of the XML file which you have just imported listed in it.
    2. The focus tab of the XML palette lists all of the XML files which are associated with the QuarkXPress document. By importing an XML file, it becomes associated with the QuarkXPress document.

    Notice that next to the name of the XML file you have some further information about it; in this example:

    [XML] - shows this is an XML file

    [Easy_Magazine.dtd] - Shows that the DTD for this XML file is called ‘Easy_Magazine.dtd’.

    Note that If the DTD was specified internally as part of the XML file, then you would simply see [None] here, like so:

    [Easy_Magazine.rls] - Shows that the Easy_Magazine.rls ruleset is applied to this XML file.

    1. Now switch to the XML tab of the ‘Roundtrip XML’ palette. You’ll see a structured view of the XML which you have just imported.

    You can explore the XML by clicking on the disclosure triangle to the left of each element, which will reveal that element’s child items. Clicking on a disclosure triangle whilst holding down the option or alt key on the keyboard will open the full tree of child elements of all the children of that element.

    1. Click on the disclosure triangle next to the first ‘Review’ element. The contents of this element will be revealed.
    2. You will notice that the sample XML file is not simply a flat file, but contains a rich structure. Atomik Roundtrip is able to use XML files with complex, variable structures.
    3. On the QuarkXPress page, draw a text box. Drag the text from the “GameTitle” element in the first review into this text box.
    4. The text, “The Neverland”, will appear in the QuarkXPress text box.
    1. Draw another text box, and this time drag the “Standfirst” element to it. The text from this element will appear automatically in the text box.

    Note that the text is automatically styled when it is brought on to the page.This is because we selected a ruleset when we imported the XML in step 2. We’ll look at rulesets in more detail in Tutorial 3.

    1. Draw a further, larger, text box on the QuarkXPress page. Previously, the XML items which you’ve dragged to the page were simple elements which contained only text. The next element which you drag and drop will be a parent element with multiple children.

    Examine the ‘ReviewText’ element (you’ll need to scroll down in your palette in order to see this), by clicking on the disclosure triangle. Note that there are multiple child ‘Paragraph’ elements, and one of these Paragraph elements has, itself, multiple child elements.

    1. Drag and drop the ReviewText element to the empty text box which you’ve drawn. Notice that the text on the QuarkXPress page is, again, automatically formatted; and this time, some of the child elements are differently formatted from their parents.
    2. You’ll notice that if your copy of QuarkXPress is set up to show invisibles (View->Show Invisibles, or command (apple) + I), that the starting and finishing points of the separate XML elements are indicated by a magenta marker.
    1. Click into the text which you have just dragged & dropped to the page. Whilst you are clicking around in this text, notice the Roundtrip Control palette. This shows you where in the structure of the XML document you are clicking. There is more information about the Roundtrip Control palette in the ‘Function Reference’ section of this manual.


    In this tutorial we have:

    1. Set up the Atomik Roundtrip preferences
    2. Imported a sample XML file
    3. Imported content from the XML file to the QuarkXPress page