RemarkService

---

The RemarkService is a powerful tool for attaching contextual remarks to elements within your application's model. These remarks appear as interactive badges, providing users with quick visual cues and access to more detailed information.

Here's an example of how to use the RemarkService within a typical service:

class MyRemarksService {
  // Inject the RemarkService to utilize its functionalities
  private remarkService = inject(RemarkService);

  // Define a category for remarks managed by this service.
  // This allows for selective clearing of remarks later.
  private readonly category = "demo.checks";
  
  /**
   * Checks a ComponentModel and its data elements, adding remarks as needed.
   * @param component The ComponentModel to check.
   */
  checkModel(component: ComponentModel) {
    // Clear only the remarks previously added by this service's category.
    // This prevents stale remarks from accumulating.
    this.remarkService.clearRemarks({ category: "demo.checks" });

    // Iterate through data elements to perform individual checks.
    for (const dataElement of component.dataElements) {
      this.checkDataElement(dataElement);
    }
  }

  /**
   * Checks a single DataElementModel and adds a remark if a condition is met.
   * @param dataElement The DataElementModel to check.
   */
  checkDataElement(dataElement: DataElementModel) {
    // Replace with your actual condition to determine if a remark is needed.
    if (/* check some condition */) {
      this.remarkService.addRemark(remark({
        subject: { // Identifies the model element to which the remark applies.
          id: dataElement._id.key,
          type: dataElement._id.type,
          url: dataElement._id.url!
        },
        label: "invalid", // A concise label displayed on the remark badge.
        priority: Priority.WARNING, // Sets the badge's color (e.g., WARNING for orange, ERROR for red).
        note: "This dataElement is invalid", // The tooltip message shown on hover.
        category: this.category, // Assigns a category for easy management (e.g., clearing).
        showMore() { // A function executed when the remark badge is clicked.
          alert("Some explanation about why this data element is invalid.");
          // You could open a dialog, navigate to another view, etc.
        }
      }));
    }
  }
}

Key Concepts

• addRemark(remark): This method is used to add a new remark to a model element. The remark object contains all the details for the badge.
• clearRemarks(options): This method allows you to remove remarks. You can clear all remarks or filter them by category or subject.
• remark object: This object defines the properties of the remark badge:
  • subject: Crucial for linking the remark to a specific model element. It requires the id, type, and url of the target element.
  • label: A short, descriptive text shown on the badge.
  • priority: Determines the visual importance and color of the badge (e.g., Priority.INFO, Priority.WARNING, Priority.ERROR).
  • note: The text that appears when a user hovers over the badge.
  • category: A custom string to group related remarks. This is highly recommended for easier management and selective clearing.
  • showMore(): A callback function executed when the user clicks on the remark badge. This is where you can provide more detailed information or actions.

---

glint-model-remarks

The glint-model-remarks component is responsible for displaying the remark badges associated with a given model element. It automatically fetches and renders remarks that have the provided model as their subject.

<glint-model-remarks [model]="dataElement"></glint-model-remarks>

Properties

• [model]: This required input property accepts the model element for which remarks should be displayed. The component will match this model against the subject property of registered remarks.