Smartstaff
34
edits
Changes
no edit summary
=OverviewGeneral Description=
[[File:xmlSample.png|thumb|none|500px|Example field configured as a budget sheet.]]
By default, the data for this field is stored in the structured XML (Extensible Markup Language) format. However, you also have the option to instead use this field as a presentation layer for lists of sub-activity records. For example, you may 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 '''[[Custom Field Type: Special - In-Line Basic Data GridTable|Special - In-Line Basic Data GridTable]].'''
{| class="wikitable"
||Hours
|}
==Field Options==
All common options:<br />
[[Custom Fields - General Information #General_Settings|General Settings]]<br />
[[Custom Fields - General Information #Role Field Permissions and Status Field Permissions|Permissions & Availability]]<br />
[[Custom Fields - General Information #Classic Options|Classic Options]]<br />
For further information, please refer to [[Custom Fields – General Information]].<br /><br />
Options listed below are specific to this particular field type.<br />
{{XSL Template}}
{{XML Tag Mapping}}
{{XML Javascript Function}}
{{Show View XML Button}}
{{Show Upload Button}}
{{Show Up/Down Button}}
{{Show Clear Button}}
{{Custom Field Ids}}
=Configuration - Essentials=
==Creating the field==
Typically XML Advanced Data table custom fields are created for UTA level 1, 2 or 3, (e.g. a grant application) or they are created for organizations. To create the field:
# Navigate to the desired settings area where you want to create a worksheet (e.g. the UTA level 1).
# Click the '''New Field''' (+) button.
# For Field Type select '''Special - XML Advanced DataTable'''.# Enter a '''Field Name''' and , '''Caption''' then '''Save'''.
# Use the '''Section Builder''' button to begin process of creating the XML tables.
# Use the '''Custom Field''' button to navigate back from the Section Builder to the Field settings to configure the display of tables.
==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 XMLmodify other parameters.
[[File:xml-sectionbuilder1.png|thumb|none|500px|The section builder.]]
# 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(e.g. Item, Amount, Date).# Define a '''Display Name''' for the first column of each row (e.g. Salaries, Equipment, Other).# Within each of the column headers you can define a '''Format''' for the column (e.g. plain textText, currencyCurrency, dateDate). For numeric formats the Number format option you may also specify a precision.# When you are done click the '''Build button'''. Note: # When you choose the format '''Currency''' in a column header, make sure you specify the column alignment as '''Right Align'''. This way it will be easy for the user to avoid confusion it compare the values. This step is recommended also required if you plan to export this data to PDF for printing.# You must use unique node names of sections, rows, and columns within the this field.
==Create a Table with a Dynamic Number of Rows==
* '''Maximum Number of Rows''': Set a maximum limit to the number of 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 user. A default message is displayed if left blankthis input is empty.
Setting the Number of Rows to 0 also exposes the following configuration options for each column header within the Cell Details tab:
* '''Has Total''': Display the total sum of a the 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'.
==Configure the Display of Tables==
The presentation of the XML Data custom field is configured in the general settings page '''General Settings''' tab of the field. This is defined in the XSL Template (Extensible Style Sheet Language) optioninputn. The XSL Template includes a sample template optionlink. Once you have inserted sample template you will need to specify which sections should appear and where they should appear.
[[File:xml-xsl.png|thumb|none|500px|The XSL template and configuration.]]
# While editing the custom field locate the '''XSL Template''' option link and insert the '''Sample Template'''.# Locate the marker below marker.
<pre><!---- Insert section variable here ----></pre>
# Below the this marker, insert variable references to the each section with the following syntax (e.g. @section.Expenses@) in the order in which you wish the sections to appear. Note: # Make sure you are using the section node name '''Section Node Name''' and not the '''Section Name'''# '''Section Node Name''' is case sensitiveExample if your '''Section Node Name''' is '''Expenses''' than @section.Expenses@ will work but @section.expenses@ will not because it has a lower case '''e'''.
@section.''SectionNodeName''@
=Configuration - Advanced=
==Creating formulas (calculations) in XML cells==
[[File:xml-formula.png|500px|border|Adding a formula]]
In the section builder you declare the formatting such as currency or numeric for specific columns as well as settings like choose the precision. If you are collecting You can also do calculations on numeric or and currency data you will likely want to do calculations on this information found within your XML (e.g. to sum the contents of column one, over two rows, enter '''=[1,1]+[2,1]''').
==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.
# Click the desired '''Section'''to edit it.
# Click the desired '''Cell'''.
# Under '''Cell Properties''' enter your Enter the desired formula into the '''Content''' input.
# Click '''Build'''.
|}
So if you wanted to add the values of row 1 and 2 together in column 1 you would enter '''=[1,1]+[2,1]'''. To minimize divide by zero errors, you can first check if the denominator is 0 (and set value to 0) by using the following syntax: <pre>=(ssParseNum([1,3])==0 ? 0 : ([1,2]/[1,3])*100)</pre> ==Adding a formula to a XML cell (working with data in the different sections)==
Refer to cells in different sections using this syntax
If you need want to display data in the head of a section (row 0) from another section you can use the following:
'''@xml.customfieldname.sectionnodename.rownodename.columnnodename@''' ==Validate XML values when saving the worksheet==
Clicking on a cell inside the section builder will present you with the cell properties. There are two cell properties used for the validation of cells when the xml worksheet is saved.
<pre>parseInt([this])>0</pre>
Message: Please provide a numeric value greater than 0.
* Value entered in one cell cannot be more than 20% above or below the value in another cell
<pre>(ssParseNum([this])>=(ssParseNum([1,4])*(0.80)) && ssParseNum([this])<=(ssParseNum([1,4])*1.20))</pre>
Message: Value entered in one cell cannot be more than 20% above or below the value in another cell
==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).
When creating validation for an XML this custom field use the '''Appear Mandatory''' option. Appear mandatory does not enforce the validation but will make the field look mandatory (add it adds the asterisk and or color) just like the mandatory option. Once you have checked '''Appear Mandatory''', validate the XML worksheet this field using one of the following validation methods, when the record is saved.
===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.
Validate an XML a table node is not empty and display a message.
<pre>if("@level1.xml.fieldname.sectionnodename.rownodename.columnnodename.nodevalue@"=="")
===Submit Logic Validation===
Use Submit Logic in conjunction with Submit Buttons to Validate a XML worksheet.
Check an XML a node in not blank when saving the XML worksheet.
<pre>"@level1.xml.fieldname.sectionnodename.rownodename.columnnodename.nodevalue@"!=""</pre>
</pre>
The following function allows you to check for an already selected value from an existing row when using dynamic rows on multiple sections:
<pre>var saveFunc=saveXML;
saveXML=function() {
if (checkdupeval_Section1() == 0 && checkdupeval_Section2() == 0 && checkdupeval_Section3() == 0) {
saveFunc();
}
}
function checkdupeval_Section1() {
var result = 0;
var numOfRows = document.getElementsByName('16580_row_COUNTY'); // REPLACE '16580_row_COUNTY' AND '16580_row_COUNTY_' WITH SPECIFIC XML sectionid_rownodename_columnnodename for Section 1
var ctr=1;
for (ctr=1;ctr<numOfRows.length;ctr++)
{
var field1='16580_row_COUNTY_'+ctr;
var lastfield='16580_row_COUNTY_'+numOfRows.length;
var a = document.getElementById(field1).value;
var b = document.getElementById(lastfield).value;
if( a == b)
{
alert ("Please list each option no more than once for Section 1.");
result = 1;
}
}
return result;
}
function checkdupeval_Section2() {
var result = 0;
var numOfRows = document.getElementsByName('16581_row_COUNTY'); // REPLACE '16581_row_COUNTY' AND '16581_row_COUNTY_' WITH SPECIFIC XML sectionid_rownodename_columnnodename for Section 2
var ctr=1;
for (ctr=1;ctr<numOfRows.length;ctr++)
{
var field1='16581_row_COUNTY_'+ctr;
var lastfield='16581_row_COUNTY_'+numOfRows.length;
var a = document.getElementById(field1).value;
var b = document.getElementById(lastfield).value;
if( a == b)
{
alert ("Please list each option no more than once for Section 2.");
result = 1;
}
}
return result;
}
function checkdupeval_Section3() {
var result = 0;
var numOfRows = document.getElementsByName('16582_row_COUNTY'); // REPLACE '16582_row_COUNTY' AND '16582_row_COUNTY_' WITH SPECIFIC XML sectionid_rownodename_columnnodename for Section 3
var ctr=1;
for (ctr=1;ctr<numOfRows.length;ctr++)
{
var field1='16582_row_COUNTY_'+ctr;
var lastfield='16582_row_COUNTY_'+numOfRows.length;
var a = document.getElementById(field1).value;
var b = document.getElementById(lastfield).value;
if( a == b)
{
alert ("Please list each option no more than once for Section 3.");
result = 1;
}
}
return result;
}
</pre>
The following allows you to hide the Add Row button for a specific section when the record is in a specific status:
<pre>function onloadfunc() {
<!--@sslogic("@statusid@" = "XXXXX" )--> //Replace XXXXX with the ID of the status in which the button should be hidden
$('#addrowbutton_@section.SECTION.id@').hide(); //Replace SECTION with the section name
<!--@end-->
}
</pre>
The following allows you to hide the Delete Row button:
<pre>function onloadfunc() {
$("a[name='@section.SECTION.id@_deletebutton']").remove(); //Replace SECTION with the section name
}
</pre>
==Managing Level 2 / 3 Activities with an XML a Section==System administrators can configure XML fields this field to add, modify or delete {{l2}} records on a {{l1}} entity or {{l3}} records on a {{l2}} entity.
In the [[XML '''Section Builder]]''', when the ''Number of Rows'' for a Section is set to '0', the ''Enable Mapping'' option will be shown.
[[Image:XMLEnableMapping2017.png|link=|800px|border]]
When '''Enable Mapping''' is selected, you can choose one type of activities to be referenced by the XML this field.
The '''Activity Status Filter''' setting allows you to filter the activities to be referenced by status.
The '''Additional Filter''' setting allows you to select custom fields and associated values. These are used to filter the existing activities that will be listed within the XMLthis field. The custom fields used have to be those fields with pre-defined options (e.g. [[Custom Field TypeCustom_Field_Type: _Select_One_-_Dropdown_List|Select One – Combo Box|Combo box- Dropdown List]], and [[Custom Field TypeCustom_Field_Type: _Select_Many_–_Check_Boxes|Select Many – Check Boxes|Check Boxes]], [[Custom Field Type: Dynamic Data – Dynamic Control Field|Dynamic Control]], Ajax Lookup).
[[Image:XMLEnableMappingFilter2017.png|link=|650px|border]]
When building your section, you will need to map the fields on the {{l2}}s that will be referenced by the XML section.
For each Section column, enter the field name from the Level 2 type that you have selected from the '''Activity Type''' dropdown in the '''Map Field''' section:
[[Image:MappingL2Fields2017.png|link=|800px|border]]
The syntax for the '''Map Field''' section is:
* for [[custom fields]], simply the field name (i.e., '''Fund Name''');* for [[standard fieldStandard_Field|Standard Field]]s, use the prefix '''sf_''' and then the system name for the standard field (i.e., '''sf_status'''). : ''see [[Standard Level 2 Field List]] article for a list of system names for {{l2}} standard fields.
see [[Standard Level 2 Field List]] article for a list of system names for {{l2}} standard fields.
If the Standard or Custom field has a limited number of pre-defined options then these need to be defined in the Content section of the cell properties.
When this section is added to the XSL Template of your XML field, the list of {{l2}} activities will be displayed when the XML worksheet is opened. Level 2s can be added, deleted and modified directly from the {{l1}} XML Advanced Data Table field.
=Displaying XML Data=
==Displaying XML Advanced Data Table data on an object==
[[File:xml-readonly.png|500px|border|The XML displayed in a read only]]
The XML Advanced Data Table custom field opens can open in a new or modal window and . The '''Open in Modal Window''' option is recommended. You can toggle this on under '''Document Options'''. By default the information entered into this field type is hidden until the user must click clicks a button . But there is a way to launch the modal window and see the information entered. You can however, display the information entered into a '''Special - XML Data''' custom this field on your object, such as a grant application, without requiring the user to click a button and launch the modal window. To do this we use Use the '''Read Only – System Display - Text and Variables''' custom fieldto display the content of the Advanced Data Table on the object. The same syntax can be used elsewhere in the system (e.g. include Display Only - Web Page View, Special MS Word Merge, visibility conditions, etc.) when referencing the xml this field's values.
# Go to the desired location where you want to create the custom field.
# Click the '''New Field''' (+) button in the action bar.
# For '''Field Type''' select '''Read Only – System Display - Text and Variables'''.
# Enter a '''Field Name'''.
# For '''Variables''' enter '''@xml.''CustomFieldName''.''SectionNodeName''.html@''' (replace the '''CustomFieldName ''' and '''SectionNodeName ''' with the actual names from your XMLexample '''@xml.Budget.Expenses.html@''').
# Scroll Down to the '''Display''' section.
# For '''Caption''' select '''Hide Caption''' (we recommended that you hide the caption for the display so that you can utilize the full screen width).
# Click '''Save'''.
# Navigate back to the XML custom Advanced Data Table field and click '''Save''' ('''Display Fields Refreshed Upon Edit''' will be updated with this updates the linkage and ensures when data is entered into the custom field ID of worksheet the Read Only we just created. From now data displayed on when a user edits the XML the read only object will be also get automatically updated. If you miss this step it , information entered into the Advanced Data Table will only refresh in the Display - Text and Variables field when the object is saved).
Note: you may want to create two '''Display - Text and Variables''' custom fields for each '''Advanced Data Table''' custom field. One that you will use for printing and one for displaying on the object.
==Access, Display and Format options for XML Data==The syntax options for accessing, displaying and formatting the data from the XML fields are Advanced Data Table field is detailed below.
<pre><!--@sscalculation(format("@xml.fieldname.sectionnodename.rownodename.columnodename.nodevalue@",2))--></pre>
* Extract a filtered row count from a '''dynamic''' XML section.
<pre><!--@sscalculation(@xml.XML Field.People.Person[#(?criteria="~type.nodevalue~" == "A") 1+#]@ 0)--></pre>
* Extract a percentage value and '''format with two decimal places'''. If pulled from a '''dynamic''' XML section then you will see multiple values.
* Return multiple rows for XML with dynamic sections in a custom html table.
<pre>@xml.fieldname.sectionnodename.rownodename[# #]@</pre>
{|border="1"
|-
||~columnodename.nodevalue~
* Return a single value in the total row of a Dynamic XML.
<pre>@xml.fieldname.sectionnodename.rownodename.total.columnnodename.nodevalue@</pre> ==Styling XML data for web and print (PDF)==[[File:xml-readonly-styled.png|500px|border|The XML styled at 700 pixels wide in a read only]] If you enable the '''Section Builder''' and '''Apply Default Styles''' is enabled in each section of your XML custom field, the field will be automatically styled. If you have manually added CSS classes to your cells, you will need to remove those classes and check '''Apply Default Styles''' again and then click '''Build''' on your XML in section builder. Administrators with CSS knowledge can modify the look and feel of their XMLs (e.g. make columns wider or thinner). To modify the look and feel of your XML, create an external CSS style sheet, upload the style sheet to a SmartFolder, add classes to the elements in your XML, and add a link to the style sheet in your '''Special - XML Data''' or '''Read Only - System Variable''' custom fields.
==Styling Advanced Data Table for web, print and conversion to PDF==
[[File:xml-readonly-styled.png|500px|border|The worksheet styled at 700 pixels wide in a Display Text and Variables custom field]]
To ensure data entered into an '''Advanced Data Table''' fits on screen and will converted to a PDF without having data cut off, administrators need to upload two external CSS style sheet to a SmartFolder, reference it on the '''Advanced Data Table''' and the '''Display Text and Variables''' fields as well as add some code to both of these fields.
# Navigate to the desired '''Display Text and Variables'''.
# Paste the contents of '''display.html''' into the '''Content''' section of the field.
# update the href to point to the relative path to the file called '''xml-print.css''' that you uploaded to the SmartFolders.
# Add your desired variable example '''@xml.Budget.Expenses.html@''' inside the div with the '''class="xml8col"'''.
# Change the '''8''' in '''class="xml8col"''' to the number of columns in your section. Note you must have 8 or less columns.
# If you want this table to be displayed wider for landscape printing add the word '''landscape''' in the class example '''class="xml8col landscape"'''.
# Save your custom field
You now have a version of your Advanced Data Table that you can display on the object such as the level 1 application and you can convert this to a PDF using the Web Page View custom field.
==Reporting on XML Advanced Data Table data==Extract XML value values 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>
{{CustomFieldPageFooter}}
[[Category:XML]]
