Create_a_Rule_c24569d.md

loio
c24569de859446819798c5dc53ac604d

view on: demo kit nightly build | demo kit latest release

Create a Rule

A rule consists of properties that test and advise on how possible issues can be resolved and a check function that tests the application for a specific issue. To create a rule, you need to set the properties and add a check function.

For more information on how to create rules in the user interface, see Rules Management.

You can find best practices on how to create rules in Guidelines and Best Practices .

---

Properties

You need to set the following properties :

Property	Description
ID	The ID of the rule. It must be a valid camelCase string consisting of between 6 and 50 alphabetic characters.
Title	The name of the rule in a readable format. It must be a valid string consisting of between 6 and 200 characters.
Audiences	Describes what audiences the rule is intended for. You can have multiple audiences selected.
Categories	Describes what the rule tests. You can have multiple categories selected.
Min version	The minimum version the rule should be checked at. Possible values are <empty string> and versions like 1.28, 1.44, etc.
Async	Defines if the rule check function will contain asynchronous operations.
Description	A short description of the rule.
Resolution	A short advice on what to do to fix the issue generated by the rule.
Resolution URLs	An array of key/value pairs of texts and URLs providing the links to documentation where the user can find how to fix the issue generated by the rule. You can have multiple resolution URLs. Key is text and value is href.
Check function	Function that checks the application against the rule. It is described in more detail in the next section.

---

Check Function

The check function has three main and one optional parameters. The main ones are oIssueManager, oCoreFacade and oScope, and the optional one is fnResolve. Here is more information about them:

• oIssueManager - allows you to add new issues with the addIssue() method. The issue object has the following properties:

  • Severity - the possible values are:

    • sap.ui.support.Severity.Low

    • sap.ui.support.Severity.Medium

    • sap.ui.support.Severity.High

  • Details - free text, may include any type of details related to the issue.

  • Context - an object, which has an ID property. The ID should belong to the element, which generates the issue.

• oCoreFacade - gives you access to the different elements provided by the OpenUI5 core framework:

  • getMetadata()

  • getUIAreas()

  • getComponents()

  • getModels()

• oScope - retrieves elements in the scope with the following methods:

  • getElements() - returns all the elements.

  • getElementsByClassName(className) - the className can be, for example, sap.m.Button. The function returns all elements of type sap.m.Button.

  • getPublicElements() - returns all elements that are part of public API aggregations.

  • getLoggedObjects(type) - returns all logged objects. The method provides access to the logs and traces in the browser Console. Note that it is possible to enhance the log traces with an extra fnSupportInfo object which you can then analyze in the rule check function. The fnSupportInfo function is called only when support mode is turned on with the URL parameter sap-ui-support set to true (sap-ui-support=true). For more information, see Rules for the Console Traces and Logging.

  Prior to version 1.54, getElements was not accepting any arguments and was returning all elements registered with the core. Now it accepts one query object parameter. This allows you to select only a specific subset of elements valid for your use case. The three parameters of the method are type, public, and cloned.

  Here is an example format:

  var queryObject = {
  
    type: "sap.m.Button", // String property specifying the type to select
  
    public: true, // Boolean property specifying whether only public elements should be loaded
  
    cloned: false // Boolean argument specifying if cloned elements are needed
  
  }
  

  When the public parameter is set to true, the getElements function only explores public aggregations. It is useful if, for example, you have a composite control comprising of public and internal subelements, and you only want to check the public ones.

  The cloned parameter allows you to filter out elements that are clones of list bindings. If you don't want to explore issues associated with multiple cloned elements, for example repeated table cell content, set cloned: false and the results will include only one representative instance.

  Here is an example of a check function that checks all Input controls which are part of the public aggregation and have no parent set:

  function(issueManager, oCoreFacade, oScope) {
    var mElements = oScope.getElements({
      type: "sap.m.Input",
      public: true,
      cloned: false
    });
    for (var n in mElements) {
      var oElement = mElements[n];
      if (!oElement.getParent()) {
        issueManager.addIssue({
          severity: sap.ui.support.Severity.Medium,
          details: "The element " + oElement.getId() + " has no parent.",
          context: {
            id: oElement.getId()
          }
        });
  
      }
    }
  }

• fnResolve - an optional parameter. It is passed to the check function only when the rule property async is set to true to allow you, as the rule developer, to resolve an asynchronous operation. The rule times out if it takes more than 10 seconds to resolve.

  Here is an async rule code example:

  function(issueManager, oCoreFacade, oScope, fnResolve) {
    // Some async operation
    setTimeout(function () {
      …
      fnResolve();
    }, 2000);
  }

Remember:

Make sure to call issueManager.addIssue() in your check function so that issues can be seen in the analysis results.

Related Information

API Reference: sap.ui.support.ExecutionScope

Common Rule Patterns