adjust user formatter api

lib/exampletask/index.js

@@ -1,38 +1,81 @@
 (function(){
     const api=window.esp32nmea2k;
     if (! api) return;
+    //we only do something if a special capability is set
+    //on our case this is "testboard"
+    //so we only start any action when we receive the init event
+    //and we successfully checked that our requested capability is there
     let isActive=false;
     const tabName="example";
     const configName="exampleBDSel";
     let boatItemName;
+    let boatItemElement;
     api.registerListener((id,data)=>{
         if (id === api.EVENTS.init){
             //data is capabilities
+            //check if our requested capability is there (see GwExampleTask.h)
             if (data.testboard) isActive=true;
             if (isActive){
+                //add a simple additional tab page
+                //you will have to build the content of the page dynamically
+                //using normal dom manipulation methods
+                //you can use the helper addEl to create elements
                 let page=api.addTabPage(tabName,"Example");
                 api.addEl('div','',page,"this is a test tab");
             }
         }
         if (isActive){
-            console.log("exampletask listener",id,data);
+            //console.log("exampletask listener",id,data);
             if (id === api.EVENTS.tab){
                 if (data === tabName){
+                    //maybe we need some activity when our page is being activated
                     console.log("example tab activated");
                 }
             }
             if (id == api.EVENTS.config){
+                //we have a configuration that
+                //gives us the name of a boat data item we would like to 
+                //handle special
+                //in our case we just use an own formatter and add some
+                //css to the display field
+                //as this item can change we need to keep track of the 
+                //last item we handled
                 let nextboatItemName=data[configName];
                 console.log("value of "+configName,nextboatItemName);
                 if (nextboatItemName){
-                    api.addUserFormatter(nextboatItemName,"xxx",function(v){
+                    //register a user formatter that will be called whenever
-                        return "X"+v+"X";
+                    //there is a new valid value
+                    //we simply add an "X:" in front
+                    api.addUserFormatter(nextboatItemName,"m(x)",function(v,valid){
+                        if (!valid) return;
+                        return "X:"+v;
                     })
+                    //after this call the item will be recreated
                 }
                 if (boatItemName !== undefined && boatItemName != nextboatItemName){
+                    //if the boat item that we handle has changed, remove
+                    //the previous user formatter (this will recreate the item)
                     api.removeUserFormatter(boatItemName);
                 }
                 boatItemName=nextboatItemName;
+                boatItemElement=undefined;
+            }
+            if (id == api.EVENTS.dataItemCreated){
+                //this event is called whenever a data item has
+                //been created (or recreated)
+                //if this is the item we handle, we just add a css class
+                //we could also completely rebuild the dom below the element
+                //and use our formatter to directly write/draw the data
+                //avoid direct manipulation of the element (i.e. changing the classlist)
+                //as this element remains there all the time
+                if (boatItemName && boatItemName == data.name){
+                    boatItemElement=data.element;
+                    //use the helper forEl to find elements within the dashboard item
+                    //the value element has the class "dashValue"
+                    api.forEl(".dashValue",function(el){
+                        el.classList.add("examplecss");
+                    },boatItemElement);
+                }
             }
         }
     })

web/index.js

@@ -1671,7 +1671,7 @@
             src.setAttribute('id', 'source_' + def.name);
             let u = getUnit(def, true)
             addEl('span', 'unit', footer, u);
-            callListeners(api.EVENTS.dataItemCreated, frame);
+            callListeners(api.EVENTS.dataItemCreated,{name:def.name,element:frame});
         }
         let de = document.getElementById('data_' + def.name);
         return de;
@@ -1720,17 +1720,17 @@
             if (!current.name) continue;
             names[current.name] = true;
             let show = current.valid||showInvalid;
-            let de=createOrHideDashboardItem(current,show,frame);
+            let de = createOrHideDashboardItem(current, show, frame);
-            if (de) {
+            let newContent = '---';
-                let newContent = '----';
             if (current.valid) {
                 let formatter;
                 if (current.format && current.format != "NULL") {
                     let key = current.format.replace(/^\&/, '');
-                        formatter = userFormatters[current.name]|| valueFormatters[key];
+                    formatter = userFormatters[current.name] || valueFormatters[key];
                 }
                 if (formatter && formatter.f) {
-                        newContent = formatter.f(current.value);
+                    newContent = formatter.f(current.value,true);
+                    if (newContent === undefined) newContent = "";
                 }
                 else {
                     let v = parseFloat(current.value);
@@ -1743,7 +1743,16 @@
                     }
                 }
             }
-                else newContent = "---";
+            else {
+                let uf=userFormatters[current.name];
+                if (uf && uf.f){
+                    //call the user formatter
+                    //so that it can detect the invalid state
+                    newContent=uf.f(undefined,false);
+                }
+                if (newContent === undefined)newContent = "---";
+            }
+            if (de) {
                 if (newContent !== de.textContent) {
                     de.textContent = newContent;
                     resizeFont(de, true);
@@ -2024,7 +2033,8 @@
             tab: 1, //tab page activated data is the id of the tab page
             config: 2, //data is the config object
             boatData: 3, //data is the list of boat Data items
-            dataItemCreated: 4, //data is the frame item of the boat data display
+            dataItemCreated: 4, //data is an object with
+                                // name: the item name, element: the frame item of the boat data display
         }
     };
     function callListeners(event,data){