Related issues are displayed with layouts that use the naming convention RELATED_XXXXX. To create a new related issue layout, you first create a layout type where the name begins with RELATED_ Note that the usage of related issue displays must be Report. In the normal way for layouts, these may be inherited by any Business Area or Project which will use them. These are used to display the related records within add, edit and report layouts. The layout contains the fields you want to display when viewing the related issues. There is a single default related issue display layout within a new ExtraView installation, named RELATED_ISSUE_DISPLAY. The default fields on this layout are VIEW_BUTTON, QUICKEDIT_BUTTON, EDIT_BUTTON, RELATIONSHIP_GROUP_REMOVE_BTN, ID, STATUS, ASSIGNED_TO and SHORT_DESCR. You may change any of these fields to meet your requirements.
When you configure a related issue display layout to allow the creation of new related issues, you are able to place a button on a header to the display. This button may have any text, and when pressed will open a modal window where you can add the issue you are creating into the relationship with the current issue on the screen. On reports all related issues are displayed, allowing you to print the results clearly.
On add and edit screens, the related issues are placed within a scroll box whose dimensions are controlled by the layout cell attributes named SIZE and HEIGHT. If you do not provide a layout cell attribute for SIZE, then the default is 125 characters. Within the layout, you can also use a SIZE layout cell attribute on the individual fields to control their width. If you do not use a SIZE attribute on individual fields, then the width of each field floats and the user's browser will decide on the optimal width. The height of the related issue display is calculated automatically, to display all the records in the group unless a HEIGHT layout cell attribute is added to the related issue display, to provide a maximum height.
You can fix the position of the column titles of the related issue display with the layout cell attribute named RID FIX TITLES. When you set this attribute it is not recommended that you use the SIZE attribute on fields within the related issue display layout.
Some sample layouts rendered on Add and Edit screens are:
Related issues on a report
Editing related issues on an add or edit screen
Adding new related issues on an add or edit screen
The modal popup to add a related issue
You may create any number of additional related issue display layouts, but you must begin the name of the layouts you create with RELATED_. For example, as well as RELATED_ISSUE_DISPLAY, and as an example, you may create another related issue layout named RELATED_SUPPLIERS. All the layouts to be used as related issue displays must be created with a display type of Report, even if they are to be embedded within an Add or Edit layout. Once you have created the layout type, you then include the layout on the Add, Edit or Detailed Report layouts.
For the above example, you would include LAYOUT.RELATED_SUPPLIERS on the layout. When you create a related issue layout, a new field is created automatically in the data dictionary, with the same name as your layout. In our example, the field RELATED_SUPPLIERS is created. The field has the usual PR_ADD_PROBLEM and PR_RESOLUTION permission keys, and these control visibility to the the related issue display layout on the add and edit layouts for the different roles in your installation.
The field RELATIONSHIP_GROUP_REMOVE_BTN is an inbuilt field with special treatment. It is defined in the data dictionary with a type of LABEL and a display type of BUTTON. Although it is placed on RELATED_ISSUE_DISPLAY layouts, it will only appear when the layout is rendered within an Add or Edit screen. It is ignored on report layouts and on the POST_EDIT_UPDATE layout. There is a security permission key named PR_RESOLUTION.RELATIONSHIP_GROUP_REMOVE_BTN to control the appearance of the Remove? checkboxes on the Add and Edit screens. Its function is to allow the end user to remove a related issue from the relationship group. The user may check any number of related issues and the checked issues will be removed from the relationship when the current issue is updated. Removing an issue from a relationship does not delete the issue.
As stated above, related issue display layouts are designed to be embedded within add, edit, report and other layouts which are then embedded within add, edit and report layouts. This screenshot shows a related issue display layout embedded within an edit layout:
Over and above the standard layout cell attributes that can be applied to all cells on layouts, the following attributes allow configuration of embedded related issue display layouts.
Cell Attribute | Purpose |
BUTTON ACTION |
The RID BUTTON ACTION attribute is applied as a cell attribute to the RID PREHEADER ADD BUTTON. The action defines what happens when the user presses the add button. This attribute is applied directly to the field's global attributes, defined within the data dictionary, as opposed to being set as a layout cell attribute on the related issue display layout.
Note that you may define more than one BUTTON_ACTION on a single related issue display. |
DRILLDOWN | This attribute should only be applied to a field that contains the ID of the related issue. You can choose to set the drilldown to either a value of View or Edit according to the type of drilldown window you wish to open |
HEIGHT | This defines the maximum height of the related issue display when it is rendered within an add or edit layout. The height is input in rows, where each row is estimated to be 20 pixels. If the height required to render the issues is less than this value, then the related issue display is resized to only take the height required. If the height required is more than this value, a vertical scroll bar is placed on the related issue display. The titles to the fields are always fixed in position, so that when the user scrolls the list of related issues, the titles remain visible.
The setting has no effect on reports where the entire contents of the related issue display will be rendered. |
RID ACT ON FIELD CHANGE | This attribute is not applied to a relationship layout, but is applied to the field (the RID LINK FIELD NAME above) that is used to link the result set from a search to a relationship issue display. When this attribute is present on the RID LINK FIELD NAME, along with an HTML modifier to trigger the action, a related issue display is refreshed, creating links from each issue ID within the RID LINK FIELD NAME, and displaying these issues in the related issue display. A full example of the use of this feature is provided in Example 4 |
RID FILTERS |
This cell attribute allows the administrator to specify a set of filters to apply to the selection of the related issues to display. This filter is applied to only the related issue records so the user will only see a subset of the related issues. For example, this screenshot shows the administrator about to select values for filters for the Business Area and Status fields: Note that beyond the selection of specific values to use for filters, there are several other possibilities:
|
RID FIX TITLES | This attribute may only be set on Related Issue Display layouts within Add, Edit layouts, or sublayouts of these. When this attribute is used in conjunction with the HEIGHT attribute, and a scroll bar appears after issues have been added, the title to the Related Issue Display is fixed as the user scrolls.
It is not recommended that you place SIZE layout cell attributes on the fields contained within the Related Issue Display layout when you use this attribute. Likewise, it is not recommended that you use this option if you expect that the user will see text that wraps within the Related Issue Display. The best results are obtained when the browser sizes all the columns and column titles. |
RID GROUP REFERENCE FIELD | The default for this attribute is the ID field. This attribute may be set to provide a different field for the relationship to be formed between the issues. The field must exist on both the layouts that are being related |
RID LINK FIELD NAME | This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. RID LINK FIELD NAME must be a field with a display type of text field or text area and the field is typically hidden within the add or edit layout and is used to transition the list of issued from the search results into the list of issues to be related. The list is a series of issue ID values, delimited by semi-colons. If the RID SINGLE SELECT attribute in this table is set, then there can only ever be a single issue ID in the list. Text fields are capable of storing 255 characters. The link field stores the ID's of all issues selected within the results, plus an extra character as a separator between each ID. They therefore store approximately 40 - 60 ID's. If you are likely to link more than this number of issues, make sure the RID LINK FIELD NAME has a display type of text area. These are highly scalable for this purpose.
Linking a Single Result to Populate Fields within the Current IssueIf you are using the RID LINK FIELD NAME to link the search results to a single issue and you then want to take fields within that issue and place their values within the current issue, you are likely to also configure a link and a refresh business rule to retrieve the field values you require from the search result. See Example 3. Linking Multiple Search Results to Populate a Related Issue DisplayIf you are using the RID LINK FIELD NAME to link the search results to multiple issues that you want to relate to the current issue, and place these issues within a related issue display on the current layout, you are likely to also configure RID LINK FIELD NAME with these attributes:
See Example 4 for details on how to configure this. |
RID ONCLICK_JS | RID ONCLICK_JS is the JavaScript that is executed when the INCLUDE ADD BUTTON button is clicked. For most purposes, the script that is executed is created by the RID BUTTON ACTION cell attribute and you do not require to use the RID ONCLICK_JS attribute. The RID ONCLICK_JS attribute is provided for advanced configurations where the administrator wants to create JavaScript that goes beyond the capability of the RID BUTTON ACTION attribute. You must not configure both the RID BUTTON ACTION and the RID ONCLICK_JS attributes on the same button, as they will conflict with each other. The JavaScript for RID ONCLICK_JS should be carefully constructed, and there may be differences when wanting to use the JavaScript to initiate a popup to add a new issue when on the add and on the edit screens. If you want to add related issues on both the add and edit screens, you may need to configure a different INCLUDE ADD BUTTON in the data dictionary for each screen, each with the appropriate RID ONCLICK_JS value. It is possible to configure and place multiple buttons to add different types of issues on a single related issue display.
Basic SyntaxSubstitutable values are possible in this string value. To create a modal popup window the basic JavaScript you use will be:
Note the two substitutable variables SESSION_ID and LAYOUT_TYPE_ID. They must be surrounded by double underlines. This provides the mechanism for ExtraView to substitute the variable at runtime. You set a value of YES or NO to the add_confirm_page parameter, depending on whether you want to display or suppress the verification layout or the ADD_CONFIRMATION layout that is typically shown to users after submitting a new issue. If you set NO, then the verification screen is never shown. There is a built-in method that generates the necessary relationship group parameters for the ADD operation. These are needed to force the insertion of the child issue into the correct Relationship Issue Display relationship group using the relation type of the Related Issue Display. This is rgParameters() and it is in scope from the button when the button is inserted into the header of the Related Issue Display. Updating and Refreshing the Underlying IssueThere are use cases where you might want to update and refresh the parent Add or Edit screen, after you add a child issue. For example, while adding a child issue, Business Rules might execute that update the parent issue. If you want this behavior, there is an UPDATE_MAIN parameter. The workflow might be to go from an Add or Edit screen, add a child record in a modal popup window, submit the child issue within the modal popup (this executes Business Rules that update the parent issue), then close the modal popup and finally redisplay the updated parent issue, you will include the UPDATE_MAIN parameter as follows: doEditAEActions(window.parent.extraview_app_home_url , '__SESSION_ID__',
new Array('UPDATE_MAIN','POPUP_MODAL_ADD', 'add_confirm_page=NO &p_rg_relate_this_to=' + getValueFromParent('p_id') + rgParameters(), 'REFRESH_ID', getValueFromParent('p_id'))); Note that you do not require the RELATIONSHIP_GROUP_REFRESH and accompanying LAYOUT_TYPE_ID parameters, as the REFRESH_ID takes care of refreshing the entire parent issue. If this is executed from an Add screen, the parent issue is displayed within an Edit screen, as the underlying Business Rules submitted the parent issue to the database, thus meaning it is no longer in the add state, but it is now in a state where it can be updated. The p_rg_relate_this_to parameter and its value are used on the Add screen to identify the parent issue to which you want to relate the child issue you are adding, when you are including the UPDATE_MAIN parameter. It has no effect otherwise on Add screens, or Edit screens and may be omitted in these cases. Setting Additional Parameters to Push Values from the Parent to the New IssueOther parameters may be added to the array value immediately following the POPUP_MODAL_ADD entry. An example is to set the Business Area and Project of the issue to be added. To accomplish this, you will need to know the AREA_ID and PROJECT_ID where the issue is to be added. These can be found on the administration screens for these items. With rgParameters(), an example becomes: doEditAEActions(window.parent.extraview_app_home_url, '__SESSION_ID__',
new Array('POPUP_MODAL_ADD', 'p_area=1&p_project=5&add_confirm_page=NO &p_rg_relate_this_to=' + getValueFromParent('p_id') + rgParameters(), 'RELATIONSHIP_GROUP_REFRESH', '__LAYOUT_TYPE_ID__' )); Note that the values for the p_area and the p_project parameters must correspond to the AREA_ID and PROJECT_ID into which you will add the related issue. These values can be seen on the list maintenance screens for the Business Area and the Project. Another possibility is that you might want to pass the values of one or more fields from the parent issue to the child issue you are creating. To achieve this, you may use either the pushDownFields('p_fld1;p_fld2;p_fld3;...') function to pass several fields at once or use the getValueFromParent() function to pass individual fields. For example, let's say that you want to pass the FIRST_NAME and LAST_NAME fields from the parent to the child. The string then becomes either: doEditAEActions(window.parent.extraview_app_home_url , '__SESSION_ID__',
new Array('POPUP_MODAL_ADD', 'p_area=1&p_project=5 &p_rg_relate_this_to=' + getValueFromParent('p_id') + pushDownFields('p_first_name;p_last_name') + '&add_confirm_page=NO' + rgParameters(), 'RELATIONSHIP_GROUP_REFRESH', '__LAYOUT_TYPE_ID__' )); or using individual parameters:
Note that if a field name that you pass within the pushDownFields() or the getValueFromParent() function does not exist, it will be ignored when the user presses the button to add the issue, and no error will be generated. This can be used to advantage in configurations where you want to use a single button for multiple purposes on different forms. Opening the Modal Popup Window in Edit ModeThere is a feature within ExtraView that allows the user to open up a new issue in Edit mode, as opposed to the Add mode. This configuration assigns an ID and / or an ALT_ID and saves the initial issue within the database before then placing the user within Edit mode on the screen. This can be configured within the modal popup window, by altering the Repeating Rows FieldsThe function getValueFromParent may be modified to access repeating row field values. Repeating rows are indexed, beginning with zero, therefore to access the first repeating row, the call will look like: getValueFromParent('p_fieldname', 0)
To access the third repeating row, the call will look like: getValueFromParent('p_fieldname', 2)
Although you may target any repeating row to obtain a value from a field, the value will always be placed in the field on the first row of the child record. The following technique will allow you to get values from successive repeating row fields, and populate these into successive repeating rows within child records: getValueFromParent('p_fieldname', 2); getValueFromParent('p_fieldname', 3)
This example gets the field value from the third repeating row and places the result in the first repeating row child record, and then gets the value in the fourth repeating row field and places its value in the second repeating row child record |
RID PREHEADER | This attribute adds a title to a related issue display header to contain an Add or other buttons. No title is added to the related issue display if this attribute is not defined. There is one special property of this field. If you use the value of TITLE in the value then the description of the related issue display layout will be used as the title in the pre-header. The reason why you might want to do this is solely if you need to provide a localized equivalent for the title in languages other than the base language of your system. The related issue display title may be localized, while layout cell attributes (with the exception of the ALTERNATIVE TITLE) may not be localized.
|
RID PREHEADER ADD BUTTON | This attribute adds a button to the pre-header. This button is used to add new issues to a relationship. The button is a field that must already be created in the data dictionary. The button must be created on the Label tab within the data dictionary and must have a display type of Button. The title to the field will be used as the title to the button when it appears on the pre-header of the related issue display. You may add any number of Add buttons to a single Related Issue Display |
RID PREHEADER REFRESH BUTTON | This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. This places a button onto the related issue display pre-header bar that allows the user to refresh the list of results from the current set of search filters. The button has a default title of Get Filtered Results, but you can optionally provide a value to the attribute which will then appear as the label on the button |
RID PREHEADER SUBMIT BUTTON | This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. This places a button onto the related issue display pre-header bar that allows the user to submit the list of results from the current set of search filters. The button has a default title of Fetch Selected Record(s), but you can optionally provide a value to the attribute which will then appear as the label on the button |
RID RELATIONSHIP NAME | This is the name of the relationship group to which the related issues will be added. The relationship group must be created before you add the name to the cell attribute. If you do not set a value for this attribute, then the value in the behavior setting named RELATION_GROUP_DEFAULT will be used |
RID RELATION TYPE | This should be set to one of the following values:
If you are using the related issue display to add new issues, the value should be CHILDREN or PARENTS. If you choose another relationship type then the issue will be added, but will not be displayed as the relationship is indeterminate |
RID SEARCH FILTER LAYOUT | This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. This field holds the name of the search layout that is being embedded on the same layout as the related issue display. Typically you will embed this search layout just above the related issue display layout |
RID SINGLE SELECT | This attribute is used when you are using a search layout on an add or edit layout to return one or more issues to relate them to the current issue. The default is that the search will allow you to return all the issues the user selects from the results. If you set this attribute, then the user will only allow a single issue to be selected to return the results into the related issue display |
RID SORT ORDER | This attribute determines a sort order, based on a field that is displayed on the related issue display. You can set the value to ASCENDING or DESCENDING |
RID TRANSPOSE LAYOUT | The default is that the related issues will be presented on the display by row. If you select this attribute, then the issues will be presented by column |
SIZE | This controls the width of the related issue display on add and edit screens. The size is an estimate of the number of characters to be displayed. If you do not provide a layout cell attribute for SIZE, then the default is 125 characters.
Beginning with version 10, you can no longer use a SIZE layout cell attribute on the individual fields within the related issue display to control their width. This allows the enabling of a new feature, to freeze the titles of the related issue display. This is very beneficial when you have a significant number of related issues within the display, as the titles always remain visible. |
VISIBLE IF | This allows you to make the entire related issue display visible or not visible depending on the value of another field on the layout within which the related issue display is embedded |
Given that the end user may carry out a combination of operations on several, and sometimes independent, related issue displays with an add or edit screen, there might be some conflict in these operations, with records that might appear in more than a single related issue display. For example, what happens if you update an issue in one relationship, but remove the same issue in another relationship? The RELATIONSHIP_GROUP_REMOVE_BTN is given precedence over other transactions. Transactions are processed in the following order: removes, inserts, deletes (where the deletes are relationship group remove button transactions).