MOO API /

Documentation

Template Model

Template Model

The template object is described in XML and returned from the moo.template.getTemplate method. Templates describe how a single Side will be rendered onto one side of a Card. Templates define what individual items will be printed to the side of a card. It describes how the print product should be interpreted in terms of what content will be placed where. It also provides information about the print, cut and safe areas of the Card being printed.

Example Template Object XML

<Template xmlns="http://www.moo.com/xsd/template-1.0">
    <Code>businesscard_left_image_landscape</Code>
    <Version>1</Version>
    <Settings>
       ...
    </Settings>
    <Items>
       ...
    </Items>
</Template>

Core information

  • Code - string - The Code tag gives the templateCode for this template. If it ever mismatches the template code used to retrieve the template, this is a bug and should be reported to MOO. For clarity, the template code used in the moo.template.getTemplate method is the canonical name of the template.
  • Version - string - The Version tag identifies the version of the template in use currently. Right now, this is always 1. Logic surrounding issues such as dealing with different versions has not yet been finalised. More details will come when we know what's happening here.

Settings

The Settings element describes the information about how the template will be printed. It contains information about the print area itself, and information about how some of the other areas of the Side are defined.

Example Settings XML

<Settings>
    <Units type="millimetres"/>
    <Origin orientation="top-left" offsetX="0" offsetY="0"/>
    <PrintArea>
       <Width>88</Width>
       <Height>59</Height>
    </PrintArea>
    <BleedBox>
       <Centre x="44" y="29.5"/>
       <Width>88</Width>
       <Height>59</Height>
       <Angle>0</Angle>
    </BleedBox>
    <CutBox>
        <Centre x="44" y="29.5"/>
        <Width>84</Width>
        <Height>55</Height>
        <Angle>0</Angle>
    </CutBox>
    <SafeAreaBox>
        <\!-\-  assume safe area matches bleed for now @ 2mm \-->
        <Centre x="44" y="29.5"/>
        <Width>80</Width>
        <Height>51</Height>
        <Angle>0</Angle>
    </SafeAreaBox>
    <RotationAngle>0</RotationAngle>
    <FontSubstitutionStrategy>allLinesIfAnyNeeded</FontSubstitutionStrategy>
</Settings>

The following properties are defined:

  • Units - string - defines the units that this template is measuring in. All current MOO templates are measured in millimetres. Note that this is very deliberately intended to be in physical measurements, as using units of say "pixels" or "points" are entirely dependent on the print resolution used at the printer. Using millimetres means that there can be no ambiguity on what will happen to the final product.
  • PrintArea - Width/Height (float) - defines the total print area in millimetres. NOTE! This is not the size of the final card that the customer will receive (see the CutBox below), but is the total area we will use to print onto the physical paper. This is almost always larger than the final cut box so that we have a "bleed" which allows for the fact that the cut cannot ever be 100% accurate to the cut box. For most products we give a margin of 2mm around each edge. Our cutting is however usually well within 1mm of the "ideal" cut as specified by the CutBox.
  • CutBox - BoundingBox - defines the box such that if the Big MOO were a perfect sphere in a vacuum, the product that the customer receives would be cut on the edges of this box. Sadly, we operate in the real world, and so we have to allow for the fact the cut will never be exactly on the line. The end product that the customer receives should always be exactly the width and height of the given box, but the center point of the physical product will not usually be precisely where we say it is on the template. Although we promise only to not be more than 2mm away in any direction, we are usually well within 1mm.
  • SafeAreaBox - BoundingBox - defines a box (or boxes) that can be considered "safe" for content, in that as long as we uphold our promise of not being further than 2mm away from the "ideal" CutBox, then content with the safe area is guaranteed to be displayed on the final printed product. For a product like a businesscard, the SafeAreaBox will be the same distance inside the CutBox as the PrintArea is on the outside (by definition, if we actually cut the product a little bit to the left of the true box, we'll lose some content at the right-hand side of the CutBox). Note that for products where we have multiple Side's on the same physical side of the paper (holiday cards), the safe area may extend all the way to the print area on that side - this is fine and expected.
  • RotationAngle - float - defines the clockwise angle that the entire template will be rotated through after rendering. This is provided so that we have provide Business Cards with your details in a portrait orientation. By combining this with the definition for the Side on other side of the Card, the binding can be worked out for this card. Note that if we have a portrait front, and a portrait back - the front will be rotated by 90 clockwise, while the back will be 270 clockwise (rotate a card yourself to see why)
  • FontSubstitutionStrategy - string - defines the what will happen during the rendering process if there are some text characters in the Pack data that can't be printed with the font specified for that line. See the Font object definition for more information on the different strategies.

Items

The Items block defines all the individual content elements that can be rendered as part of a template. The order in which individual items are defined is unimportant. Each Item defines the following properties:

  • LinkId - string - a unique ID for the content item within this template. Uniqueness is enforced as part of the XSD. This LinkID is then used in the individual Pack data items to link them back with the content element on the template.
  • Layout/zIndex - int - a unique integer defining the Z-index order for the purposes of rendering. Arguably, we could have allows z-index'es to be non-unique, but in the case of overlapping elements, the end order would be slightly ambiguous. Forcing them to be unique means that there can be no ambiguity.

Each item type is covered individually below:

Text Item

A Text item defines a single line of text, which can provide some or all of the details on how that text should be rendered. Any properties which are not specified by the template MUST be provided by the Pack data item for this LinkID - this is sparingly used where a default setting would not likely provide a good result on the print product. The properties defined on a Text item are:

  • ClippingBox - BoundingBox - defines the Bounding Box for this text line. This cannot be overriden by the Pack user data. This serves 2 purposes:
    • Positions the text on the print area. The baseline of the text characters will fall exactly 25% from the bottom to take account of descenders in various characters (like a "y" "j" or "g")
    • If the text when rendered were to fall outside this box, it will be clipped and cut-off at the edge of this box. This can happen for instance if the point size is too large, or if too much text is entered by the user.
  • Font - Font - the Font to be used to render this line of text. If the fontFixed constraint is not enabled, then this can be overridden by the Pack user data. See the Font object definition for more information on the properties of the Font.
  • PointSize - float - the size of the text to be rendered, in the units of the template. So not actual points I'm afraid. This will almost always be in millimetres. To scale between actual point sizes and millimetres, the conversion factor is 25.4 mm / 72 points (so 7pt text = 2.4694444 mm). If the pointSizeFixed constraint is not enabled, then this can be override by the Pack user data.
  • Alignment - string - the alignment of the text within the clipping box. Must be one of "left", "center", or "right". If the alignmentFixed constraint is not enabled, then this can be overridden by the Pack user data.
  • Colour - Colour - the Colour to be used to render the text in this box. If the colourFixed constraint is not enabled, then this can be overridden by the Pack user data. See the Colour object definition for more information on how colours work.
  • Text - string - the default text content for the text line. If the textFixed constraint is not enabled, then this can be overridden by the Pack user data. Note that this will be in UTF-8 encoding (as should the Pack user data content)
  • Constraints - Constraint[] - specifies the constraints applied to this text line, allowing the Font, Colour, Alignment, PointSize and Text to be fixed by the template. These settings cannot be overriden by the Pack user data. These constraints are very strongly validated, and if the user data attempts to override a constrained element, this will be considered a validation failure and the Pack will not be accepted. This is to ensure that there is no ambiguity between what the Pack user data defines, and what will actually get rendered.

Example Text Item

<Text>
    <LinkId>back_line_1</LinkId>
    <Font>
        <Family>Helvetica</Family>
        <Bold>false</Bold>
        <Italic>false</Italic>
    </Font>
    <ClippingBox>
        <Centre x="59" y="12.75"/>
        <Width>44</Width>
        <Height>5</Height>
        <Angle>0</Angle>
    </ClippingBox>
    <PointSize>3.527777777</PointSize>
    <Alignment>left</Alignment>
    <Constraints fontFixed="false" colourFixed="false" pointSizeFixed="true" alignmentFixed="false"/>
    <Layout>
        <zIndex>2</zIndex>
    </Layout>
    <Colour type="RGB">
        <Red>0</Red>
        <Green>0</Green>
        <Blue>0</Blue>
    </Colour>
</Text>

MultiLineText Item

A MultiLineText item defines a block area of text possibly spanning multiple lines, which can provide some or all of the details on how that text should be rendered. Any properties which are not specified by the template MUST be provided by the Pack data item for this LinkID - this is sparingly used where a default setting would not likely provide a good result on the print product. Multi line text areas do NOT allow for inline styling of text at the moment, but they do provide automatically word-wrapping, and support forced line breaks within the rendered text. The properties defined on a MultiLineText item are:

  • ClippingBox - BoundingBox - defines the Bounding Box for this text area. This serves 2 purposes:
    • Positions the text on the print area. The baseline of text characters is defined by the Leading and/or BaselineOffset parameters for a multi line text area.
    • If the text when rendered were to fall outside this box, it will be clipped and cut-off at the edge of this box. This can happen for instance if the point size is too large, or if too much text is entered by the user.
  • Font - Font - the Font to be used to render this line of text. If the fontFixed constraint is not enabled, then this can be overridden by the Pack user data. See the Font object definition for more information on the properties of the Font.
  • PointSize - float - the size of the text to be rendered, in the units of the template. So not actual points I'm afraid. This will almost always be in millimetres. To scale between actual point sizes and millimetres, the conversion factor is 25.4 mm / 72 points (so 7pt text = 2.4694444 mm). If the pointSizeFixed constraint is not enabled, then this can be override by the Pack user data.
  • Leading - float - Leading is the vertical distance in millimetres between baselines of lines of text within the text area. This may be 0, in which case the default settings will be used based on the point size and font metrics. In general, if set, our recommendation is that this should be around 33% larger than the pointSize setting. At the moment, this setting cannot be overridden by the Pack user data. As such, for templates where the leading is specified and greater than 0, great care needs to be taken when overriding the pointSize property.
  • BaselineOffset - float - specifies whether the default baseline of the text should be moved either up or down. This is most commonly used to provide for a greater margin at the top or bottom of the box when the vertical alignment is not set to "middle". If not specified explicitly, the value for the leading is used. This ensures that the descenders of the last line (or ascenders of the first line) are not cut off by the ClippingBox setting.
  • VerticalAlignment - string - specifies the vertical alignment of the text within the text area clipping box. One of "top", "middle" or "bottom".
  • Alignment - string - the alignment of the text within the clipping box. Must be one of "left", "center", or "right". If the alignmentFixed constraint is not enabled, then this can be overridden by the Pack user data.
  • Colour - Colour - the Colour to be used to render the text in this box. If the colourFixed constraint is not enabled, then this can be overridden by the Pack user data. See the Colour object definition for more information on how colours work.
  • Text - string - the default text content for the text line. If the textFixed constraint is not enabled, then this can be overridden by the Pack user data. Note that this will be in UTF-8 encoding (as should the Pack user data content)
  • Constraints - Constraint[] - specifies the constraints applied to this text line, allowing the Font, Colour, Alignment, PointSize and Text to be fixed by the template. These constraints are very strongly validated, and if the user data attempts to override a constrained element, this will be considered a validation failure and the Pack will not be accepted. This is to ensure that there is no ambiguity between what the Pack user data defines, and what will actually get rendered.

Example MultiLineText Item

<MultiLineText>
    <LinkId>multi_line_text1</LinkId>
    <Font>
        <Family>Helvetica</Family>
        <Bold>false</Bold>
        <Italic>false</Italic>
    </Font>
    <ClippingBox>
        <Centre x="76" y="49.5"/>
        <Width>85</Width>
        <Height>77</Height>
        <Angle>0</Angle>
    </ClippingBox>
    <PointSize>10.2305555</PointSize>
    <Leading>0</Leading>
    <Alignment>center</Alignment>
    <VerticalAlignment>middle</VerticalAlignment>
    <Constraints fontFixed="false" colourFixed="false" pointSizeFixed="false" alignmentFixed="true"/>
    <Layout>
        <zIndex>2</zIndex>
    </Layout>
    <Colour type="RGB">
        <Red>0</Red>
        <Green>0</Green>
        <Blue>0</Blue>
    </Colour>
    <Text/>
</MultiLineText>

Image Item

An Image item defines an area on the template in which a user supplied image may be placed. The Image item is slightly different from the others, in that the user must provide EITHER:

  • Both resourceUri and imageBox from the Pack user data, in which case the specified image will be rendered into the specified imageBox (being clipped if necessary by the ClippingBox specified here)
  • None of resourceUri and imageBox from the Pack user data (or indeed on item with the relevant linkId at all), in which case no image will be rendered in this space

The properties defined on an Image item are:

  • ClippingBox - BoundingBox - defines a Bounding Box for the image data that will be displayed on the printed product. This cannot be overridden by the Pack user data. For more information about Bounding Box definitions and the properties, see the Bounding Box object definition. For more information about how the Pack user data imageBox and ClippingBox interact to produce the final rendered image, please see the Image Positioning page which provides much more information.
  • Constraints - Constraint[] - Provides a list of constraints about where the edge of the image box is allowed to be placed with reference to the total print area. To illustrate why - think of an coloured image placed on a white background such that the edge of the image is exactly on the CutBox specified for this product. In that case, when the final product is cut, the customer is almost guaranteed to have some white edges on the card (where the cut wasn't perfectly on the defined CutBox). As such, we strongly discourage imageBox edges on any side to fall outside a SafeAreaBox, but inside the PrintArea. HOWEVER - all the current templates currently specify that the image is allowed to be placed anywhere. This structure is slightly subject to change in a future release, and MOO reserves the right to start enforcing constraints

Example Image Item

<Image>
    <LinkId>variable_image_back</LinkId>
    <ClippingBox>
        <Centre x="16" y="29.5"/>
        <Width>32</Width>
        <Height>59</Height>
        <Angle>0</Angle>
    </ClippingBox>
    <Constraints>
        <TopEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
        <LeftEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
        <BottomEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
        <RightEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
    </Constraints>
    <Layout>
        <zIndex>1</zIndex>
    </Layout>
</Image>

FixedImage Item

A FixedImage item allows the template to specify that an image will be placed onto the template, possibly with the option for the customer to choose which image is going to be used. This is primarily used to support a set of background images for use on our holiday card products, but will be used more frequently in the future. If the FixedImage item doesn't provide a ResourceURI, then the Pack user data MUST provide that item, choosing from the allowed image choices.

Elements

  • ClippingBox - BoundingBox - defines a BoundingBox for the image that will be displayed on the printed product. This cannot be overridden by the Pack user data.
  • Constraints - Constraint[] - defines constraints on where the image edges are allowed to fall. In some respects this is slightly pointless given that the ImageBox is also being specified by the template, and currently cannot be overriden by the user data - however - if we decide to allow the user data to override the ImageBox information in the future, then the constraints would come into play.
  • ImageBox - BoundingBox - defines the bounds of the image as it should be placed underneath the clipping box. This cannot be overridden by the Pack user data for the moment. See the Image Positioning page for more information on how the ImageBox and ClippingBox interact to actually display an image.
  • ResourceURI - string - present, specifies the resourceUri of the image to be displayed in this image box, and cannot be override by the Pack user data. See the Resource URI page to understand the format for a resource URI.
  • ResourceURIChoiceList - ResourceUri[] - IF present, provides a list of possible image resourceUri's to be used in this image area, and the Pack user data MUST provide the chosen resourceUri from the given list.

Example FixedImage Item

<FixedImage>
    <LinkId>background_template</LinkId>
    <ClippingBox>
        <Centre x="53.5" y="76"/>
        <Width>107</Width>
        <Height>152</Height>
        <Angle>0</Angle>
    </ClippingBox>
    <Constraints>
        <TopEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
        <LeftEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
        <BottomEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
        <RightEdge outside="true" betweenBleedAndCut="true" betweenCutAndSafe="true" insideSafe="true"/>
    </Constraints>
    <Layout>
        <zIndex>1</zIndex>
    </Layout>
    <ImageBox>
        <Centre x="52.5" y="76"/>
        <Width>109</Width>
        <Height>152</Height>
        <Angle>0</Angle>
    </ImageBox>
    <ResourceURIChoiceList>
        <ResourceURI>filestore://image_original/0de6ac1a-4b5e-558545ee-48e0f7f3-30d0.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/2911eaff-1341-558545ee-48fc7a89-1e20.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/8d151674-5576-558545ee-48e0f80f-65df.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/826ed3a2-0176-558545ee-48e0f8cf-ef23.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/00484690-0648-558545ee-48e0f8df-0d48.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/1fc1fe87-094a-558545ee-48e0f8ea-ac8d.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/77d14003-1894-558545ee-48e0f943-3b8a.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/5c607ff0-193f-558545ee-48e0f954-085a.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/74242d21-1a0e-558545ee-48e0f963-80ad.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/2cd4266a-21e2-558545ee-48e0f9d5-406e.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/eacb1fcb-2410-558545ee-48e0f9f1-0e68.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/5ddd8dbe-253f-558545ee-48e0fa01-b0ad.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/fc8f153c-65d6-558545ee-48e38582-9fb7.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/29f76420-591f-558545ee-48e0edc6-93af.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/451e1f0e-59b8-558545ee-48e0edcc-711f.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/443cca58-5a12-558545ee-48e0edd2-ebbf.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/205854a7-7bb9-558545ee-48f4c909-eba5.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/e65adf05-5423-558545ee-48fc7fa5-19e2.pdf</ResourceURI>
        <ResourceURI>filestore://image_original/90af413e-1e00-558545ee-48f4c995-d0db.pdf</ResourceURI>
    </ResourceURIChoiceList>
</FixedImage>

Box Item

A Box item defines a content area which can be filled in with a colour. This is primarily used to allow the entire print area to be given a background colour.

Elements

  • ClippingBox - BoundingBox - defines the bounding box for this Box element. If filled, the block of colour will extend all the way to the edges of this box. This cannot be overridden by the Pack user data.
  • Colour - Colour - the Colour to use for the background box. See the Colour object definition for more information about the properties of the colours.
  • Filled - bool - specifies whether the box should be filled, or merely an solid outline in the specified colour. This cannot be overridden by the Pack user data. Currently, the template system does not provide a way to style the line - it's always a 0.3mm thick solid line.

Example Box Item

<Box>
    <LinkId>background_box</LinkId>
    <ClippingBox>
        <Centre x="44" y="29.5"/>
        <Width>88</Width>
        <Height>59</Height>
        <Angle>0</Angle>
    </ClippingBox>
    <Colour type="CMYK">
        <Cyan>0</Cyan>
        <Magenta>0</Magenta>
        <Yellow>0</Yellow>
        <Black>0</Black>
    </Colour>
    <Filled>true</Filled>
    <Layout>
        <zIndex>0</zIndex>
    </Layout>
</Box>
  Oh hi, nice to see you! Fonts Terms & conditions Privacy policy © MOO Inc., 985 Waterman Avenue, East Providence, RI 02914, USA - Registered in the United States of America.