==Overview==XML (Extensible Markup Language) is a type of custom field used to create budgets and lists of information. This advanced custom field opens in a separate window from the main browser screen, it can have multiple sections, and it is robustly configurable (formulas, validation, reporting).
If you are looking to create a basic list or budget, you can also use the field called '''[[Custom Field TypeFile: Special - In-Line Data GridxmlSample.png|Special - In-Line Data Gridframe|none|middle|Example field configured as a budget sheet.|500px]].'''
[[File:xmlSampleThis field type can be used to create worksheets or tables such as budget sheets, and lists of information.png|The look A wide range of an XML|500px|border]]complexity is supported from very simple tables to multi-section, multi-year budgets. This is accomplished through the ability to configure sub-sections within the same worksheet, and also define automatic cell calculations. This all adds up to a very robust, and flexible field.
Creating a By default, the data for this field is stored in the structured XML is (Extensible Markup Language) format. However, you also have the option to instead use this field as a multi step processpresentation layer for lists of sub-activity records. For convenience we have grouped how example, you do specific tasks under several groupingsmay use this field on a UTA Level 1 record to display any associated UTA Level 2 records for a user to easily update the activities or create new activities.
If you are looking to create a basic list or budget, you can also use the field called '''Configuring [[Custom Field Type: Special - In-Line Data Grid|Special - In- EssentialsLine Data Grid]].'''*Creating a Special - XML Data custom field*Create XML section with defined number of rows*Create XML section with dynamic number of rows*Display XML sections
'''Configuring {| class="wikitable"| Summary| |- Advanced'''*Creating formulas (calculations) | Commonly Used in XML cells*Adding a formula to a XML cell Markets (working with data in the same sectionPhilanthropy, Research, Insurance)*Adding a formula to a XML cell (working with data in the different sections)| All*Validate XML values when saving the worksheet|-*Validating values when saving record | Used By (SmartCheck, Submit Logic, Browser ScriptUser Type)| All|-'''Displaying the XML data'''| Requires Administrator Setup*Displaying XML data on a object| Yes*Access, Display and Format options for XML data|-*Styling XML data for web and print | Configuration Complexity (PDFLow, Medium, High)*Reporting on XML data| High|-'''XML - Appendix'''| Time to Configure (Minutes, Hours, Days)*Field options and settings| Hours*Example of an XML|}
== Configuring Configuration - Essentials ==
=== Creating a Special - XML Data custom the field ===
Typically XML Data custom fields are created for UTA level 1, 2 or 3, (e.g. a grant application) or they are created for organizations. To create a XML custom the field:# Navigate to the desired place, settings area where you want to create the XML custom field a worksheet (e.g. the UTA level 1).
# Click the '''New Field''' (+) button.
# For Field Type select '''Special - XML Data'''.
# Enter a '''Field Name''' and '''Caption'''.# Click '''Save'''.
== Create a Simple Table ==
Using the XML '''Section Builder''' you can create sections and define the attributes of each section and the cells within them. You can define the number of rows and columns, the display format, calculation formulas, and style your XML.
=== Create XML with defined number of rows ===Use the XML '''Section Builder''' to create sections, including defining the number of rows and columns displayed, formulas, and style your XML[[File:xml-sectionbuilder1. Note: This feature is switched on by default, but you can manually enable the '''Section Builder''' if previously disabledpng|frame|none|middle|The section builder.|500px]]
[[File# While editing the custom field click on the '''Section Builder''' button (the four square icon) in the action bar.# Create a '''New''' section and enter a '''Section Name''' (e.g. Expenses).# Enter '''Number of Rows''' and '''Number of Columns''' desired.# Once you '''Save''' you will be brought to the '''Cell Details''' tab.# Define a '''Display Name''' for each of the row and column headers.# Within each of the column headers you can define a '''Format''' for the column (e.g. plain text, currency, date). For numeric formats you may also specify a precision.# Note:xml-sectionbuilder1to avoid confusion it is recommended to use unique node names of sections, rows, and columns within the field.png|The section builder|500px|border]]
== Create a Table with a Dynamic Number of Rows ==
# In the action bar click on the '''Section Builder''' button (it has four squares on it).# Click the '''New''' button.# Enter a '''Section Name''' (e.g. '''expense''').# Click into the '''Section Node Name''' (the name auto populates. Note[[File: '''Section Node Names''' are case sensitive).# Enter '''Number of Rows''' desired.# Enter '''Number of Columns''' desiredxmlDynamic.# Click '''Save''' (this will bring you png|frame|none|middle|Example section set to the '''Cell Details''' tab).# Click into the first cell of the '''Cell Grid''' at the top left.# Enter a '''Display Name'''.# Click into the top row of the column labeled '''1'''.# Enter a '''Display Name''' and a '''Node Name'''.# If desired choose the '''Format''' (e.g. text, number, comma, date, currency, percent). NOTE: If you select number, comma or percent you can also specify precision settings (e.g. Whole Number, Nearest Hundred). If you select currency you can also specify precision and currency settings (e.g. US Dollar, Euros).# Repeat for the remaining column headers.# Click into the first cell in the row labeled '''1'''.# Enter a '''Display Name''' and '''Node Name'''.# Repeat for the remaining row labels.# Click the '''Build''' button.# When you are done, navigate from the builder back to the field by clicking the '''Field''' button.Note: Do not use the same node names across different sections, dynamic rows or columns in the xml.|500px]]
=== Create XML with dynamic In addition to defining a set number of columns and rows ===The XML section builder , you can also be configured configure a section to allow handle a dynamic number of rows. The user entering the user to data can add additional rows as necessary at time of entry. This is done by entering '''0''' for the '''Number of Rows''', which in turn exposes the following configuration options: * '''Maximum Number of Rows''': Set a maximum limit to the number of data using rows that can be entered, or leave as 0 for no limit. * '''Maximum Message''': The message to be displayed when the maximum limit is set and reached by a plus buttonuser. A default message is displayed if left blank.
[[FileSetting the Number of Rows to 0 also exposes the following configuration options for each column header within the Cell Details tab:xmlDynamic* '''Has Total''': Display the total sum of a column.* '''Total Row Label''': For columns without a total display this option allows you to enter a label for the total sum of another column. For example, if column 3 was displaying a total, then you could configure the '''Total Row Label''' of column 2 to display 'Total'.png|The dynamic XML|500px|border]]
It is configured by entering '''0''' for == Configure the Number Display of Rows, which in turn exposes the following configuration options in the Section Details tab: * '''Maximum Number of Rows''': if left as 0 the user can add as many rows as needed. If populated with a numeric value the user can only add up to and including that number of rows. * '''Maximum Message''': message to be displayed if user tries to add more than the specified maximum number of rows. A default message is displayed if left blank. Tables ==
Setting the Number The presentation of Rows to 0 also exposes the following configuration options XML Data custom field is configured in the Cell Details tab: * '''Has Total''': will appear when clicking into general settings page of the section's column headersfield. Check '''Has Total''' to automatically sum and display all This is defined in the items in that columnXSL Template (Extensible Style Sheet Language) option. The XSL Template includes a sample template option. * '''Total Row Label''': Once you have inserted sample template you will need to specify which sections should appear when '''Has Total''' is switched off. Text entered here will and where they should appear as a label on the row used to display the totals.
Even though you set the number of rows to 0 you still need to configure one row of data which will be used to format the dynamically created rows[[File:xml-xsl.png|frame|none|middle|The XSL template and configuration.|500px]]
=== Display XML sections ===The XML Data # While editing the custom field has an locate the '''XSL Template ''' option within and insert the '''Sample Template'''.# Locate the overall XML Data custom field settingsbelow marker. <pre><!---- Insert section variable here ----></pre> # Below the marker, insert variable references to the each section with the following syntax (e.g. @section. The XSL Template is used Expenses@) in the order in which you wish the sections to define how appear. Note: the XML will be displayedsection node name is case sensitive. XSL stands for Extensible Style Sheet Language @section. ''SectionNodeName''@
The XSL Template includes a sample template option. Once you have added the sample template you will need to specify which sections should appear and where they should appear. = Configuration - Advanced =
[[File:xml-xsl.png|The XSL template|500px|border]] # In the Section builder click the field button to return to the overall XML Data custom field settings. # In the '''XSL Template''' click the '''Sample Template''' link.# Replace <pre><!---- Insert section variable here ----></pre> with <pre>'''@section.''SectionNodeName''@'''</pre># Click '''Save'''. The syntax '''@section.''SectionNodeName''@''' will display the section we created using the section builder. Note: you must replace '''SectionNodeName''' with the name you gave your section (e.g. '''@section.''expense''@'''), the section node name is case sensitive, and you must remove the html comments. == Configuring - Advanced == === Creating formulas (calculations) in XML cells ===
[[File:xml-formula.png|Adding a formula|500px|border]]
=== Adding a formula to a XML cell (working with data in the same section) ===
# Navigate to your XML custom field.
# Click the '''Section Builder''' button in the action bar.
The Syntax for basic calculations within a section:
{| borderclass="1wikitable"|'''Operation'''|'''Symbol'''|'''Example'''
|-
| Add
|}
=== Adding a formula to a XML cell (working with data in the different sections) ===
=== Validate XML values when saving the worksheet ===
=== Validating values when saving record (SmartCheck, Submit Logic, Browser Script) ===
In addition to validating values when you save the XML worksheet you can also validate the XML worksheet when you save the record (e.g. save a level 1 grant application).
==== SmartCheck Validation ====
Use SmartCheck for XML validation when possible. SmartCheck validation is a secure server side method. SmartCheck also displays all error messages in a context as well as in one central place.
<pre>if("<ssEscape>@level1.xml.fieldname.sectionnodename.rownodename.columnnodename.nodevalue@</ssEscape>"=="")
{result.isPassed=false;
result.addMsg('xml_@fieldname.id@','YourAlertMessage'); }</pre>
==== Submit Logic Validation ====
Use Submit Logic in conjunction with Submit Buttons to Validate a XML worksheet.
==== Special - Browser Script validation ====
You can enter JavaScript and jQuery into XML JavaScript Function input to create specific validations. Use the following syntax when referencing a value in your variables.
var saveFunc=saveXML;
saveXML=function() {
checkdupeval(); }
function checkdupeval() {
var result = 0;
if( a == b)
{
alert ("Please list each population no more than once."); result = 1;
}
}
if(result==0)
saveFunc();
}
</pre>
== Displaying XML Data==
=== Displaying XML Data on an object ===
[[File:xml-readonly.png|The XML displayed in a read only|500px|border]]
=== Access, Display and Format options for XML Data ===
The syntax options for accessing, displaying and formatting the data from the XML fields are detailed below.
<pre>@xml.fieldname.sectionodename.rownodename[#(?criteria="~colunnnodename.nodevalue~" == "matching criteria")~columnnodename.nodevalue~ #]@</pre>
=== Styling XML data for web and print (PDF) ===
[[File:xml-readonly-styled.png|The XML styled at 700 pixels wide in a read only|500px|border]]
==== Styling XML Data for Printing ====
You can print your XML if you are displaying it in a '''Read Only - System Variable'''. Size your your XML to fit within 700 pixels wide (portrait) or 900 pixels wide (landscape) to avoid content cutting off, when a PDF is generated. If you have more than one section and more than a few columns, some of your content may cut off when printed if it is not sized. You will also notice columns between sections do not align. To fix this, we will use CSS in a SmartFolder and amend our '''Read Only - System Variable''', which is displaying the XML information.
==== Using different styles for Print and Web with XML Data ====
You can have one look for your XML when it is onscreen and another when it is in PDF format for printing. To do this, create two '''Read Only - System Variables''' custom fields, create two CSS style sheets in '''SmartFolders''' and reference the desired style sheet in the desired '''Read Only - System Variables'''. Then on the '''Read Only - System Variables''' for viewing on screen for '''SmartFields''' View choose '''Exclude'''. This custom field will no longer be included in PDFs generated using the SmartFields variable. For the other custom field you want to print, choose '''Only display for SmartFields View'''. Now one '''Read Only - System Variables''' will appear on screen and another when the PDF is created, and you can have a separate style sheet to control the look and feel of both.
=== Reporting on XML data ===
Extract XML value in a report using the following syntax in the report builder. This will return one value for static XML sections specific to the row and multiple values for Dynamic XML sections across all rows.
<pre>ExtractValue([this], '/worksheet/sectionnodename/rownodename/columnnodename')</pre>
== XML Data - Appendix ==
=== Field options and settings ===
==== General Settings ====
{{Custom Field ID}}
==== Display ====
{{Display Order}}
==== Options ====
==== Value Storage ====
{{Value Storage}}
=== Example of XML field ===
Here is an example of an XML field with one section (Expenses) 3 static rows (Salaries, Supplies and Total) and 3 columns (Amount, Notes and Date).
<pre><?xml version="1.0" encoding="UTF-8"?>
<worksheet>
<Expenses>
<Salaries>
<Amount>50000</Amount>
<Notes>People I work with</Notes>
<Date>2016-11-30</Date>
</Salaries>
<Supplies>
<Amount>30000</Amount>
<Notes>Things I need</Notes>
<Date>2016-11-30</Date>
</Supplies>
<Total>
<Amount>8000</Amount>
<Notes></Notes>
<Date>2016-11-30</Date>
</Total>
</Expenses>
</worksheet></pre>
{{CustomFieldPageFooter}}
[[Category:XML]]
