Atomik Roundtrip 2.1: Reference > Chapter 12 Function Reference << >>

12.6 Ruleset Palette

The Ruleset palette allows users to create rulesets to style XML content automatically as it is imported into QuarkXPress.

The ruleset palette is opened by double-clicking or double-right clicking (Windows) an element in the Structure tab of the Roundtrip XML palette. The settings you make in this palette will relate to the element which was originally double-clicked. However, if you select another element in this palette, or change the focus of the Roundtrip XML palette (by changing the selection in the ‘Focus’ tab), then the Ruleset palette will update to reflect that change. If you have unsaved changes in the ruleset palette, you will be automatically prompted to save those changes before proceeding.

Rulesets are created by clicking the ‘Create Ruleset’ button in the Roundtrip XML palette, and when a ruleset is created, it can be selected directly in the focus tab of the Roundtrip XML palette. However, this isn’t the only way in which you can edit a ruleset file. Any time an XML file is opened with a particular ruleset, you are able to edit that ruleset simply by selecting the imported XML file in the focus tab of the Roundtrip XML palette, then going to the ‘DTD’ tab of that palette, and double-clicking an element to show the Ruleset palette. Alternatively, the ruleset palette can be displayed by clicking on the ‘Show Ruleset’ button (

) in the Roundtrip Control palette or by selecting ‘Show Roundtrip Ruleset’ in the Roundtrip menu.

Note that in order to use the ruleset palette, you must have imported an XML file using the ruleset which you wish to edit. If you have not imported any XML, or you do not currently have an XML file selected in the ‘Focus’ tab of the Atomik XML palette, the ruleset palette will appear blank.

Each rule within a Roundtrip ruleset defines how a particular type of XML content will be styled and handled when it is brought onto the QuarkXPress page. A rule can be applied either to all instances of a particular element within an XML file, or only to certain instances, depending on conditions which you can define. These conditions can either be dependent on the ‘context’ of the element - the part of the XML hierarchy where the element appears, or the value of an attribute of the element. The left-hand section of the ruleset palette lists all of the rules which make up the current ruleset.

The rule name can be changed by selecting the rule in the list on the left-hand side of the palette, and editing the text in the ‘Rule Name’ box. Note that the rule name will normally default to the name of the XML element.

There are two types of control in the ruleset, those which describe how the content will appear when the rule is applied to it, and those which define the conditions under which that rule will be applied.

Styling controls

These are controls which affect the content which is imported using this rule will appear on the QuarkXPress page.

Text

Paragraph style This option lists all the paragraph styles in the frontmost QuarkXPress document. When a paragraph style is selected, the rule will apply that style to the contents of this element, and any children which that element may have.

Note that when you are placing multiple elements simultaneously, and apply a paragraph style, the same style will be applied to all text following the element to which this rule was applied, until a piece of content is reached which conforms to a rule which applies a paragraph style sheet. As a paragrah can only have one paragraph style sheet applied in QuarkXPress, if you have two multiple elements in the same paragraph using rules which all apply a paragraph style sheet, then the rule for the last element in the paragraph will be the one whose style sheet is applied to that paragraph. You should take care when designing rulesets to avoid this circumstance.

If you do not wish to specify a paragraph style for a rule, you can specify the ‘Not Set’ option at the top of the list of styles.

Character Style allows you to specify a character style to be applied by this rule. This can be done either alongside or independently of setting a paragraph style.

Is a Paragraph will make the XML to which this rule is applied into a separate paragraph by inserting a hard return after the imported text.

Note that you can specify ‘Is a Paragraph’ on elements wihch don’t themselves contain any text, but do contain child elements : a hard return will be inserted after those child elements.

Map from Attribute allows you to specify that this rule will insert the contents of an attribute value of this element, rather than any text content it might have. If this option is selected, a pop-up menu is available listing all the attributes defined in the DTD for this element.

Note, this option is only available when the element selected in the ‘Elements’ pop-up menu has an attribute list defined in the DTD.

Use Character Attributes

It is also possible, using the styling controls on the right-hand side of the ruleset palette, to apply individual character attributes as part of a rule. If these are set as part of a rule which also contains paragraph or character style sheets, then the character formatting will take precedence over that specified in the style sheets.

Character formatting set in the child’s ruleset entry will take precedence over any character formatting inherited from a parent element’s rules or style sheet.

You should note that character attributes are only applied as part of a rule if the ‘Use Character Attributes’ checkbox at the top of this section of this dialog is checked. The effect of the character attributes when applied through a Roundtrip rule is identical to when these same character formatting attributes are applied through their equivalent QuarkXPress functions (from the ‘Style’ menu in QuarkXPress). If you require further information about QuarkXPress character formatting, please consult chapter 12 of ‘A Guide to QuarkXPress’.

Generated Text

The Roundtrip ruleset’s generated text options allow you to add text before and after the element to which the rule will be applied. Text entered in the ‘Pre’ field will appear before the element when it is brought onto the page and text which appears in the ‘Post’ field will appear after the element. This generated text can be any standard character. Good examples of when this might be used are to add a currency symbol before a price (e.g. ‘2.99’), or a unit symbol after a measurement (e.g. ‘24 cm’).

Not only can visible characters be added to this dialog, special non-printing QuarkXPress characters can also be added.

Special characters, preceded by a backslash (“\”) character, will be translated into their equivalents and inserted before or after the imported XML text.

This is particularly useful if you are setting up a ruleset for importing tables into QuarkXPress, as you simply need to add “\t” to the pre text field for all of the items which you wish to put into columns : when the data is imported into QuarkXPress, with an appropriately configured style sheet, then your table can be easily configured (there is an example of this, Easy_Table.rls, in the ‘Samples’ folder on the Atomik Roundtrip CD-ROM).

The easiest way to choose these special characters is simply to click on the

icon next to the pre and post fields, and you can choose the special character which you wish to insert from a list.

  1. \t Tab a standard QuarkXPress tab marker - equivalent to pressing the ‘Tab’ key on the keyboard.
  2. \n Soft Carriage Return a QuarkXPress soft return - equivalent to pressing shift + return on the keyboard.
  3. \b New Box forces the text to flow into the next box in a linked chain, regardless of whether the current box is filled. This is equivalent to pressing ‘Shift+Enter’ on the numeric keypad on the keyboard (Note, this is only applicable to chains of linked boxes, in a box which is not part of a linked chain, a new box character will make all subsequent text into overmatter).
  4. \c New Column forces the text to flow into the next column in a columnated text box, or the next box in a linked chain if the box only has one column or the insertion point is within the last column of the box. Equivalent to pressing ‘enter’ on the numeric keypad on the keyboard.
  5. \r Hard Carriage Return a hard carriage return / new paragraph. Equivalent to pressing ‘Return’ on the keyboard.
  6. \p New Paragraph a hard return / new paragraph again (why? It’s a long story...)
  7. \f Flex Space a QuarkXPress flexible space - equivalent to pressing option + shift + space (Mac) or ctrl + shift + 5 (Windows) on the keyboard.
  8. \. Punctuation Space a QuarkXPress punctuation space - equivalent to pressing shift+space (Mac) or ctrl + 6 (Windows) on the keyboard.
  9. \d Discretionary New Line a QuarkXPress discretionary new line character - equivalent to pressing z+ return (Mac) or ctrl + enter (Win) on the keyboard.
  10. \i Indent Here a QuarkXPress indent here marker - equivalent to pressing z+ \ (Mac) or ctrl + \ (Win) on the keyboard.
  11. \- Discretionary Hyphen a QuarkXPress discretionary hypen - equivalent to pressing z+hyphen (Mac) or ctrl + hyphen (Win) on the keyboard.
  12. \\ Backslash inserts a backslash character.
  13. \3 Current Page Number inserts the page number on which this text appears in the text flow (useful for creating page folios, for example).
  14. \2 Previous Page Number inserts the page number of the page on which the previous box in the current chain of boxes was located. Useful for inserting ‘Continued from page number...’ in text which flows over multiple pages.
  15. \4 Next Page Number inserts the page number of the page on which the next box in the current chain of boxes is located. Useful for inserting ‘Continued on page number...’ in text which flows over multiple pages.
  16. \# Auto Number inserts an automatically incrementing number for each instance of this element.
  17. \~ Hierarchical Numbering allows for Microsoft Word style hierarchical numbering - for example:
  18. A list of colours
<document>
<list content=”colours”>
<category><name>Primary</name>
<listitem>Red</listitem>
<listitem>Yellow</listitem>
<listitem>Blue</listitem>
</category>
<category><name>Other</name>
<listitem>Purple</listitem>
<listitem>Green</listitem>
<listitem>Orange</listitem>
</category></list>
<list content=”foods”>
<category><name>Meat</name>
<listitem>Beef</listitem>
<listitem>Lamb</listitem>
</category>
<category><name>Vegetable</name>
<listitem>Carrot</listitem>
<listitem>Turnip</listitem>
</category>
</list>
</document>
  1. 1 Primary 1.1.1 Red 1.1.2 Yellow 1.1.3 Blue 1.2 Other 1.2.1 Purple 1.2.2 Green 1.2.3 Orange
  2. A list of foods 2.1 Meat 2.1.1 Beef 2.1.2 Lamb 2.2 Vegetable 2.2.1 Carrot 2.2.2 Turnip

Hierarchical numbering gives you the option to choose the number of levels of hierarchy to number, and your choice of separator, period (1.2.3) or hyphen (1-2-3).

When using hierarchical numbering, the element to which it is being applied will detect and inherit the appropriate ‘contextual’ number from parent elements which also have ‘Auto Number’ or ‘Hierarchical Numbering’ defined. If you specify a number of levels of hierarchy greater than the number of parent elements with numbering defined, then only the appropraite number of levels of hierarchy will be displayed.

  1. You will notice in the example above that the numbering for each ‘listitem’ element resets so that every time a new ‘category’ element is inserted, the numbering of list item resets to 1. This is achieved by selecting the ‘Reset Numbering To’ option on the parent element (‘category’ in this case). Similarly, if ‘Reset Numbering To’ is also set for the parent of ‘category’ (‘list’), then the category elements within each list will be numbered from 1 (or whatever number you choose to enter in the reset numbering field). If this were not done, then the numbering would simply continue on. For example:
  2. A list of colours 1.1 Primary 1.1.1 Red 1.1.2 Yellow 1.1.3 Blue 1.2 Other 1.2.4 Purple 1.2.5 Green 1.2.6 Orange
  3. A list of foods 2.3 Meat 2.3.7 Beef 2.3.8 Lamb 2.2 Vegetable 2.4.9 Carrot 2.4.10 Turnip

You can also choose from 5 different numbering formats from the ‘format’ pop-up menu. This will display your numbering as arabic numerals, roman numerals, lower case roman numerals, alphabetic character (a,b,c etc.) or capital alphabetic characters (A, B, C etc.)

Can be dragged

This element can be dragged & dropped onto the page. If this is not set, then the element cannot be directly placed onto the QuarkXPress layout.

Parent elements automatically propagate their styling down to their child elements (unless the child has a different styling rule set). The styling of a child element may depend on its only being dragged onto the page implicitly, due to its parent being dragged & dropped, rather than explicitly by being dragged & dropped itself. Mistakes can be avoided by unchecking this option.

Can be mapped as child

If set, this element will be automatically mapped when its parent is dragged onto the page. The styling for the child element will be set according to the rules defined in this ruleset, but also, any styling applied to the parent element will also be inherited by this child element. However, stylings set for the child element will override those inherited from the parent element.

If this is not set, then the child element must be manually dragged onto the page. If there is a piece of information which is a child element that is unlikely to be used in your workflow, then you can un-check this option, so that it is not automatically imported every time its parent element is imported.

Element is an Image

If the element which you are editing the rules for is an image, then you should check the ‘Element is an Image’ checkbox. This activates the image settings functions, which are grouped together in the bottom left-hand corner of the ruleset palette.

The first of these settings is the Tag Type. If the references to images within the XML files which you wish to import with this ruleset contain paths to, or partial paths to, the image files on a file system, then ‘Path Name’ will be selected.

The next option you have is the tag name. This is a pop-up menu which lists all of the attributes which are associated with this element. You should select the attribute which contains the reference to the image from this list.

The next option, Box Type, allows you to select the type of action which Roundtrip will perform when dragging an item to the page. If this is set to ‘Use Existing Box’, then Roundtrip will only let you drag the image to a picture box which has already been drawn on the document. Should the box type be set to ‘Create Anchored Box’, then Roundtrip will allow you to drop the element into a text box, either on its own, or, more usually, as part of a parent element, and an anchored or inline picture box will be created, into which the picture will be imported. You can specify the size and other facets of this anchored box by clicking the ‘Modify Box’ button in this dialog, which brings up the standard QuarkXPress ‘Modify’ dialog, for you to specify all the appropriate settings for the box which will be created. Finally, if box type is set to ‘Create Floating Box’, then whenever you drag the parent element of an image into a text box, a new picture box will be drawn (one for each picture element which is a child of that parent element), and the picture imported into it.

Finally, you can choose how Atomik Roundtrip will fit the picture to the box - whether it will be scaled to fit the box, or whether the box will be scaled to fit the image. The options you have for this are:

Do Not Fit Image

Fit Box to Image

Fit Image to Box

Centre Image to Box

Fit Image to Box Proportionally

Conditional controls

Conditional controls identify the circumstances under which a rule will be applied. It’s possible to have multiple rules for the same element name, because there may be several different ways in which that element appears in the XML, which require different styling to be applied. By default, each rule is given the name of the element to which it applies, but you can give each rule a different name by changing the value in the ‘Rule Name’ field.

You can also change the XML element to which a rule is applied by picking a different element from the ‘Element’ pop-up menu.

Contextual rules - ‘Descendent of’

Contextual rules are defined by clicking the ‘Descendent of’ check box. They are called ‘contextual’ rules because they are dependant on the element’s ‘context’ or position within the XML hierarchy.

Elements with the same name can often occur in different locations within the XML file, but require different styling. In Tutorial 6, for example, we looked at an XML file with multiple instance of an element named ‘Title’, where an identically named element referred to the title of an article, the sub-title of two different types of section and the titles of books in the bibliography. It’s often important to be able to differentiate between these different uses of an element name, which you can do in Atomik Roundtrip by making multiple contextual rules, one for each of these contexts.

The context of an element is determined by identifying an element beneath which this element is located in the hierarchy. This doesn’t have to be a direct ‘parent’ element, however, simply an element which contains the element to which the rule is to be applied.

You are presented with two choices when making a contextual rule. The rule’s target can be specified as descending from an element - which offers you a list of all of the elements in the DTD - or from a rule. If you select that this rule will be descended from another rule, all the conditions of the first rule must be matched in addition to all the conditions of this rule being matched before the rule is applied. This allows you to make some very complex rules.

Attribute Rules - ‘With Attribute’

The next two options on the palette allow you to make a rule which is dependent on the value of an attribute of the XML element. By checking the ‘With Attribute’ box, and selecting an attribute, only XML elements of the type specified in the ‘Element’ pop-up which have the specified attribute defined in the XML will have this rule applied. Note that rules made in this way will apply the rule regardless of the content of the attribute. If you wish to make your rule more specific, so that application of the rule depends on the content of the specified attribute, you must check the ‘Value’ checkbox, and enter a value.

Rules whose application depend on an attribute are referred to as ‘Attribute rules’.

Of course, it could be the value of the attribute which you wish to appear on the page - rather than being used as a condition of the rule. To get the text content of the attribute to appear on the page, click on the ‘Map Attribute’ check box within the ‘Text’ section of the ruleset palette, and select the name of the attribute from the pop-up menu. Note that only attributes whose content is defined as ‘CDATA’ can be mapped in this way.

It is possible to mix the options above in order to create complex rules.

You will notice that the list of rules on the left-hand side of the palette not only lists the name of the rule (which can be changed, as described previously), but also, in the right-hand column, displays a description of the rule. The type of condition (or conditions) can be determined by the character which prefixes the condition in the listing.

Attribute Rule: ElementName&AttributeName or: ElementName&AttributeName=AttributeValue Mapped Attribute: ElementName:AttributeName Contextual Rule: ElementName<ParentElement

There are 4 control buttons in the top right-hand corner of the Roundtrip ruleset palette:

Revert changes the rest of the controls on the ruleset palette back to match the settings currently stored in the ruleset for the current rule. Any changes made to the current rule will be lost.

Save will save the settings in the ruleset palette to the rule currently selected in the list on the left hand side of the palette, overwriting previous settings.

Delete will delete the rule currently selected in the list on the left-hand side of the ruleset palette.

Add will add a new rule to the ruleset palette, based on the current settings in the palette.

These controls are sensitive to the current selection in the list on the left hand side of the palette, and the settings of the contextual and attribute controls. You should note that as the type of element referred to changes when you change settings in the contextual or attribute controls, if you make a change to these controls whilst setting a rule this is considered a new rule for the new type of element which you have specified. So you will need to click ‘Add’ to add this new rule, rather than clicking ‘Save’.