Reports and forms in OASIS run off of files called XMLs. These files are small snippets of code that perform 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. Ingen Software has created its own XML language for use in OASIS.
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. 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 affect the variables in the vline. The data in the variables cannot exceed the width specified in the data width.
fontsize=“value” - Used to create a default font size 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 is drawn
<image/>
Used to display an image. It must be placed in a <line> or <vline>. It will scan the file the data variable calls and then attempt to fit it to the dimensions defined in the image. Please note that if the image is too large, it may have issues printing it properly if at all.
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 data width. 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 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 number 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 parameter may be:
- a column name in the table
- a reference on an object stored in a column
- or a nonobject 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.
Comments
0 comments
Please sign in to leave a comment.