Wiki

Case Status
Log In

Wiki

 
A Guide to OASIS XML
  • RSS Feed

Last modified on 6/9/2017 10:06 AM by User.

Tags:

A Guide to OASIS XML

Introduction

 

Reports and forms in OASIS run off of files called XMLs. These files are small snippets of code that preform basic tasks of arranging data on an x/y plane. In appearance, XML is very similar to HTML, however it has its own syntax that is custom built to the platform it is used on.

 

In this case, Ingen Software has created its own XML language for use in OASIS.

 

One important thing to note: you cannot change the name of an XML document to something else. If you are working on a QuoteCustomerCopy.xml, renaming it QuoteCustomerCopy2.xml will render the file useless to OASIS. Just keep that in mind when creating new documents. It's best to keep track of multiple XMLs by creating folders for each agency, and sometimes even more folders in the agency folder for each specific document.

 

Basic Syntax

 

 

 

<Document>

<document></document> - Every XML document must begin and end with these two tags.

 

Attributes:

name=“value” - This is for naming the document

 

 

<Title>

Similar to the <author/> tag, this tag is mostly used in the code side of OASIS.

 

Attributes:

data=”variable” - This is for pulling the title from a variable in OASIS

text=”value” - This is for naming the title manually

 

 

<Author>

Must be placed after the opening <document> tag, though typically directly after the <title/> tag. 

 

Attributes:

data=“value” – This attribute is usually used to hold the data=“user.FullName” that is used in OASIS for various functions.

 

 

<Page>

<page></page> - These tags must be placed in between document tags. Every XML document must contain at least one set of page tags. One XML can contain any number of page tags. These can be used to separate pages in a report like total pages or having one MFG per page, etc.

 

Attributes:

text=“value” - Sets the name of the page

width="value" Sets the width of the page. Default for portrait is “606”; default for landscape is “792”

height="value" - Sets the height of the page. Default for portrait is “792”; default for landscape is “606”

leftmargin="value" - Sets the left margin of the page

rightmargin="value" - Sets the right margin of the page

topmargin="value" - Sets the top margin of the page

bottommargin="value" - Sets the bottom margin of the page

 

 

<Header>

<header></header> - There can only be one pair of these tags per <page>. The header will always print at the top of the page's margin. It serves as a container for <line> and <vline> tags.

 

Attributes: none

 

 

<Footer>

<footer></footer> - There can only be one pair of these tags per <page>. The footer will always print at the bottom of the page's margin. It serves as a container for <line> and <vline> tags.

 

Attributes: none

 

 

<Content>

<content></content> - There can be any number of these tags in a <page>. These serve as containers for <line> and <vline> tags.

 

Attributes:

name=“value” - Used to specify the name of the content area.

data=“value” - Used to specify which TABLE the content area is pulling the variable data from. This can be very important when working with variables for a particular report/form.

 

 

<Line>

<line></line> - The contents of this tag (along with the field tags) are the part of the XML that is used most.

 

Attributes:

height=“value” - Used to specify the height of the line

width=“value” - Used to specify the width of the line

name=“value” - Used by OASIS to determine certain attributes about the line. Sometimes important for the report (in instances of name=“header” or name=“content”).

 

 

<Vline>

<vline></vline> -  Similar in concept to the line, the vline has some more advanced functions that are explained in the “Advanced Formatting” section of this document.

 

Attributes:

height=“value” - Used to specify the height of the vline

width=“value” - Used to specify the width of the vline

name=“value” - Used by OASIS to determine certain attributes about the vline. Sometimes important for the report (sometimes necessary; often when using name=“vline”).

data=“variable” - Used to specify a particular variable required for the vline to show. The specified variable must have data in it in order for the vline to appear on the form.

datawidth=“value” - Similar to width=“value”, this attribute will only effect the variables in the vline. The data in the variables cannot exceed the width specified in the datawidth.

fontsize=“value” - Used to create a default fontsize for the fields in the vline.

LineType=“value” - Used to identify certain line types to accept (subtotal lines, for example)

hardspace=“_” - Used for variables that contain “_” in the data. It removes the “_”s and replaces them with normal spaces.

 Once="Y" - Forces a line to print only once. Remove if you wish to enable line wrapping.

 

<field/> 

This is the main tag used in OASIS XMLs. It must be placed in either a <line> or <vline>.

 

Attributes:

x=“value” - Used for horizontal positioning on the x axis

y=“value” -  Used for vertical positioning on the y axis

height=“value” - Sets the height of the field

width=“value” - Sets the width of the field

halign=“left, right, center”  - Aligns the text within the set width of the field (width=”value”)

valign=“top, bottom, center” -Aligns the text within the set height of the field(height=”value”)

fontstyle=“bold, italic, normal” - Adds styles to the text

fontsize=“value” - Used to set the size of the font

hint=“ss=XX” - Used to assign fields with columns when exporting to Excel (i.e., hint=”ss=00” would equal the “A” column in Excel)

LineWrap=“Y” - When the text outsizes the specified width, this attribute will wrap the remaining text around below the current location (equal to the height value); similar to hitting the enter key when typing

DownSize=“Y” - When the text outsizes the specified width, this attribute will minimize the font's size until it fits inside the width

text=“value” - Used to display text on the report

data=“variable” - Used to display data on the report. Uses variables from the OASIS code. (i.e., data=”UserName”, etc.)

color="hexidecimal" - This will change the color of the data or text being printed in the field.

 

 

<rectangle/>

Used to create lines and boxes in XMLs. It must be placed in a <line> or <vline>.

 

Attributes:

x=“value” - Used to align the rectangle on the x axis

y=“value” - Used to align the rectangle on the y axis

height=“value” - Used to set the height of the rectangle (can be 0)

width=“value” - Used to set the width of the rectangle (can be 0)

color="hexadecimal" - Used to specify the color of the rectangle being drawn

 

 

<image/>

Used to display an image. It must be placed in a <line> or <vline>.

 

Attributes:

x=“value” - Used to align the image on the x axis

y=“value” - Used to align the image on the y axis

height=“value” - Used to set the height of the  image

width=“value” - Used to set the width of the  image

data=“variable” - Used to specify the variable that contains the  image

 

 

<fill/>

Used to highlight areas with color. Must be placed in a <line> or <vline>.

 

Attributes:

x=“value” - Used to align the fill on the x axis

y=“value” - Used to align the fill on the y axis

height=“value” - Used to set the width of the  fill

width=“value” - Used to set the width of the  fill

color=“hexadecimal” - Used to specify the color of the  fill

 

 

Other Tags

Comment

<!-- --> - This is a comment. Anything in between these two tags (including white-space) will not be compiled and added to the report. Best used for internal notes, hiding data (for removing columns without deleting the text) and a few other miscellaneous tasks.

 

 

The Data Dump Tag

There are hundreds of variables in OASIS to choose from for a report...however, loading every variable each time one report is run would slow or crash the system. This is why Brian chooses what data is necessary for each report each time it loads. Remembering what data is on which report would be almost  impossible, so we have a trick to use:

 

<dump/> - Must be placed after the opening <document> tag, but before the first <page> tag.

 

The <dump/> tag will give the user a text file each time the report runs. This text file is a list of all of the available variables for this particular report. For a detailed description of the data dump, see the related help sheet.

 

Advanced Formatting:

 

With these same basic tools, we can do some more advanced XML tricks.

 

The Vline:

 

Vlines are one of the most complex XML tags. They're complex for a reason though: you can do a lot of neat things with them. Here are a few examples:

 

 

Scenario #1:

 

You are asked to do a small edit to a report. They want the report to show the phone number ONLY if there is one in the system. Otherwise, they want it to be hidden.

 

You could go about doing that like this:

 

<vline height=”12” data=”PhoneNumber”>

  <field x=”0” y=”0” height=”10” fontsize=”9” data=”LineText”/>

</vline>

 

Notice that we use the data=“LineText”. This means that the field's data pulls from the data=”PhoneNumber” attribute in the <vline>.

 

 

Scenario #2:
 

You get a request to add a field in a report that will display the project name. The one catch is that the field must allow for long names, preferably to wrap around if it exceeds a certain length (say, 32 characters – which we will say is roughly 100 px in this example). This is the perfect time to use a vline.

 

<vline height=”10” datawidth=”100” data=”CleanProjectName”>

  <field x=”0” y=”0” height=”9” width=”110” fontsize=”8” data=”LineText”/>

</vline>

 

Notice we made the width of the field slightly bigger than the datawidth. This will ensure there are no odd looking text cut-offs in the form.

 

 

Special Functions:

 

In addition to displaying data straight, the data= attribute has another purpose: functions. Instead of this:

 

data=“value”

 

We have this:

 

data=“{(f)}”

 

This is the basic syntax for a setting up a function, where “f ” is a function.

 

Text With Data

{'Text' + var} - Used to display both text and data in the same line. Notice that this is the only function without ( ) brackets.

 

Examples:

 

<field x=”0” y=”0” height=”10” fontsize=”9” data=”{'Phone #: ' + PhoneNumber}”/>

 

<field x=”0” y=”0” data=”{'From ' + BeginTimeframe + ' to ' + EndTimeframe}”/>

 

<field x=”0” y=”0” height=”10” fontsize=”9” data=”{PageSlashCount + ' Pages'}”/>

 

 

Case

{(CASE var 'if' 'then' 'else')} - Used to output the “then” value when the variable equals “if”. Otherwise, it will display the “else” value, which can also be a variable. There can be any number of “if” and “then” pairs; however, you can only have one else. You must have at least one “if” and “then” pair as well as an else.

 

Examples:

                                                                  var     if   then   if    then   if    then   if   then   else

<field x=”0” y=”0” data=”{(CASE Rank '1' 'A' '2' 'B' '3' 'C' '4' 'D' 'N/A')}”/>

 

<field x=”0” y=”0” data=”{(CASE AllowEmail 'Y' 'Yes' 'N' 'No' 'Undefined')}”/>

 

<field x=”0” y=”0” data=”{(CASE TotalComm$ '0.00' '-' ' ' '-' TotalComm$)}”/>

 

 

Percent

data="{(PERCENT var1 var2 FORMAT)}" - This function is used to divide var2 by var1 and output the result in the FORMAT specified. Formats to choose from are: DOLLARS, PERCENT, and NUMBER.

 

Example:

 

<field x=”0” y=”0” data=”{(PERCENT Comm$ Sales$ PERCENT)}”/> - Displays the comm%

 

 

Add

data="{(ADD var1 var2 FORMAT)}" - This function is used to add var1 and var2 and output the sum in the FORMAT specified. Formats to choose from are: DOLLARS, PERCENT, and NUMBER.

 

Example:

 

<field x=”0” y=”0” data=”{(ADD Comm$ Overage$ DOLLARS)}”/> - Displays the earnings

 

 

Subtract

data="{(SUBTRACT var1 var2 FORMAT)}" - This function is used to subtract var2 from var1 and output the difference in the FORMAT specified. Formats to choose from are: DOLLARS, PERCENT, and NUMBER.

 

Example:

 

<field x=”0” y=”0” data=”{(SUBTRACT Comm$ AmountPaid DOLLARS)}”/> -  Displays the amount left to be paid

___________________________________________________________________________________________________________________________________________________________________________________________________________

PercentOf

data="{(PercentOf var1 var2)}" - Subtracts var2 from var1 and divides the result. Formats into percentage automatically.

 

Example:

 

<field x="0" y="0 data="{(PercentOf NetPrice SellPrice)}"/> - This performs the following: (Netprice - SellPrice)/SellPrice.

___________________________________________________________________________________________________________________________________________________________________________________________________________

PercentMarkup

data="{(PercentMarkup var1 var2)}" - Divides var2 by var1 and subtracts the result from 1.

 

Example:

 

<field x="0" y="0" data="{(PercentMarkup SellPrice NetPrice)}"/> - This performs the following: 1 - NetPrice/SellPrice. This does follow order of operations.

 

 

 

Left

data="{(LEFT var characters)}" - This function is used to restrict the output of a particular variable to a certain amount of characters. Where var is a variable and characters is the amount of characters to restrain it to.

 

Example:

 

<field x=”0” y=”0” data=”{(LEFT MFGID 6)}”/>

 

 

 

Sum

data="{(SUM table var)}" - Use this function to calculate the total on a table

The table parameter must be a table reference (e.g. a dynamic table).

The var paramter may be:

  • a column name in the table
  • a reference on an object stored in a column
  • or a non object value stored in the data area of the table (not of much use)

 

Example:

 

<field x=”0” y=”0” data=”{(SUM TABLE QuoteTotal)}”/>

 

<field x=”0” y=”0” data=”{(SUM TABLE Quote.Level1Total)}”/>

 

___________________________________________________________________________________________________________________________________________________________________________________________________________

Tips

 

It’s best to think of everything as a rectangle in xmls. When you create a <line> tag and enter its attributes for height and width, you are essentially creating a rectangle for which to place your fields in. It is possible to place fields outside the <line>’s attributes, but the next <line> will take place on the next available pixel, and possibly overwrite any fields that may print outside the first <line>.

Vlines are the most powerful tool available in xmls. These are used to their greatest effect (and most commonly) in the bill of material prints. When printing the bill of material, the vline essentially steps through each row of the table stored in the database, and fills out each field one after another. Once it reaches the end of the vline (</vline>) it will then go back and continue printing the rest of the table. Rinse and repeat until there’s no more information available for that transaction.