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.

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);

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”);

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”.

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]; } } }