administration:analys:canvas [Orbiq wiki]

Denna sida är skrivskyddad. Du kan titta på källkoden, men inte ändra den. Kontakta administratören om du anser att du bör kunna ändra sidan.
====== Canvas-widget ======

Canvas-widgeten är en paneltyp i Analys som ritar upp livedata från tidsseriedatabasen ovanpå en bakgrundsbild, till exempel ett flödesschema, en planritning eller en systemskiss. Utöver att visa värden kan widgeten innehålla inputfält som skriver nya värden till tidsseriedatabasen. På så sätt kan du bygga översiktsbilder där du både läser av ett system och gör överstyrningar (t.ex. ändra ett börvärde eller slå på/av en funktion) direkt från panelen.

===== Vad är en canvas-widget? =====

En canvas-widget består av:

  * **En bakgrundsbild** som all information plottas ut på. Bilden är grunden för hela widgeten.
  * **Items** som placeras fritt på bilden. Det finns tre typer:
    * **Text item** – statisk text (med formatering) som även kan innehålla taggar som skriver ut senaste värdet från en tidsserie.
    * **Value item** – en symbol som visar senaste värdet för en tidsserie. Utseendet styrs av en //canvas template// som bestämmer ikon och vilka färger olika värden ska få.
    * **Input item** – ett inmatningsfält (siffervärde eller på/av-knapp) som skriver ett nytt värde till tidsseriedatabasen när du trycker Enter eller slår om knappen.

Value items och taggar i text items uppdateras automatiskt med valbart intervall (1, 5 eller 10 minuter) så att widgeten visar aktuella värden.

===== Skapa en canvas-widget =====

  - Öppna panelen och gå in i redigeringsläge.
  - Klicka på **+** i en panelrad (eller i rutnätsläget) och välj **Canvas**.
  - Canvas-editorn öppnas i helskärm. Ge widgeten ett namn i fältet högst upp.

Editorn består av tre delar:

  * **Verktygsraden** högst upp med knapparna **Add background image...**, **Add text**, **Add value** och **Add input**.
  * **Förhandsvisningen** i mitten där du placerar och flyttar items.
  * **Inställningspanelen** (Settings) till höger som visar inställningar för det item (eller den bakgrund) som är markerat.

==== Steg 1 – Ladda upp en bakgrundsbild ====

Det första du gör är att ladda upp den bild som all information ska plottas ut på.

  - Klicka på **Add background image...**.
  - Välj en bildfil. Formaten JPG, PNG, WebP och GIF stöds.
  - Bilden visas direkt i förhandsvisningen. Den laddas upp när panelen sparas.

Klicka på bakgrunden för att visa dess inställningar i sidopanelen:

  * **Background image size** – skala för bilden i procent (10–300 %). 100 % motsvarar bildens ursprungliga pixelstorlek. Använd detta för att få en lagom stor arbetsyta i förhållande till widgetens storlek i panelen.

Alla items positioneras i procent av bilden, så de följer med om du ändrar skala eller zoomar i panelen.

==== Steg 2 – Lägg till items ====

Använd knapparna **Add text**, **Add value** och **Add input** för att lägga till items. Ett nytt item placeras mitt på bilden och kan sedan dras till rätt plats med musen.

  * Klicka på ett item för att markera det. Inställningarna visas i sidopanelen till höger.
  * Ett markerat item får ett litet kryss (**Remove selected**) som tar bort det.
  * Klicka på bakgrunden för att avmarkera.

De olika item-typerna beskrivs i detalj nedan.

==== Steg 3 – Spara ====

Klicka på spara-ikonen (**Save panel**) i verktygsraden. Bakgrundsbilden laddas upp och widgeten sparas i panelen.

**Obs:** Input items kan inte skriva värden förrän widgeten har sparats första gången.

===== Text item =====

Ett text item används för rubriker, etiketter och förklarande text på bilden. Lägg till ett med **Add text**.

Inställningar i sidopanelen:

^ Inställning ^ Beskrivning ^
| **Text content** | Själva texten. Verktygsraden ovanför ger fetstil, kursiv, understruken, länk samt punkt- och nummerlista. |
| **Text color** | Textfärg. |
| **Font size** | Teckenstorlek i pixlar (10–96). |
| **Text width** | Bredd på textrutan i procent av widgetens bredd. Texten radbryts inom bredden. |
| **Card layout** | Lägger textrutan på ett kort med ram och bakgrund. |
| **Background color** | Kortets bakgrundsfärg (visas när Card layout är på). |

==== Värdetagg i text ====

I ett text item kan du använda en tagg som läser senaste värdet från en tidsserie och skriver ut det som text, mitt i den övriga texten. Det gör det möjligt att skriva t.ex. ''Framledning: 45.2 °C'' där siffran hämtas live.

Taggen har formatet:

<code>
{#UUID.<serie-uuid>.value:<intervall>}
</code>

  * ''<serie-uuid>'' är tidsseriens UUID.
  * ''<intervall>'' är hur ofta värdet ska uppdateras: ''1m'', ''5m'' eller ''10m''.

Exempel:

<code>
Börvärde: {#UUID.3f2a9c1e-7b4d-4e8a-9c21-5d6f7a8b9c0d.value:1m} °C
</code>

Så här lägger du in en tagg:

  - Markera ett text item.
  - Klicka på knappen med kod-ikonen (**Add value tag**) i textens verktygsrad.
  - Ange **Series UUID** och välj **Refresh interval**.
  - Klicka på **Save**. Taggen läggs till sist i texten och kan sedan flyttas eller kompletteras med vanlig text.

Du kan också skriva taggen direkt i texten för hand. När widgeten visas ersätts taggen med seriens senaste värde (eller ''-'' om inget värde finns). Flera taggar med olika serier kan användas i samma text item.

**Tips:** Taggen passar bra ihop med input items. När ett input item har skrivit sitt första värde får det ett UUID som du kan kopiera (se nedan) och klistra in i en värdetagg för att visa det aktuella överstyrda värdet i klartext.

===== Value item =====

Ett value item visar senaste värdet från en tidsserie som en symbol på bilden. Symbolen är en ikon i en cirkel där cirkelns färg ändras beroende på värdet, enligt den canvas template du valt. Värdet i sig visas i en tooltip.

==== Lägga till ett value item ====

  - Klicka på **Add value**.
  - Välj en **Canvas Template** i sidopanelen. Detta är obligatoriskt – utan template kan ingen symbol ritas. Finns inga templates visas en hänvisning till **Administration > Visualization > Canvas Templates** (se nedan).
  - Bygg en fråga under **Filter** genom att filtrera på seriernas attribut (metadata) så att du får fram den eller de serier du vill visa.
  - Klicka på **Read results**. Under **Read results** listas träffarna med **Series** och **Latest value**.
  - Klicka på **Add as label** för den serie du vill visa. Symbolen placeras på bilden och kan dras till rätt plats.

För att byta serie på ett befintligt value item markerar du det och klickar på **Update query...**. Du kan då ändra filtret, läsa resultat igen och klicka på **Update label**.

==== Hur man väljer canvas template ====

Canvas templates väljs i listan **Canvas Template** högst upp i sidopanelen när ett value item är markerat eller håller på att skapas. Templaten bestämmer:

  * vilken ikon som visas,
  * ikonens färg och storlek,
  * vilka färger cirkeln runt ikonen får vid olika värden (tröskelvärden eller enum-värden),
  * tooltipens utseende, position, antal decimaler och suffix.

Du kan överstyra templatens inställningar för ett enskilt item. Fälten som kan överstyras är **Icon**, **Icon size**, **Icon color**, **Tooltip color**, **Tooltip position**, **Decimals**, **Suffix**, **Permanent tooltip** och **Show designation**. När ett fält är överstyrt visas en återställningsikon bredvid fältet som återgår till templatens värde. Fält som inte är överstyrda följer templaten, så om templaten ändras i administrationen slår ändringen igenom på alla value items som använder den.

Canvas templates definieras under **Administration > Visualization > Canvas Templates**.

==== Tooltip ====

När du håller muspekaren över en symbol visas en tooltip med:

  * seriens beteckning (kan döljas med **Show designation**),
  * senaste värdet med valt antal decimaler och suffix,
  * tidpunkten för värdet.

Tooltipen innehåller även en diagramikon (**Show Series**) som öppnar serien i Analys i en ny flik. Med **Permanent tooltip** visas tooltipen alltid, utan att man behöver hovra.

===== Input item =====

Ett input item är ett inmatningsfält på bilden som skriver ett nytt värde till tidsseriedatabasen. Det används för överstyrningar av system, t.ex. att sätta ett nytt börvärde eller slå på/av en funktion som ett externt system sedan läser från tidsseriedatabasen.

Lägg till ett med **Add input**. Fältet kan vara antingen ett sifferfält eller en på/av-knapp (boolean).

Inställningar i sidopanelen:

^ Inställning ^ Beskrivning ^
| **Input value** | Fältets aktuella värde. Visas som startvärde tills ett värde skrivits. |
| **Placeholder** | Hjälptext som visas när fältet är tomt. |
| **Make Boolean** | Gör fältet till en på/av-knapp i stället för ett sifferfält. Skriver ''1'' (på) eller ''0'' (av). |
| **Default on** | Startläge för en boolean-knapp. |
| **Width** | Fältets bredd i pixlar (48–480). Gäller sifferfält. |
| **Background color** | Fältets bakgrundsfärg. |
| **Font size** | Teckenstorlek. |
| **Attribute Group** | Attributgrupp som bestämmer vilka attribut (taggar) den nya tidsserien ska få. |
| **Additional attributes** | Värden för attributgruppens attribut. Obligatoriska attribut är markerade med ''*'' och måste fyllas i innan widgeten kan sparas. |

==== Så fungerar skrivningen ====

  * I ett sifferfält skriver du ett värde och trycker **Enter**. Endast siffror, minustecken och decimaltecken accepteras.
  * För en boolean-knapp skrivs värdet så fort du slår om knappen.
  * Första gången ett input item skriver ett värde skapas en ny tidsserie med ett unikt UUID och de attribut du angett. Alla efterföljande skrivningar från samma item hamnar i samma serie.
  * När serien skapats låses **Attribute Group** och **Additional attributes** för det itemet, eftersom seriens attribut inte kan ändras i efterhand.
  * En databas-ikon visas i fältet när itemet har en serie. Håll muspekaren över ikonen för att se seriens UUID och kopiera det med kopieringsknappen. UUID:t kan användas i en värdetagg i ett text item eller för att hitta serien i Analys.

Under tiden skrivningen pågår visas en snurrande ikon i fältet. Varje skrivning loggas i auditloggen.

**Obs:**
  * Widgeten måste vara sparad innan ett input item kan skriva värden. Försöker du skriva innan dess visas felet //Save the canvas widget before writing input values//.
  * Du behöver rättighet att spara panelen för att kunna skriva värden.
  * Vid skrivning synkas fältets visade värde med det senast skrivna värdet i databasen, så alla som tittar på panelen ser samma värde.

===== Canvas templates =====

Canvas templates styr hur value items ser ut och definieras centralt under **Administration > Visualization > Canvas Templates**. En template kan användas av många value items i många paneler, vilket gör att du håller symboler och färgkodning enhetliga.

Klicka på **Add Canvas Template** för att skapa en ny, eller **Edit** på en befintlig.

^ Fält ^ Beskrivning ^
| **Template name** | Namn på templaten. Måste vara unikt. |
| **Icon** | Ikon som visas i symbolen. |
| **Icon color** | Ikonens färg. |
| **Tooltip color** | Tooltipens bakgrundsfärg. |
| **Icon size** | Ikonens storlek i pixlar (10–96). |
| **Tooltip position** | Var tooltipen visas i förhållande till symbolen: Top, Bottom, Left eller Right. |
| **Decimals** | Antal decimaler i värdet (0–4). |
| **Suffix** | Text som visas efter värdet, t.ex. ''°C'' eller ''%''. |
| **Permanent tooltip** | Visa tooltipen alltid i stället för bara vid hovring. |
| **Show designation** | Visa seriens beteckning i tooltipen. |
| **Color ranges** | Tröskelvärden som bestämmer cirkelns färg, se nedan. |

==== Color ranges ====

Under **Color ranges** anger du vilka färger symbolen ska få vid olika värden. Klicka på **Add threshold** för att lägga till en rad. Varje rad har **Color**, **Threshold** och **Name**. Namnet visas i widgetens legend.

Templatens typ bestäms automatiskt av hur du skriver tröskelvärdena:

  * **Numerisk template** – alla trösklar är intervall skrivna som ''min-max'', t.ex. ''0-10'', ''10-20'', ''20-100''. Värdet matchas mot det intervall det hamnar i. Minst två intervall krävs och intervallen får inte överlappa varandra. Intervallen sorteras automatiskt när templaten sparas.
  * **Enum-template** – trösklarna är textvärden, t.ex. ''on'', ''off'' eller ''larm''. Seriens värde måste matcha texten exakt. Minst ett värde krävs.

Det går inte att blanda intervall och textvärden i samma template. Om seriens värde inte matchar någon tröskel får cirkeln ikonens färg.

Templates som används i paneler kan inte tas bort. Försöker du ta bort en sådan visas en lista över de paneler (**Panel IDs**) som använder den.

===== Använda widgeten i panelen =====

När panelen visas har canvas-widgeten en egen verktygsrad:

  * **+ / −** – zooma in och ut. När bilden är större än widgeten kan du panorera genom att dra i den.
  * **Pensel** – markeringsverktyg. Dra en ruta över bilden för att markera ett område, t.ex. för att peka på något i en diskussion eller när panelen exporteras som bild. Klicka på penseln igen för att ta bort markeringen.
  * **Uppdatera** – visas när widgeten har value items. Här kan du uppdatera värdena direkt (**Refresh**) eller välja uppdateringsintervall: **1m**, **5m** eller **10m**.
  * **Legend** (listikon) – visas när widgeten har value items med canvas template. Listan visar templaternas tröskelnamn med antal symboler i varje. Klicka på en rad för att visa enbart de symbolerna, och på fler rader för att lägga till dem i urvalet. Klicka på en vald rad igen för att ta bort den ur urvalet; när inget är valt visas alla symboler. Text items och input items påverkas inte av filtret.

I menyn (**⋮**) finns **Fullscreen** och, i redigeringsläge, **Delete**. Pennan öppnar canvas-editorn igen.