Plandroid Help Documentation

This section describes the structure of the XML catalog files. It is intended for advanced users and is only relevant if you intend to create or edit your own catalog files. You need to be familiar with XML syntax to edit an XML catalog.

The parts that are available for selection in the Parts catalog tab carry all of their information with them, such as part number, price and size etc. This information is stored in an XML catalog file that is located in the product application data directory (on Windows XP this is typically C:\Documents and Settings\All Users\Application Data\DelftRed\Plandroid\Catalog, but this can vary with operating system and computer setup). The catalog file must have the standard XML extension .xml, and must be digitally signed by DelftRed Simulation Technology to authenticate its validity.

XML Structure

The catalog XML file has the root element <catalog>, which has the attribute version, which is the catalog syntax version number (this is not the Plandroid version number). Catalog contains information on the catalog version (name, release date, and expiry date), the manufacturer and their terms and conditions (if any), and then the main section - the library of parts.

The Parts catalog tab
Parts tab

The parts catalog library is structured in 3 tiers, just as they are shown in the Design -> Parts catalog tab. The top layer is the part type layer (<partType>), which are the most general categories, and are shown in the topmost window of the Parts catalog (e.g. Diffuser). The part type can contain multiple part sub-type (<subtype>) elements. These usually represent one family of parts, and are shown in the middle window of the Parts catalog (e.g. Metal Louvre Face). The part sub-type can contain multiple part elements. Each part has its own product code, size info, icon definition, connection data, price, and any other information needed by the program (e.g. LFR2525, of size 250x250mm). A part represents the physical object that is taken off a warehouse shelf and put into a building. In the same way, only parts can be placed into the design canvas.

PartTypes, Subtypes, and Parts

Any of these catalog elements may contain an attribute for the following properties:

All of these catalog elements must contain sub-elements for the following properties:

And any of these catalog elements may contain sub-elements for the following properties:

PartType and Subtype elements may also have the following attribute:

Inheritance

Unless redefined, a part will inherit the settings for these fields from its parent subtype, which in turn will inherit its settings from its parent part type. For example, if you are defining a part type Diffuser which has the property that it should be installed in the second fix, you can define its fix property just once in its part type definition (at the highest level). All subtypes that descend from Diffuser will inherit that setting and therefore also be defined as second fix, unless they have their own fix property defined otherwise. Similarly, descendant parts will inherit the same setting from their parent subtypes if they don't have their own fix definition. Info fields are not inherited.

Image Sizes

The image element has the attributes width, and height. These define the size that this icon will have, in mm, when placed on the design canvas. (The image metafile's true size is used in the scaling calculations, not its reported size - these are often different.) If only the width is given, the icon height will be set to the width. The part icon drawn in the Part list view is scaled against its parent sub-type image size. The sub-type image size definition is optional. If it is not given, it is calculated as the largest width and height of all its child part icons.

The size of the top level part type icon has no significance beyond adjusting that icon's aspect ratio in the list view.

The image element may also have the attribute flip, taking the values "x", "y","xy", or "" (for none) indicating the axes used to flip the part image. This setting is the only one that is not inherited according to the usual rules as it is deliberately not inherited from the part type to the subtype. It is inherited normally from the subtype to the parts, however. There are a number of subtleties involved in using this attribute correctly.

Subtypes

A sub-type definition may contain sub-elements for the following properties:

Parts

A part definition must contain sub-elements for the following properties:

A part definition may additionally contain sub-elements for the following properties:

List View Labels

The actual label shown in the part list view is the label, if it is defined, otherwise the size, if that is defined, or else the product code, which must be defined. For example, the list view label for a part may read "100mm sq" as a more convenient text than the size, which may be "100x100mm". The label is shown both in the parts list view, and on the canvas depending on the Options -> Design -> Show labels user options selected.

Part Sizes

The size field is sometimes parsed for various functions, and must be in a strict format of: [prefix]Length[xLength[xLength]]units. The only valid prefix is the engineering diameter symbol: "ø". Different lengths can be specified in different units, but the units suffix should be applied to the last of the series of numbers which are given in that unit. Recognised units (and suffixes) are: millimetres (mm), metres (m), feet ('), and inches ("). For example, sizes may be defined as: 200x200mm, or 200mmx6m, or 8". Combining units for a single length, for example feet and inches, is not supported, neither is specifying fractional units, such as 1/2".

Duplicate Product Codes

All product codes in a catalog must be unique. However, if a part needs to appear multiple times in a catalog because it is relevant in different sections, or it appears with multiple different views (top, side, front etc.) this can be achieved by using the same product code with a suffix in parentheses, where the suffix will be removed when viewed in the Costing page. For example, a part can be represented twice in a catalog by using the two unique product codes DBTO and DBTO(B). In the Costing page, these two parts are counted as two instances of a single part (part DBTO), and are therefore counted together. Only the price from the cannonical part (DBTO in this case, with no suffix) will be used — any price assigned to the duplicate part is ignored. It is therfore the catalog pricer's responsibility to ensure that the costing is consistent for all duplicate parts so that the catalog is not misleading.

You should always have a cannonical version of a part (with no suffix) in the catalog you are using if you are also including a duplicate (with a suffix). If a catalog does contain multiple parts with the same product code (not recommended), or if there is a coincidental product code clash when loading multiple catalogs, the program will detect this and automatically assign unique numerical suffixes (1), (2), (3) etc. to the subsequent parts. Note that if a clash of this type occurs your costing may be incorrect, as the part that is loaded first will be considered the cannonical part and its price will be used for all duplicates.

The suffix can be of any length, and multiple suffixes can be used, for example DBTO(Bottom View) or DBTO(B)(1)(Special) are both valid. In the latter case, all suffixes will be removed from the first "(" to the last ")".

Clearly any actual product code that for any reason happens to end in parentheses is not supported and must be modified. A suitable work-around for this is to add a space to the product code after the closing parenthesis, e.g. ") ", so that it is not treated as a duplicate product code.

Note that parentheses are not valid characters for regular expressions, and can cause problems when adding product codes to the Automatic Design parts product codes in the Options Settings. For this reason you can also use the tilda (~) as a suffix marker, for example: DBTO~B~.

Notation

Note that a period (".") must be used for decimal point in all catalog numeric values, and not a comma (",").

Auto-adding Parts

The element add itself contains one or more sub-elements code. This specifies the product code of a part which, if found in the current catalog, is automatically added to the canvas whenever the parent part is added. If the product code is not found in the current catalog, the part is not added and no warnings are given. The application will recognise and avoid circular dependencies - if a part tries to add one of its own ancestors, that addition will be skipped. Therefore parts which always go together can each be defined to add each other without problems. For example, a supply starter fitting can add its matching return fitting, and that same return fitting can itself add its matching supply fitting. Whenever one of these two parts is added, its matching pair will also be added.

When it is a child of an add element, the code element may have the optional attributes offset_x, offset_y, and top. The offset values specify the distance in mm that the added part should be placed from the parent part (distance to the right is +x, and distance down is +y). Both attributes default to 0. The top attribute is a Boolean (true or false), and specifies if the added part should be displayed on top of the parent part (true) or underneath it (false). The default is true. Added parts will automatically attempt to snap-to any compatible connections within snapping range on their parents before being added to the canvas.

You can also define your own add parts in the Catalog Edits File, and even use the special Auto Add This Part to tool to define them automatically.

XML Structure Example

The following XML snippet shows an example of the 3 tiers of a part definition:


 <partType name="Diffuser">
    <fix>2</fix>
    <installTime>25.00</installTime>
    <installCost>35.00</installCost>
    <!-- part type image dimensions are arbitrary -->
    <image width="32" height="32">
      <file>Diffuser.emf</file>
    </image>
    <subtype name="Metal Louvre Face" function="face">
      <info>Solid metal construction</info>
      <!-- The subtype image dimensions are optional, and are in mm -->
      <image>
        <file>Diffuser_MetalLourve.emf</file>
      </image>
      <part>
        <code>LFR2535</code>
        <price>20.80</price>
        <size>250x250mm</size>
        <label>250mm sq</size>  
        <info>Face 350x350mm</info>
        <!-- part image dimensions are required, and are in mm -->
        <image width="350" height="350" />
        <add>
          <code offset_y="800" top="false">NKAD25</code>
          <code offset_x="100" offset_y="-100" >F77</code>
       </add>
      </part>
    </subtype>
  </partType>

A/C Units

Air conditioners (function="<unit_type> unit" are somewhat more complex, and should have the following additional sub-elements defined, as they are used to calculate the design air-flows:

The values of output (air flow), cool (cooling power), and heat (heating power) are used in the automatic designer, for checking the design with the Design page toolbar button Check design, and for reporting the supplied air in the zones table displayed with the Show zones table toolbar button.

The following sub-elements may be defined, but are for information only and are not used for any calculations in the program:

These attributes may be defined, and are also for information only as they are not yet used for any calculations in the program:

The following example shows a typical unit catalog definition:


      <part function="rc unit">
        <code>AC51</code>
        <price>1680.80</price>
        <size>900x450,700x400,�13,�2mm</size>
        <label>5.1kW, 350L/s</size>
        <phase>1</phase>
        <cool AEER="2.88">5.1kW</cool> 
        <heat ACOP="2.95">6.0kW</heat> 
        <output>350L/s</output> 
        <image width="350" height="350" />
        <add>
          <!-- Attic tray -->
          <code offset_y="800" top="false">AT125-65</code>
          <!-- Outdoor unit -->
          <code offset_x="100" offset_y="-100" >TCU5000</code>
       </add>
      </part>

Part Functions

The program uses the optionally defined part function attribute to determine how to handle the various parts. Valid functions include (but are not limited to) the following:

Note that a part designated as an outlet should be the terminal part which is connected to ducting, as this part is interrogated for its connector size for calculating airflows. For example, for a plastic vent this is often the part itself, but for a metal vent, this will usually be the neck adaptor.

A part with the function symbol will be resizable in the canvas. Any part with a function that starts with symbol will not be added to the costing. This distinction can be used to create symbols that cannot be resized and are also not costed, for example by giving them the function symbol2.

Manufacturers

Information on the manufacturer of the parts is read from the <manufacturer> data at the <catalog> level, and may be used by the program in automatic ordering, for example. It is also possible to redefine the manufacturer information at any part level. The possible fields are shown in the following example, where only the <companyName> field is mandatory when used in this way:


 <manufacturer>
    <companyName>Company Name</companyName>
    <companyURI>http://www.company.com</companyURI>
    <units>Metric</units>
    <contact>info@company.com</contact>
    <orderEmail>orders@company.com</orderEmail>
    <terms>Terms</terms>
    <warranty>Warranty</warranty>
    <notices>Notices</notices>
    <watermark>
      <file>Image.png</file>
      <hash>Akm5u+S293bxgA=</hash>
    </watermark>
  </manufacturer>

Note that the manufacturer can include their own watermark if they so choose, which will be applied to any design image created using a catalog from that manufacturer. The watermark image is protected by a hash code, which guarantees that it has not been modified in any way.

Connection Definitions

Two parts can snap-to if they each have compatible connectors. Connectors are compatible if they have the same types (that is, the same shape and compatible axes), and they have the same size. Snap-to connection definitions in the XML catalog have information on the shape, size, and location of each connector that is overlaid on the part icon, as shown in the following XML snippet:


 <connector>
    <type shape="Circular" axis="Fixed" />
    <size width="200" height="200" />
    <position x="-200" y="365" angle="180" />
 </connector>

The connector shape can be one of:

The Fitting shapes allow you to define connections that can connect to other fittings only, such as modular plastic moulded components which snap together but that can't connect to ducting.

The axis defines the type of angle at which the parts can connect, and can be one of:

If either connector is Free, the connection will be able to rotate. If both connectors are Fixed, both parts will remain at a fixed angle to each other. A connector that is FixedOrFree will be Fixed if it is mated to a Fixed connector, or Free if it is mated to a Free connector. Two mated FixedOrFree connectors result in a Free connection.

The type element can also take an optional attribute checks of type boolean which specifies if the connector is highlighted when the Check Design tool is used (defaults to true). This is used to exclude a connector from the checks if it does not need to be connected, such as for a damper motor connector.

If the size width and height are the same, you can specify the width and leave out the height.

The connector position is defined from the centre of the icon, where x is positive to the right, and y is positive downwards.

Connector Inheritance

Connectors can be defined at the sub-type level, or at the part level. If defined at the sub-type level, all parts of that subtype inherit the given connectors.

A connector's type, size, and position can be redefined in a <connector> element for any individual part, however it need not be. If it is not given in the connector definition at the part level, the connector size and position will be automatically calculated from the part <size> string (e.g. <size>500x400mm</size>), and follows the following rules:

Note that a connector can be created for a part either by specifying a <connector> element for the part, or by specifying the <size> element with the size data to be used for the corresponding inherited connection.

The inherited connector position, if it needs to be calculated, is scaled from the part's image size relative to the sub-type's image size. For example, if the current image is half the size of the subtype image, the position of the connectors is half that defined in the subtype connector definition. (If the sub-type image size is not given, the largest part image size belonging to that sub-type is used.) Connector angles are not scaled.

Note that even if a connector is defined at the sub-type level, it can be either fully or partially redefined within a <connector> element at the part level, and the connector properties given at the part level will take precedence. Any connector properties that are not given are either inherited from the sub-type connector, or calculated from the part's properties as described above. Note that if a part has multiple connectors, and some of them redefine their properties and others inherit all of their properties, you should still define an empty connector element (i.e. <connector/>) for those connectors that inherit all their properties. If only some of a Part's connector definitions are given, missing connectors will not exist even if they are defined at the sub-type level. Refer to the provided catalogs for examples of how to define connectors with inherited data.

Specifying No Connectors

If a connector has the shape None, then it will result in no connector being defined. No axis needs to be supplied in that case. This is useful for removing a connector that was defined at the subtype level, and would otherwise be inherited by a part. Similarly, a connector will also not be created if there is no <size> definition for that part, regardless of any connectors specified at the subtype level.

Multiple Connector Sizes

A connector may be defined with multiple sizes. This allows a single connector to match a range of sizes for a given shape. This can be specified in two ways: from within a <connector> element multiple <size> elements can be defined, or multiple <size> strings can be supplied at the part level. The two methods are equivalent.

When defining multiple connector sizes with multiple <size> elements, if some connectors take fewer sizes than others, simply repeat a valid size for those connectors. For example, this:


      <part>
        <code>LFR4030</code>
        <price>25.00</price>
        <size>�400x�300x�200mm</size>
        <size>�400x�350x�250mm</size>
        <size>�400x�350x�300mm</size>
        <image width="350" height="350" />
      </part>

...defines one size for the first connector (�400mm), two sizes for the second connector (�300mm and �350mm), and three sizes for the third connector (�200mm �250mm and �300mm). In the case of the second connector, it makes no difference which size is duplicated.

If a connector size has a width of zero (0), then that connector will match any width. Similarly, a connector of height zero (0) will match any other connector height.

Icon Image Files

All part icons must be in the Microsoft Enhanced Metafile Format (.emf). This is a vector format which gives good resolution at any zoom level. EMF files can be exported from Adobe Illustrator, for example. For a catalog file called MyCatalog.xml, the application will first look for a directory called MyCatalog_Images for the image files to use for the part icons. If the directory does not exist or image file is not found there, the application proceeds to look in the Default_Images directory for the image file. This gives the catalog designer complete flexibility to specify their own part artwork, or to use the default artwork provided. When importing a catalog, the application will look for the <filename>_Images directory in the same location as the catalog file <filename>.xml and also import it and its contents. (If you import an image file by itself, the application will place that file in the Default_Images directory.)

The physical size of the EMF image is unimportant - it is a vector image that will be scaled to the physical size of the part as given in its XML image element. However the file size of the image is important, as a file which is too large will have a detrimental impact on the graphics performance of the application. It is recommended to limit the EMF file size to less than 20 KB, and to keep below 10 KB where possible.

The part type image (but not the sub-type nor part image) may be in either EMF or PNG format. It is normally sized at 32x32 pixels (or smaller), which is the size of the list view icon in the catalog list.

Digital Signatures

To be used by the program, a catalog file must carry a valid digital signature from DelftRed Simulation Technology. If any changes are made to the file since it was signed, the digital signature is rendered invalid. A valid signature authenticates that the file has been checked by DelftRed Simulation Technology for correctness, and guarantees that the catalog data has not been tampered with in any way since it was signed. Contact us at info@plandroid.com to request signing of your finished catalog.

Testing a Modified Catalog

If you are developing your own catalog you can still test it with the application yourself before requesting our signing services. Plandroid will still read a catalog which has no signature or an invalid signature if both its expiry date and its release date set to the current day, today. For example, if today was 1 March 2012, you should set:


  <catalogVersion>
    <catalogName>My Test Catalog</catalogName>
    <releaseDate>2012-03-01</releaseDate>
    <expiryDate>2012-03-01</expiryDate>
  </catalogVersion>

The program will still report an invalid or missing signature upon reading your modified catalog, but it can still be used for testing and verification purposes. Again, contact us at info@plandroid.com to request signing of your finished catalog.

Embedded Watermarks

Plandroid supports embedding a watermark image into a catalog, so that whoever is using that catalog has the watermark image drawn onto their design in a similar fashion to the user-defined watermark option in the Options -> Report tab. (See the Watermark section for more information.) With this option, designs made with parts from a certain supplier can be marked as such. Contact us at info@plandroid.com to take advantage of this service in your own catalog.

Catalog Price Edits Files

The CatalogEdits.xml file contains all the catalog information that has been changed by the user, such as edited prices, price modifiers, etc. You can even add in your own Add Parts definitions to completely customise your own catalog's behaviour. You can choose to keep your edits to yourself, or to share your edits with everyone else on your computer by using the Options setting Costing -> Catalog Edits -> My edits apply to: Me only / All users. If you keep your edits to yourself, no other user can inadvertently change the pricing scheme you are using.

The menu item Import -> Price Edits File can be used to import an existing price edits file containing the price definitions that you wish to use. Whether this file is applied just for you, or for all users on your computer is again determined by your options settings.

Switching Price Edits Files

You can switch between different price definitions that you have imported from the menu item Tools -> Select Catalogs and then pressing the Set Price Edits button. This will set the catalog prices according to the new Catalog Edits file, which is useful when you have different discount structures for different parts of your business. You can also use the context menu in this window to delete an old edits file, or to save a copy of one so you can edit it manually or give it to a colleague to use as well, for example.

Catalog Edits File Structure

The following example, containing edits information for two parts, illustrates the file structure:


  <catalogEdits Version="1.0">
    <part>
      <code>AC51</code>
      <modifier>0.16</modifier>
      <price>2468.00</price>
      <label>New Label</label>
    </part>
    <part>
      <code>ABC3020</code>
      <price>25.00</price>
      <installCost>50.00</installCost>
      <installTime>30.00</installTime>
      <add>
         <code offset_y="800" top="false">NKAD25</code>
         <code offset_x="100" offset_y="-100">F77</code>
         <!-- Drawable parts may optionally have both a start and end offset defined, as follows: -->
         <code offset_x="200" offset_y="0" offset_x1="1059" offset_y1="-1550" >PF640</code>
      </add>
    </part>
  </catalogEdits>

The <code> field contains the product code of the part that has been edited, and the subsequent fields contain the new part data. If you need to edit the prices of many parts at once, you may find it easier to go directly to this file and enter all of your pricing information directly with a text editor program, for example.

Note that if the listed item is not present in an active catalog, it will be ignored. Similarly, if a part is modified that has the same product code as another different part in a different catalog, that other part will also be modified if its catalog is loaded. The price currency is assumed the same as in the catalog where the part is defined.

The next section is the How do I? section.