Question:
What can go in the Extended field on the UI Configuration tool?
Answer:
On the UI Configuration tool, you are able to add and edit certain advanced configuration fields. One of those fields is Extended.
The Extended field is a relaxed field into which several options can be placed, sometimes more than one at a time. Several of these options are quite advanced and require an understanding of the Spitfire Lookup and Validation engine which is documented in the Spitfire Developers Primer. Additional assistance with these options may be provided during implementation.
The general form for the contents of this field is
option=value;option2=value2;optionn=valuen;etc.
For example: CSS=NoWrap;Width=30ex;
Important: A semicolon must be used between options and can be used at the end of one option (to maintain good habits) but is not technically required.
The following options can be used in the Extended field.
Note: Except as noted, these options apply only to specific UI elements, such as a text box.
Calc=
- Specifies a .NET Data Expression to display in a grid column. This option only applies to SFDBX grid columns (i.e., not every grid column supports this option), but columns that do can be re-purposed. For example, the ItemSourceNumber column in the Doc Item grid can be re-purposed to display both the Manufacturer and Supplier using ISNULL(Manufacturer+‘<br>‘,‘‘) + ISNULL(Supplier‘‘). The DocItem ItemID column (as for example, on the Submittal Item Register) generally requires this customization. Spec, Para and Revisions is commonly coded as TRIM(ISNULL(Specification,‘‘)) + ‘/‘ + TRIM(ISNULL(Paragraph,‘‘)) + ‘:‘ + CONVERT(ISNULL(RevisionNumber,‘‘),System.String);
CanEditRef=
- Specifies another column that will determine if this column is editable or not. The referenced column must be in the grid table but does not have to be visible. See also CanEditWhen. This option only applies to SFDBX grid columns (see KBA-01512 for a full list).
CanEditWhen=
- Specifies the dynamic editability of this column. This option only applies to SFDBX grid columns (see KBA-01512 for a full list). Options are:
- 0 — the default – Column editability static based on Read Only flag
- 1 — Column is editable only for new, unsaved rows
- 3 — Column is editable if the peer column named in CanEditRef is TRUE (this is the default if only CanEditRef is specified)
- 4 — Column is editable if the peer column named in CanEditRef is not NULL
- 5 — Column is editable if the peer column named in CanEditRef is NULL
CSS=
- Specifies a class name to add to the data field. Some examples:
- clsNumericInput for a numeric input, enabling $ and comma cleanup
- V23+: uiNumericRO, classic: clsTextNumericReadOnly for a read only numeric,
- lClippable to mark a grid cell for text overflow popup. (the first character is a lower case L)
- nowrap to prevent text wrap
- sfShowPointer to display the mouse pointer cursor over the field
- sfTDMergeNext to keep the second field close to a first field on the same row. (For example, the Spec and Para fields would appear as a set if CSS=sfTDMergeNext is entered for Spec)
- sfTDSlideLeftIfEmpty to slide a field (and its label) left on the row if the prior TD cells are empty. Use sfTDMergeNext to combine two fields and sfTDSlideLeftIfEmpty to move a field left.
- sfTRMergeNext to bring the next row adjacent to this field. (For example, the csCustomAmount and Cost Impact fields appear by default on two rows, but on the same row if CSS=sfTRMergeNext is entered for csCustomAmount)
- uiAllowLateEdit to re-enable entry on a Note field on a document that is pending or closed. User must have the Internal Staff role capability. Use with caution. [V2020+] also allows entry on an Item field with the same conditions.
- uiAnyDate to allow any date without a range check; Currently applies to document date tab.
- uiAnyStatus to bypass a status check. Use with caution. Example: allow a reference to an in process commitment where a committed status is usually required. Do not use this feature on payment requests!
- uiBlankIfZero to hide the value if it is numeric zero
- uiByCapability to enable tan background on a field. This class is automatically applied if the Capability feature is used.
- [V2020+] uiCETabSkip marks the field as not a target of a tab sequence (so that it is skipped when a user tabs through fields).
- [V2020+] uiColFoot marks a grid column for a dynamic footer value. See also the following:
- uiDistinctCnt places the number of distinct values in the footer.
- uiSumAmt places the sum of the amounts in the footer. Hint: also set the Display Format column to the desired format (for example, C2 or N0).
- uiSumQty places the sum of the units in the footer.
- uiInstantAC to enable immediate auto complete for this field. The field will behave somewhat more like a drop down, offering choices as soon as it receives focus. This is best for fields that will have less than 8 choices. Choices will be refined as characters are typed.
- uiIsRequired to enable red underline on a field while it is empty
- uiNoSpinner to remove the numeric input “spinner” displayed by Chrome and other “webkit” browsers on numeric input fields
- uiSoftRequired to enable gold underline on a field while it is empty
- [V2020+, Classic] uiStoreValue marks an INPUT fields (header or detail parts) for save-as-you-go.
- uiUppercase to covert text entered on the client to uppercase
- uiWithTime to turn a date field into one that allows date and time. Note, some fields may also require a specific format, such as M/d/yyyy HH:mm; and you may need to disable client side validation (ValidationMode=0)
- [V2023+, Power UX]
- Grid Column Widths are dynamically calculated based on the label and the Width attributes, and then responds to the available screen real estate — these dynamic calculations can be tweaked with
- uiFW – “Full”: increases allocation by 100% and sets minimum width to 90% of the calculated width. These columns keep their width even when screen space is limited.
- uiHW – “High”: allocation is increased 70%
- uiKW – “Keep”: no extra space is ever allocated to this column
- uiLW – “Less”: no extra space is ever allocated to this column and its initial allocation is reduced by 40%
- Tab Visibility
- uxShow – to make the tab visible (available) in Power UX
- uxHide – to make the tab hidden (not available) in Power UX
- Grid Column Widths are dynamically calculated based on the label and the Width attributes, and then responds to the available screen real estate — these dynamic calculations can be tweaked with
DataField=
- Specifies the display field for either an SFDBX grid column or simple text box. For a text box, you can specify alias.fieldname. For SFDX grid columns, the new field must be in the same table as the base column. See KBA-01512 for a full list of SFDBX grid columns). For example, the ItemSourceNumber column in the Doc Item grid can be repurposed to display the value in the Manufacturer field. Both fields must be in the same table. As for the SourceDocNo text box, it might be repurposed for any (text) field in the DocHeader or DocRevision aliases. Warning: You cannot use DataField= to have a two columns in the same grid with the same datafield; use Calc= instead.
Note: when using the DataField= option, you often also need the ShowColType=, DV= or Validate= option.
DependsOn=
- [Advanced] Specifies the input to a lookup. The value takes the general form d1,d2,d3; Examples:
- DependsOn==CostingMethod;LookupUsing=CodeLookup;
- Explanation: The CodeLookup requires the name of the code list code set. The name is specified in DependsOn as a literal. The equal sign indicates that the d1 value is a literal.
- DependsOn==Reason,#DocMasterDetail.DocTypeKey (for LookupUsing=SubCodeList)
- DependsOn=#DocMasterDetail.Project,=234D47B9-A189-414E-A072-A4A82A6D850D,#DocMasterDetail.Subcontract;LookupUsing=DocSCRList;
- Explanation: The DocSCRList lookup requires three inputs: a project ID, document type and subcontract number.
- The project ID is obtained from the document header project field. The pound sign prefix indicates that the d1 value is a document data reference in table.field fomat.
- The document type GUID for CCO is specified as a literal. The equal sign indicates the d2 value is a literal.
- The commitment (subcontract) number is obtained from the document header using a field reference (pound sign prefix)
- Explanation: The DocSCRList lookup requires three inputs: a project ID, document type and subcontract number.
- DependsOn=cboSourceDocType,#DocMasterDetail.DocMasterKey,txtProjectLookup,=M
- This lookup depends on 4 values (the max):
- cboSourceDocType is the HTML ID of a drop down – its value is passed to the lookup
- The document key
- txtProjectLookup is the HTML ID of a text box, its value is passed to the lookup
- a literal M
- This lookup depends on 4 values (the max):
- DependsOn==CostingMethod;LookupUsing=CodeLookup;
DV=
- Specifies the display result rule for a grid column. Result rules are defined in xsfLookupResult. See the Spitfire Developers Primer. Some fields support DV=0 to disable the description next to or underneath the main data. Often combined with ShowColType=DBLookup;
Format=
- [this option now has its own column in the UI Configuration tool] Specifies a format, such as F2 or C2. Many of the standard .NET format specifications are feasible, although practical choices are limited for INPUT fields (for example F2 works for INPUT, but C2 does not). sfPMS also supports K followed by a mask: lower case x characters are replaced by a source character. For example Kxx-xxxxxxx would be a mask for a Tax ID number. Other examples:
- For US dates: M/d/yyyy
- For US Date and time: M/d/yyyy HH:mm
HTML=
- Specify either 0 or 1; Only applies to HTML Edit boxes. See also MLRows=1 (below).
MemberOf=
- Specifies the role name for which a tab should be visible. Applies only to tabs. Consider ‘Customization by Capability‘ instead (See KBA-01534.)
MLHeight=
- Specifies a height for a multi-line text box, such as the Description field. Specify a value with units, such as 120px.
MLRows=
- Specifies a height for a multi-line text box in rows. Do not use both MLHeight and MLRows on the same item. MLRows=1 implies HTML editing should be disabled.
NullFormat=
- Specifies a format for what is displayed if the value is null.
Overlay=
- Valid only for text boxes (mostly found in detail panels). This text is displayed as an overlay (or placeholder) on top of empty input fields that do not currently have focus. Examples: City and Zip fields. For a segment masked field, use Overlay=1 to display the segment name as the overlay. Of specific note: HTML edit boxes are not text boxes and therefore do not support this feature.
QE=
- [Deprecated] Specifies that the grid column allows editing (through Quick Edit). Default is usually 0. Avoid this feature in future deployments, it has been replace by the click-to-edit UI. Quick Edit is also disallowed if the grid column is participating in the grid sort. This option only applies to SFDBX grid columns (see KBA-01512 for a full list).
QHelpURL=
- Specifies a URL (http://support.spitfirepm.com/kba-01336/ or http://yoursite.yourdomain.com/yourpage.htm)
ROIfUnits=
- Valid only for DocItem grid columns. Specifies that the column should be read-only if units have been provided, forcing the user to use the unit*rate calculation; Valid value is ROIfUnits=1; omit for standard behavior.
ShowColType=
- Valid only for SFDBX grid columns, changes the display mode of the column when it is read only. Common values:
ShownWhen=
- For DocItem sfDBX grid columns: Controls when visible columns are actually shown. Valid values are
- 1= Show only in grid view (not in Item detail view).
- 3= Show only in grid view AND when document is Published, Approved, or Closed (not In Process).
- 5= Show only in grid view AND when document is Approved, or Closed (not In Process or Pending).
- For DocItem icons: Controls when icon is visible. (Currently only applies to Comment Link icon) Valid values are
- 1= Show only in grid view.
- 2= Show only in detail view.
- 3= Show in both grid and detail views
SortHint=
- Valid only for grid columns, suggests a sort for the grid. You can provide a comma-separated list of fields. If you specify multiple SortHints for the same part and context, the last one processed applies. Internal logic and user actions can override your hint, for example, Attachments and Items have specific sequencing logic that will override the SortHint. If you change the sort for one context, you may need to assert the default sort for other contexts.
ValidateAgainst=
- Specifies the validation result rule for a text box with a lookup. Result rules are defined in xsfLookupResult. See the Spitfire Developers Primer.
ValidateCodeset=
- Specifies the code set name for a drop down
ValidateTextAgainst=
- Validates specified text to find an actual value. Some textboxes with a lookup display a descriptive text value, but the actual internal (key) value is not meaningful to the user. The most prevalent example throughout the system is Contact names. Such lookups require two validation rules: ValidateAgainst validates the internal key value and ValidateTextAgainst recognizes text and finds the actual value.
ValidationMax=
ValidationMin=
- Specifies the minimum or maximum for the grid column. Currently only applies to QuantityCol in the Doc Item grid, and then only when the line item is not related to a Commitment. (Commitments provide a much more dynamic and context appropriate value range.)
ValidationMode=
- Specifies the dynamic validation for this column. This option only applies to SFDBX grid columns (see KBA-01512 for a full list). Options are:
- 0 — the default – no validation
- 1 — Boolean (0,1,T,F)
- 2 — Numeric
- 3 — Any Date (implicit date range validation may also apply); see also CSS=uiAnyDate (above)
- 4 — Future Date (implicit date range validation may also apply)
- 5 — Positive Numeric
- 6 — Integer
- 7 — Positive Integer
- 8 — Until Date (any date up to including today) (implicit date range validation may also apply)
- 16 – “Required”, meaning must not be empty
- Note for the dates: if the date column is the “finish” of a start+finish pair, then a range check is also implied so that the finish date must be greater than the start date (further limited to any, future, or prior as specified above). The implied range check can be circumvented
- if the start column is not immediately to the left of the finish date, or
- by adding CSS=uiAnyDate in V2019 or later.
Width=
- Specifies the UI field width. The width specifier must be a valid value for the HTML width attribute. For example, the value can be in forms such as 25%, 20em and 15ex. Spitfire recommends using ex units because ex provides a reasonable average character width.
Additional Comments:
For more information about the UI Configuration tool, see the Focus on System Administration guide. Some customizations are only allowed on special ‘smart‘, ‘sfDBX‘ grid columns. See KBA-01512 for a full list.
KBA-01336; Last updated: July 4, 2024 at 16:31 pm;
Keywords: AuxData;LookupUsing;lookup using;lookup name; change field size