Rapporter — Utöka¶

WideQuick levereras med en uppsättning standardrapportmallar, men det är också möjligt att skapa helt anpassade mallar som är skräddarsydda för specifika behov. Det här avsnittet täcker hela processen för att skapa en anpassad rapportmall och tillhörande ReportController-vy, från att designa Excel-layouten till att koppla den till livedata från databasen.

Det här avsnittet förutsätter kännedom om grunderna i rapportsystemet. Se vid behov Kom igång och Konfigurering.

Skapa mallar¶

Processen för att skapa egna rapportmallar består av tre steg:

1. Designa mallen i Excel
2. Konfigurera datablad, makron och loggenheter
3. Koppla ihop allt

Designa mallen¶

Det första steget är att designa rapportmallen i Excel. Detta inkluderar att besluta om layout, vilka diagram som ska inkluderas och hur data ska presenteras. WideQuick sätter inga begränsningar på designen, så mallen kan anpassas fritt.

En rapportmall består vanligtvis av tre blad:

• Presentationsblad: den synliga delen av rapporten. Innehåller diagram, tabeller och alla andra visuella element som rapporten ska visa.
• Datablad: ett dolt blad som innehåller rådata hämtad från databasen. Det här bladet matar presentationsbladet med data. Databladet är enklare att konfigurera i WideQuick® Designer, där dolda blad är synliga, jämfört med direkt i Excel.
• Metablad: ett dolt blad som innehåller allmän information om rapporten, som rapporttitel, aktuellt datum och tid, vald loggenhet och valda signaler. Det här bladet är användbart för att visa rapportmetadata på presentationsbladet.

För att lägga till ett nytt blad i mallen, öppna mallen i WideQuick® Designer och navigera till botten av bladflikarna. Klicka på Create New Sheet, se bilden nedan. För att dölja bladet, högerklicka på bladfliken och välj Hide Sheet.

Konfigurera datablad, makron och loggenheter¶

Databladet är ett dolt blad i rapportmallen som fungerar som behållare för rådata hämtad från databasen. När en rapport genereras använder WideQuick makrokommandon placerade i databladet för att fråga databasen och fylla den med data.

För att lägga till ett makrokommando, högerklicka på en cell i databladet och välj Edit Expression. Detta öppnar följande popup:

Nedan beskrivs varje fält:

• Variable — Definierar vilken signal som ska frågas. Två alternativ är tillgängliga:

  • variable_ref[#] — Frågar en specifik signal, där # är signalens index. Ett separat makroanrop krävs för varje signal.
  • alarms — En "wildcard" som hämtar alla larm i den valda loggenheten.

• Values — Definierar vilka datakolumner som ska inkluderas. Beror på typen av data som frågas:

  • Signaldata: name, datetime, value är vanligtvis tillräckligt.
  • Larmdata: name, state, severity, timestamp, text, group. Inkludera bara de fält som behövs för rapporten.

• Logger — Loggenheten som rapporten hämtar data från. Denna måste anges statiskt och kan inte ändras dynamiskt.

• Fixed/Range timespan — Rapportören använder Range timespan som standard, med Report_Reference.from_time och Report_Reference.to_time som start- och sluttider. Dessa anges av tidsobjekten i ReportController.
• Limit — Det maximala antalet rader att fylla. Detta anges av användaren i ReportController vid generering av rapporten.
• Datetime format — Det format som används för datum- och tidsvärden. Standardvärdet är yyyy-MM-dd hh:mm:ss men kan justeras för att passa rapportens behov.

Placeringen av makrokommandot är viktig. Data fylls i med start från cellen där makrot placeras och expanderar nedåt. Kolumnerna bestäms av fältet Values. Till exempel kommer ett signalmakro med VALUES(name, datetime, value) att fylla tre kolumner med start från makrocellen:

Och för larmdata med VALUES(name, state, severity, timestamp, text, group):

Antalet ifyllda rader beror på Limit och tidsintervallet, som anges av användaren i ReportController vid generering av rapporten.

Koppla ihop allt¶

Med presentationsbladet designat och databladet ifyllt med makrokommandon är det sista steget att koppla samman de två genom att länka rådata till diagram, tabeller och andra visuella element i presentationsbladet.

Några tips för att koppla ihop mallen effektivt:

• Använd databladet för beräkningar: eftersom databladet är dolt i den slutliga rapporten är det ett bra ställe att utföra mellanliggande beräkningar innan resultaten skickas till presentationsbladet. För att redigera det i Excel, gör det tillfälligt synligt.
• Håll beräkningar borta från makrodata: eftersom makrodata expanderar nedåt rad för rad, placera eventuella ytterligare beräkningar i kolumner längre till höger för att undvika konflikter.
• Referera till databladet från presentationsbladet: diagram, staplar och andra visuella element i presentationsbladet bör referera till celler i databladet snarare än att innehålla logik i sig själva. Detta håller presentationsbladet rent och enklare att underhålla.
• Använd fasta intervall som täcker det maximala möjliga antalet rader: eftersom mängden data varierar beroende på Limit och tidsintervallet, definiera intervall som täcker det maximala antalet rader rapporten kan producera. Använd IFERROR för att hantera tomma celler på ett smidigt sätt.

Skapa ReportController-vyn¶

Med mallen skapad är nästa steg att bygga ReportController-vyn. Den här vyn bestämmer vilka signaler och data som skickas till rapporten när den genereras. Systemet kopplar en ReportController till en rapportmall genom att matcha deras namn, så det är viktigt att vyn namnges exakt samma som rapportmallen.

För att komma igång, navigera till Templates i projektträdet och duplicera Template_ReportController-vyn. Flytta duplikatet till mappen ReportController och döp om det för att matcha rapportmallens namn.

När en ReportController-vy laddas, initierar dess mallskript ett view.data-objekt med standardvärden såsom rapporttyp, tidsintervall, loggenhet och signalreferenser. Varje objekt placerat i vyn, som to_time, Report_CustomTitle och LoggerList, läser från och skriver till detta delade view.data-objekt när användaren interagerar med dem.

När Button_CreateReport-objektet klickas, samlar det in det fullständiga view.data-objektet och lägger till det i en rapportkö via funktionen scReports.addReportToQueue(). Rapporter i kön behandlas en i taget. scReports-skriptet fyller ett globalt Report_Reference-objekt med köad data, som makrokommandona i databladet läser från vid förfrågan mot databasen.

Den korrekta mallen identifieras och aktiveras med hjälp av fältet report_type i view.data, som härleds direkt från ReportController-vyns namn. Det är därför det är kritiskt att ReportController-vyns namn exakt matchar rapportmallens namn. Om de skiljer sig åt kan scReports-skriptet inte hitta och aktivera rätt mall.

För att bygga vyn finns en uppsättning färdiga objekt tillgängliga i objektbiblioteket under Report. Nedan beskrivs varje objekt och när det ska användas:

LoggerList¶

LoggerList-objektet är en TreeView konfigurerad för att visa signalerna som loggas av en specifik loggenhet. När en signal väljs visas en grön bockmarkering bredvid den i TreeView. Objektet inkluderar även två textrutor som visar den aktuellt valda loggenheten och antalet valda signaler av det maximalt tillåtna.

Loggenheten som ska visas och det maximala antalet valbara signaler konfigureras båda som egenskaper på objektet. Tilldela önskade värden när objektet placeras i en ReportController.

LarmLogger_List¶

LarmLogger_List-objektet är en specialiserad version av LoggerList, byggd för att visa larm loggade av en loggenhet. Till skillnad från LoggerList bygger den automatiskt sitt träd baserat på larmgrupper och utelämnar redundant information. Om till exempel alla larm i loggenheten följer mönstret AS01.AS01_XXX_XX, kommer TreeView att visa dem enkelt som XXX_XX.

Det här objektet har två egenskaper som måste konfigureras:

• Logger — Bestämmer vilken loggenhet som TreeView byggs från. Detta bör alltid matcha loggenheten som rapporten frågar mot.
• Signals — Styr hur många signaler som kan väljas för rapporten. Standardvärdet för maximum är 15, och det kan ändras. Se Ändra maximalt antal signaler som kan väljas. Den här egenskapen bör alltid anges till ett numeriskt värde, om inte TreeView är avsiktligt låst.

Unit¶

Unit-objektet innehåller de två väljarna som bestämmer rapportens visningsenhet: en kombinationsruta Enhet för basenheten och en kombinationsruta Prefix för SI-prefixet. De två kombineras när rapporten skapas, så att k och Wh ger kWh.

Listan i Enhet är inte en fast uppsättning. Den byggs vid körning utifrån enheterna hos signalerna på den logger som signallistan är kopplad till, reducerade till sin SI-bas, så att endast enheter som projektet faktiskt loggar erbjuds. En signal vars enhet inte känns igen utelämnas från listan. Se Lägg till en basenhet för den igenkända uppsättningen och hur den utökas.

Att placera objektet aktiverar även enhetsfiltrering för signallistan:

• TreeView förblir låst till dess att en enhet har valts.
• När en enhet väljs filtreras TreeView till signaler av den dimensionen.
• Om enheten ändras rensas det aktuella urvalet, eftersom de signaler som valdes under den tidigare enheten inte längre finns i listan.

Filtreringen är därför valfri per ReportController. En kontroller som byggs utan Unit-objektet lämnar TreeView ofiltrerad, tillåter signaler av olika dimensioner i samma rapport och skickar varje värde i sin egen ursprungliga enhet utan skalning. Larmrapporternas kontroller är byggda på det sättet.

Objektet har inga egenskaper. Det hittar signallistan på egen hand, så samma objekt fungerar oavsett om vyn innehåller en loggerlista eller visar en andra i dess ställe.

Report_CustomTitle¶

Report_CustomTitle-objektet består av en etikett och en textruta. Textrutan anger rapportens titel och är konfigurerad för att kommunicera med den aktiva datan i vyn.

Button_CreateReport¶

Button_CreateReport-objektet är en knapp som utlöser rapportgenerering. När den klickas samlar den in data från vyn och skickar den till scReports-skriptet för att skapa rapporten.

Report_output_type¶

Report_output_type-objektet består av en etikett och en ComboBox. Det valda ComboBox-värdet bestämmer om rapporten genereras som enbart PDF, eller som både en PDF och en Excel-fil.

to_time¶

to_time-objektet består av en etikett och en DateTime-redigerare. DateTime-redigeraren anger rapportens sluttid och är konfigurerad för att rapportera sitt aktuella värde till vyn.

from_time¶

from_time-objektet fungerar på samma sätt som to_time-objektet, men anger rapportens starttid istället.

to_time_Singel¶

to_time_Singel-objektet kombinerar funktionaliteten hos to_time och from_time i ett enda objekt. Det används när rapportmallen kräver ett fast tidsintervall. Följande egenskaper kan konfigureras:

• Years prior — Anger tidsintervallet i år.
• Weeks prior — Anger tidsintervallet i veckor.

Dessa två egenskaper utesluter varandra: veckor och år kan inte kombineras.

Numbe_of_event¶

Numbe_of_event-objektet består av en etikett och en SpinBox. SpinBox-värdet bestämmer hur många händelser som samlas in per makroanrop. Denna distinktion är viktig:

• Om jokertecknet alarms används representerar värdet det totala antalet händelser.
• Om variable_ref[#] används representerar värdet antalet händelser per signal.

Ändra maximalt antal signaler som kan väljas¶

I standardinställningarna för rapportören tillåts 15 signaler att väljas för rapportgenerering. Detta kan enkelt ändras om fler signaler krävs. Navigera först i WideQuick® Designer till Data Types → Arrays → variable_ref och välj Properties.... Detta öppnar följande popup:

Ändra Max. size till önskat värde. Klicka på Apply och sedan Ok. Report_Reference-arrayen har nu uppdaterats.

Uppdatera sedan scReports-skriptet för att hantera den nya storleken. Leta upp funktionen createReport() och ändra värdet 15 till det nya Max. size-värdet:

for (var i = 0; i < 15; i++) Report_Reference.variable_ref[i] = "";
var signals = reportObj.variable_ref.split(',');
for (var i = 0; i < signals.length && i < 15; i++) Report_Reference.variable_ref[i] = signals[i];

for (var i = 0; i < YOUR_MAX_VALUE; i++) Report_Reference.variable_ref[i] = "";
var signals = reportObj.variable_ref.split(',');
for (var i = 0; i < signals.length && i < YOUR_MAX_VALUE; i++) Report_Reference.variable_ref[i] = signals[i];

Lägg till en basenhet¶

Rapportsystemet känner igen sex fysikaliska storheter, var och en i valfritt SI-prefix:

Prefixen som erbjuds är T, G, M, k, h, da, inget, d, c, m, µ, n och p, så de sex baserna täcker tillsammans 78 enhetsbeteckningar.

Dimensionsexponenten är det som håller skalningen korrekt. Ett prefix på en linjär storhet skalar med prefixet självt, så dW är en tiondel av W. Ett prefix på m³ tillämpas på metern innan den kuberas, så dm³ är en tusendel av m³ i stället för en tiondel. Varje bas som är en längd i kubik får exponenten 3, alla övriga får 1.

Att lägga till en basenhet är en ändring på två ställen i scReports-skriptet, och de två måste hållas i samma takt.

Lägg först till enheten i tabellen baseUnitInfo tillsammans med dess dimensionsexponent:

this.baseUnitInfo = {
    "W": { power: 1 }, "Wh": { power: 1 },
    "m³": { power: 3 }, "m³/h": { power: 1 },
    "L": { power: 1 }, "L/s": { power: 1 }
};

this.baseUnitInfo = {
    "W": { power: 1 }, "Wh": { power: 1 },
    "m³": { power: 3 }, "m³/h": { power: 1 }, "m³/s": { power: 1 },
    "L": { power: 1 }, "L/s": { power: 1 }
};

Lägg därefter till samma sträng i baseUnitOrder. Den listan är ordnad med den längsta först, så att en sammansatt enhet matchas i sin helhet i stället för att läsas som ett prefix följt av en kortare bas. m³/h måste testas före m³, annars läses den som prefixet m plus basen ³/h. Placera en ny enhet före varje kortare enhet som den inleds med:

this.baseUnitOrder = ["m³/h", "L/s", "m³", "Wh", "W", "L"];

this.baseUnitOrder = ["m³/h", "m³/s", "L/s", "m³", "Wh", "W", "L"];

En signal vars enhet inte finns i tabellen hoppas över utan loggpost när listan i Enhet byggs. En logger som bara innehåller okända enheter ger därför en tom Enhet-lista, och eftersom signalernas TreeView är låst till dess att en enhet har valts verkar kontrollern inte erbjuda några valbara signaler alls. Att lägga till enheten i tabellen löser det.