User Interface Options
Some configuration options are also available to tweak the Squore user interface. These options need to be specified in a file called properties.xml located at the root of your Configuration folder, or in various other Bundle.xml files. This chapter describes these options and their effect on the user interface.
|
You can find the XML schema for properties.xml in properties-1.2.xsd. |
Hiding Explorer tabs
By default, the Explorer shows the following tabs for all users: Dashboard, Action Items, Highlights, Findings, Documents, Forms, Comments and all available custom tabs.
Users can change the displayed tabs by clicking the Tab Manager icon right of the last tab. You can also define the available tabs and their default state (shown, hidden, default) by editing properties.xml as shown below:
<!-- Active tabs -->
<explorerTabs>
<tab name="dashboard" default="true"/>
<tab name="action-items" mandatory="true"/>
<tab name="highlights"/>
<tab name="findings"/>
<tab name="documents" rendered="false"/>
<tab name="attributes"/>
<tab name="indicators" rendered="false"/>
<tab name="measures" rendered="false"/>
<tab name="annotations"/>
</explorerTabs>Each tab element accepts the following parameters:
-
name(mandatory) identifies the tab of the Explorer by name. The supported values are:-
dashboard
-
action-items
-
highlights
-
findings
-
documents
-
attributes
-
indicators
-
measures
-
annotations
-
-
mandatory(optional, default: false) removes the option to hide the tab from the web UI for all users. -
default(optional, default: false) makes the tab the default tab in Squore. Every link to a project or artifact that does not specifically request a target tab will open the Explorer with this tab active by default. Note that when set to true, the tab is automatically mandatory as well. -
rendered(optional, default: true) specifies whether the tab is shown (true) or hidden (false) by default. Hidden tabs can be shown by checking a box in the Tab Manager. Note that the value of this attribute is ignored if eitherdefaultormandatoryis set to true.
|
The tabs definitions order (top to bottom) will define the display order in Explorer page (left to right). |
Customising the Help menu
You can use the help option to add links that will appear in the Help menu in Squore (? in the main toolbar), as shown below.
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Bundle>
<!-- Customise the help links that appear in the right menu -->
<help label="OWASP 25" url="http://cwe.mitre.org/top25/" />
<help label="JBoss Wiki" url="http://www.jboss.org/jbosswiki" roles="ADMINISTRATOR;" />
</Bundle>The help element accepts the following attributes:
-
label(mandatory) is the label for the link in the help menu. -
url(mandatory) is the URL to link to. -
roles(optional) is a list of global roles that are allowed to see the link. If not specified, then the link is displayed for all logged-in users.
Hiding specific models
If you wish to hide some of the available models in Squore, you can use the hideModel option to prevent some folders under the models folder in the configuration from being read by Squore, as shown below.
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Bundle>
<!-- Hidden models -->
<hideModel name="ISO9126_Maintainability_Xaml" />
</Bundle>The hideModel element accepts only one attribute:
-
name(mandatory) is the name of the folder to exclude from the configuration.
Hiding specific measures
If it does not make sense to display a specific measure in the Indicator Tree or the Model Viewer, you can hide it by editing the Properties bundle of a model. This is useful to remove confusion about how a measure is computed.
In order to hide a measure:
-
Edit the model’s Properties/Bundle.xml.
-
Add a
<hideMeasure targetArtefactTypes="" path="" >element. -
Fill in the artifact types for which this measure is hidden (this is optional).
-
Specify the complete path of the measure to be hidden.
Below is an example of two hidden paths. The first one is only hidden at application level. The second one is always hidden.
<bundle>
<!-- Hidden measures -->
<hideMeasure targetArtefactTypes="APPLICATION" path="I.MAINTAINABILITY/I.ANALYSABILITY/I.FUANA_IDX" />
<hideMeasure path="I.MAINTAINABILITY/I.CHANGEABILITY/I.ROKR_CHAN/D.RKO_CHAN" />
</bundle>Note that you should always use the precise notation path elements, with the I., B. or D. to avoid ambiguities.
Tweaking the Ruleset Editor screen
Using the Properties bundle, you can define the list of categories available for edition in the Ruleset Editor. By default, all categories can be edited, but the rulesEdition element allows you to explicitly limit the list to specific categories.
<bundle>
<rulesEdition scales="CUSTOMER_SEVERITY;CUSTOMER_REMEDIATION;SCALE_SCHEDULE" />
</bundle>The rulesEdition element takes a scale attribute that accepts a semicolon-separated list of scales to display for each rule in the Ruleset Editor for this model.
Configuring Action Items and Findings tabs
Configuring sorting order
You can define for each model the order that is used to sort items in the Action Items and Findings pages.
This is done by defining one or more scales and adding them to the Properties/Bundle.xml file using the findingsTab and actionItemsTab options, as shown below:
<bundle>
<!-- sort order for columns -->
<findingsTab orderBy="SCALE_PRIORITY;SCALE_SEVERITY" />
<actionItemsTab orderBy="SCALE_REMEDIATION;SCALE_SEVERITY" />
</bundle>Hiding columns
You can define for each model the columns that should be hidden in the Action Items and Findings pages.
This is done by defining one or more scales and adding them to the Properties/Bundle.xml file using the findingsTab and actionItemsTab options, as shown below:
<bundle>
<!-- sort order for columns -->
<findingsTab hideColumns="SCALE_PRIORITY;SCALE_SEVERITY" />
<actionItemsTab hideColumns="SCALE_REMEDIATION;SCALE_SEVERITY" />
</bundle>You can also hide the Characteristics filter with the hideCharacteristicsFilter attribute:
<bundle>
<!-- hide characteristics column (list of families) -->
<findingsTab hideCharacteristicsFilter="true" />
</bundle>You can also hide the ProvidedBy column and filter with the hideProvidedBy attribute:
<bundle>
<!-- hide characteristics column (list of families) -->
<findingsTab hideProvidedBy="true" />
</bundle>Hiding the CSV export button
You can hide the "Export to CSV" button available in the Findings tab, by adding the following option in the properties.xml file:
<bundle>
<!-- Options for the findings page -->
<option name="page.findings.export.visible" value="true"/>
</bundle>Accepted values are true (to show the button) or false (to hide the button). By default the button is displayed.
Configuring links to external resources
In models that integrate requirements, test cases or change requests as artifacts, it may be necessary to provide a link to view an artifact in the context of the application where it was created. This can be done in Squore by configuring the View Source link in the Dashboard to open links in an external applications. This section shows how you can configure external links using Jira as the target application.
Our model collects Jira issues and shows a minimal dashboard or the issue’s status, assignee, priority, summary and description, as shown below:
The Jira issue shown above is an artifact of type NEW_FEATURE. In order to make the View Source link open the Jira issue in a browser, you simply need to create a properties file in the sources folder of your configuration, whose name is the artifact type in lower case.
type=url
pattern=https://github.com/squoregit/earthRepo/issues/{0}
pattern.findings=https://github.com/squoregit/earthRepo/issues/browse/{0}/activity?from={1}
p0=INFO(ISSUE_ID)
p1=INFO(ASSIGNEE)The syntax of this properties file is as follows:
-
type is the type of link to create. Only url is currently supported.
-
pattern is the URL pattern used to generate a link for the View Source link in the Dashboard. You are free to insert parameters in the URL as needed, as long as you declare them in the properties file.
-
pattern.findings is the URL pattern used to generate a link for artifacts on the Findings tab. This pattern also supports parameters.
-
p0, p1… pn are parameters that accept a computation that will return a string for the artifact. In the example above, ISSUE_ID and ASSIGNEE are two text metrics that exist for the NEW_FEATURE artifact type.
You can use the following computations:
-
INFO(measureId) to retrieve textual information from the current artifact.
-
ARTEFACT_LOCATION() to retrieve the location of an artifact within a file. For example, it will return 5 for a function artifact that starts at line 5 of its parent file artifact.
-
FINDING_LOCATION() to retrieve the precise location of the finding within the artifact. For example, it will return 2 if the finding is located on the second line of a function artifact (no matter where in the file the function artifact is located).
-
Enabling model/group rating in Project Portfolios
It is possible to display the models and groups of project rating in the Project Portfolios:
To do so, just add the following line in the "Properties/Bundle.xml" file of your model:
<bundle xmlns:xi="http://www.w3.org/2001/XInclude" >
<scoreGroups indicatorId="LEVEL" aggregationType="AVG" />
</bundle>The scoreGroups element accepts the following attributes :
-
indicatorId(optional, default: LEVEL) is the indicator to use to rate the project group. -
aggregationType(optional, default: AVG) is the aggregation method used to compute the indicator level. The supported values allowed are:-
MIN: minimal value
-
MAX: maximal value
-
OCC: number of data points
-
AVG: average value
-
DEV: standard deviation
-
SUM: sum of values
-
MED: median value
-
MOD: modal value
-
|
When rating models/groups is disabled, you can use a group icon instead by defining it in the properties. |