Annotating & highlighting in your SAC report

biAnnotation is a Custom Widget that provides script functions for the following needs:

Annotating widgets
Annotating table cells
Highlighting table cells
Overwriting table cells
Clearing annotations / highlights / overwritten values

The annotations are displayed in form of footnotes in the body of the Custom Widget. I have shown a complete example scenario in my post Commenting on table cells & SAC widgets, highlighting and overwriting values.

Implementing the annotation solution

Today I want to show how easily you can realize above example! I will also share the idea how you can use a SAC Planning Model to store the comments, highlight status and overwritten values.

With biAnnotation, you can:

use as much standard functions as possible
implement comments also for live connections by using it as a bridge between Live Connection DATA and SAC Model COMMENTS

Altering table cells

First of all, it is important to find out which cell is currently selected for the table:

selectedCol = biAnnotations_1.getSelectedCol(Table_1.getSelections()[0]);
selectedRow = biAnnotations_1.getSelectedRow(Table_1.getSelections()[0]);

For this to work, the widget must be connected to a table widget, so it knows where to check the selection:

biAnnotations_1.setWidgetID("Table_1");

Now, using this information, we can easily highlight the selected cell:

biAnnotations_1.highlightCell("yellow", selectedRow, selectedCol);

“yellow” is the background color for the cell – you can use any CSS-compliant color notation here.

/mimes/SAC_Screenshots/biAnnotation_09.PNG

By the use of standard SAC functions we can call a popup, where the user can leave a comment. When OK is clicked, the text of TextArea_2 to the biAnnotation Widget:

biAnnotations_1.commentCell(TextArea_2.getValue(), 0, selectedRow, selectedCol, false);

/mimes/SAC_Screenshots/biAnnotation_05.PNG

Similar to the cell comment, we can call a popup, where the user can overwrite a value in the table. When OK is clicked, we simply pass the content of InputField_1 to the biAnnotation Widget:

biAnnotations_1.overwriteCell(InputField_1.getValue(), selectedRow, selectedCol);

Annotating a widget

To comment an SAC Widget, you simply pass the text and the ID of the widget to the biAnnotation widget:

biAnnotations_1.commentWidget(TextArea_1.getValue(), 0, “Text_1”);

/mimes/SAC_Screenshots/biAnnotation_03.PNG

Revert changes

To clear annotations, highlight markers or overwritten values for a table cell, you can use the following script functions:

biAnnotations_1.clearCellComment(selectedRow, selectedColumn);
biAnnotations_1.clearCellHighlight(selectedRow, selectedColumn);
biAnnotations_1.clearCellValue(selectedRow, selectedColumn);

To clear all annotations, highlight markers or overwritten values that are displayed by the widget, you can use the following script functions:

biAnnotations_1.clearCellComments(selectedRow, selectedColumn);
biAnnotations_1.clearCellHighlights(selectedRow, selectedColumn);
biAnnotations_1.clearCellValues(selectedRow, selectedColumn);

Example: Persisting values in a SAC Planning Model

In this section I want to give you an idea of how you can easily use an SAC Planning Model to persist annotations, highlight markers and overwritten values.

Let’s start with an example Planning Model. This should at least contain the technical dimensions “Widget ID”, “Row” and “Column”.

/mimes/SAC_Screenshots/biAnnotation_10.PNG

The “Account” dimension will contain individual entities for:

“Comment”: A value of 1 indicates a comment was entered. The annotation itself is stored via the commenting framework.
“Highlight”: A value of 1 indicates a marker was set.
“Overwrite”: Contains the overwritten value.

This SAC Planning Model then has to be bound to a Table Widget (in this example: "Table_Planning"), in order to access the Planning and Commenting frameworks.

This example shows the full coding for saving a comment. For highlighting and overwriting we use very similar coding.

// build selection
var lselection = {"@MeasureDimension": "[Account].&[Comment_Dummy]", "Widget_Id": "[Widget_id]. &[Table_1]", "Column":"[Column].[HTable].&[3]", "Row": "[Row].[HRow].&[4]", "Date": "[Date].[YQM].&[2018]"};

// set value                                                                       
var lsuccess = Table_Planning.getPlanning().setUserInput(lselection,"1");
if (lsuccess) {

    // save data
    Table_Planning.getPlanning().submitData();

    // add comment
    Table_Planning.getDataSource().getComments().addComment(lselection, comment);

    // show comment 
    biAnnotations_1.commentCell(TextArea_2.getValue(), 0, selectedRow, selectedColumn, false);
}

This example shows how the persisted comments can be read in the onInitialization event of the application. For highlighting and overwriting we use very similar coding.

// clear comments
biAnnotation_1.clearComments();

// build selection
var lselection = {"@MeasureDimension": "[Account].&[Comment_Dummy]", "Widget_Id": "[Widget_id]. &[Table_1]", "Column":"[Column].[HTable].&[3]", "Row": "[Row].[HRow].&[4]", "Date": "[Date].[YQM].&[2018]"};

// get comments by row & column (simplified here)
for (var row = 1; row <= 20; row++){

    // change selection & retrieve comment
    lselection["Row"] = "[Row].[HRow].&[" + ConvertUtils.numberToString(row) + "]";
    var lcomments = Table_Planning.getDataSource().getComments().getAllComments(lselection);

    // set to annotation
    if (lcomments){
        var no = 0;
        var lcomment = lcomments[no];
        while (lcomment)  {
            biAnnotation_1.addComment(lcomment.text, 0, row, column);
            no = no + 1;
            lcomment = lcomments[no];
        }
    } 
}

Author: Thilo Knötzele
Creation date: 03.02.2021
Category: Commenting
back to overview

Categories

Authors