Free-Form Modification of Detail Forms

This article contains the following topics:
casm1401
This article contains the following topics:
The topics in this section describe how to perform free-form modification of Detail Forms.
Using JavaScript on Detail Forms
Use WSP to add your own fields to a detail form, or rearrange or change edit characteristics of fields provided on the form by default. However, sometimes you want to modify a form beyond simply adding new fields to a grid. There are a number of a JavaScript functions provided with CA SDM to make it easy to merge your own modifications into a combination detail form and give it any appearance you want. These functions are summarized as follows:
  • You can place any HTML whatsoever prior to the DetailForm() statement or after the endDetail() statement without affecting the operation of the detail form at all.
  • You can use the detailEndTable() function to close the table that lays out detail form elements in a grid. After you have done this task, you can lay out your own HTML in any desired format. In this case, your HTML is inside the detail form, and any form fields within it are submitted to the web engine when the user clicks Save. You can use the detailNextID() function to generate ID fields for your HTML elements that allow them to participate in mouse-less navigation of the detail form. You can see several examples of this technique in the notebook tabs, such as xx_alg_tab.htmpl.
  • You can follow your own HTML with a dtlStartRow macro to restart standard detail form formatting. This starts a second grid, whose fields will not necessarily be aligned with the first. This technique is used in every notebook tab.
  • If you want to insert a custom element at the end of a row, you can use the detailWriteRow() function to write out the contents of a row without closing it. You can see an example of this technique in the code that generates the “24 Hour” button in detail_cr.htmpl and detail_iss.htmpl.
  • If you want to explicitly specify the contents of an element in a row without closing out the table that lays out the grid, you can use the detailRowHdr() function to specify the header text and the detailSetRowData() function to specify the data text. You can see an example of this technique in the code that generates the timer field in detail_cr.htmpl and detail_iss.htmpl.
  • If you provide a function to validate a field's value (normally in an event handler), and want its results reported during browser-side validation (so that an erroneous field is redrawn with a thick red border, and an error message appears in a yellow band at the top of the form), use the function detailReportValidation(). You can see an example of this in the validate_duration() function used to validate the duration fields in xx_candp_tab.htmpl. The validate_duration() function is in the file val_type.js.
  • If you want review the HTML generated for a detail form, you can use functions docWrite() and docWriteln() in place of the standard functions document.write() and document.writeln(). Then if you invoke the function holdHTMLText() anywhere in the <HEAD> section of your form, CA SDM will pop up a debugging form containing a TEXTAREA with all of the HTML generated for the form, which you can review or copy and paste into a validation tool.
While you are composing your modifications, remember that the combination detail form is displayed in both a read-only and an edit view. If your modifications apply specifically to one view or the other, you can test the current view in one of two ways:
  • In JavaScript, the expression _dtl.edit is true in the edit view and false in the read-only view.
  • In either JavaScript or open HTML, the statements:
    <PDM_IF "$prop.form_name_3" == "edit"> </PDM_IF>
(Used only in the edit view)
or
<PDM_IF "$prop.form_name_3" == "ro">
(Used only in the read-only view)
</PDM_IF>
Used to bracket code intended only for the edit or read-only view, respectively.
detailEndTable()
This function closes the HTML table that lays out the detail form elements in a grid. It has no arguments.
You can start a new grid with the dtlStartRow() macro. However, elements in a new grid are not necessarily aligned with elements in a previous grid.
detailNextID( colspan, lastelement )
This function returns a string of the form:
" ID=df_nn_nn TABINDEX=n onFocus=func onBlur=func"
Inserting this string into an HTML element causes the element to follow the conventions of CA SDM mouse-less navigation, including accessibility with the arrow keys and turning pale yellow when focused. The returned string begins with a space and ends with no space.
  • colspan
    Specifies the number of columns in the grid occupied by the element. This argument is optional; it defaults to one if not provided. If omitted, the element is assumed to occupy one column of the grid. This affects arrow key behavior. The
    colspan
    argument can be omitted even if the
    lastelement
    argument is provided.
  • lastelement
    A Boolean value specifying whether the element for which the ID being generated is the last one in its row. If omitted, the element is assumed to be followed by other elements. This affects arrow key behavior.
detailNextLinkID()
This function returns a string of the form:
" ID=dflnk_nn_nn TABINDEX=0 onFocus=func onBlur=func"
Inserting this string into an HTML element defining a link element causes the element to follow the conventions of CA SDM mouse-less navigation, including accessibility with the up arrow key from the base element and turning pale yellow when focused. The returned string begins with a space and ends with no space.
This function takes no arguments.
detailReportValidation( field, has_error, emsg )
This function reports the result of external field validation. If validation is reported to have failed, the field is redrawn with a thick red border and the error message provided is shown in a yellow band at the top of the form. The user is not permitted to save the record until a subsequent call to detailReportValidation() reports the field as error-free.
The detailReportValidation() function is functional only for fields registered for browser-side validation. All fields created with detail form macros are automatically registered for validation. You can register other fields with the detailSetValidateFunction().
  • field
    (Required) Specifies the form element object containing the field. The easiest way to obtain this is to pass this argument to the event handler performing the validation. Another way is to use the standard JavaScript function document.getElementById().
  • has_error
    (Required) A Boolean or integer value specifying whether the field is in error. Setting a field in error prevents the user from saving the record, causes the field to be highlighted with a thick red border, and places the error message supplied as the third argument in a yellow band at the top of the form. Setting a field as not in error reverses these changes.
  • emsg
    A text string specifying the message to display in the yellow band at the top of the detail form when the
    has_error
    flag is set. This argument is required if
    has_error
    is set.
detailSetValidate( hdrtext, is_required, maxsize )
This function specifies that the most recent field created with an ID supplied by detailNextID() is subject to browser-side validation. Validation for required fields and for fields with a maximum size is automatic. Other forms of validation may be provided through JavaScript functions or event handlers calling detailReportValidation().
You should call detailSetValidate() only for form fields you have defined yourself whose ID was created by detailNextID(). The detailSetValidate() function must be called immediately after creating a field that you want validated. It is unnecessary (and will caused unexpected results) to call detailSetValidate() for fields created by detail form macros.
  • hdrtext
    (Required) Specifies a string used to identify the field in error messages.
  • is_required
    (Required) A Boolean or integer value specifying whether the field is required. CA SDM automatically verifies that all required fields are provided whenever the user attempts to save a record.
  • maxsize
    An integer specifying the maximum length of data allowed for the field. CA SDM automatically verifies that all fields with a
    maxsize
    value have a length within limits whenever the user attempts to save a record. This argument is required. To suppress
    maxsize
    validation, specify a value of 0.
detailRowHdr( hdrtext, colspan, is_required )
This function stores text for the header (TH) element of an item in the grid. The text is not actually written to the form until a detailWriteRow() function or dtlStartRow macro is invoked.
  • hdrtext
    Specifies the text in the header element. This argument is required.
  • colspan
    Specifies the number of columns in the grid occupied by the element. This argument is optional; it defaults to one if not provided. If omitted, the element is assumed to occupy one column of the grid. This affects arrow key behavior. The
    colspan
    argument must be provided if the
    is_required
    argument is provided.
  • is_required
    Specifies whether the
    hdrtext
    should be displayed in the style corresponding to a required field. The argument can be a Boolean, a number, or a string. A number or a string is interpreted as false if zero and true otherwise. This argument is optional; if omitted, the
    hdrtext
    is styled as a non-required field.
detailSetRowData( text )
This function stores HTML text for the data (TD) element of an item in the grid. The text is not actually written to the form until a detailWriteRow() function or dtlStartRow macro is invoked. The single argument is the HTML text of the element to be stored.
detailWriteRow()
This function writes the HTML stored for the current row. This creates two HTML table rows, one for the header (TH) elements and one for the data (TD) elements. The function also writes the [assign the value for TD in your book] tag that begins a new data element. The TD tag is automatically closed by the dtlStartRow macro, so it is unnecessary (and incorrect) to provide the [assign the value for TD in your book] tags in HTML text that follows detailWriteRow(). This function has no arguments.