Uživateľské tlačidlo dáva vývojárom aj používateľom možnosť definovať v ABRA Flexi vlastnú akciu vo forme tlačidla. Po jeho stlačení sa zobrazí panel v aplikácii alebo sa otvorí webový prehliadač — v oboch prípadoch s ľubovoľnou webovou stránkou.

Možnosti použitia

Uživateľským tlačidlom je možné zobraziť relevantnú časť intranetového informačného systému, vyhľadať tovar v porovnávači cien, otvoriť príslušnú časť webového rozhrania ABRA Flexi alebo vyvolať akciu cez REST API. Do adresy webovej stránky je možné dynamicky vkladať parametre, napríklad IČO práve upravovanej firmy alebo EAN zobrazeného tovaru.

Spôsob použitia

Parametre tlačidla — text, cieľové URL, umiestnenie v aplikácii — sa zapíšu do jeho definície, súboru vo formáte XML. Vytvorená definícia sa do ABRA Flexi načíta importom z XML a pri opätovnom pripojení k firme je tlačidlo súčasťou používateľského rozhrania, či už klientskej aplikácie, alebo webového rozhrania.

Tlačidlá sú uložené v evidencii custom-button, takže sa dajú aj bežne čítať cez API:

GET https://demo.flexibee.eu/c/demo/custom-button.json?detail=full

Definícia uživateľského tlačidla

Každý prvok môže byť v definícii jedného tlačidla uvedený nanajvýš raz (výnimkou je prvok id). Súbor môže obsahovať definícií viac; pri viacnásobnom uvedení toho istého tlačidla sa jednotlivé definície považujú za jeho aktualizáciu a fakticky sa prejaví tá posledná. Nevyhovujúca definícia bude odmietnutá už pri importe.

Prvok	Povinný	Význam
`id`	áno	Identifikátor tlačidla.
`url`	áno	Adresa, ktorá sa po stlačení otvorí.
`title`	áno	Text zobrazený na tlačidle.
`description`	áno	Detailný popis zobrazovaný v bubline.
`evidence`	áno	Evidencia, v ktorej sa tlačidlo zobrazuje.
`location`	áno	Umiestnenie na prehľade alebo na karte záznamu.
`browser`	nie	Prehliadač, v ktorom sa URL otvorí.

id

Identifikátory záznamu slúžia na pridelenie kódu pri vytváraní a na presné určenie tlačidla pri jeho neskoršej aktualizácii či mazaní. Použiť je možné:

Kód (skratku) — používateľské označenie, prefix code:
Externý identifikátor — identifikátor z externej aplikácie, prefix ext:
Identifikátor ABRA Flexi — číselný nemenný identifikátor prideľovaný aplikáciou, bez prefixu

Pri vytváraní tlačidla musí byť prvok uvedený s kódom.

url

Určuje adresu webovej stránky či sieťového zdroja, ktorá sa po stlačení tlačidla otvorí. Uvádzajte ju v úplnom, absolútnom tvare — so schémou a doménovou adresou servera, napríklad https://www.flexibee.eu/.

⚠️ URL zadávajte v <![CDATA[ … ]]>, aby prítomnosť znaku & nespôsobila nevalidné XML.

🚨 Schéma file na prístup k lokálne uloženým súborom podporovaná nie je — definícia s file:// sa pri importe odmietne chybou restrictedProtocol.

Pri konštrukcii URL je možné uviesť premenné, ktoré za behu aplikácie vyhodnotí FreeMarker a zaistí odovzdanie hodnôt z aplikácie. Napríklad zápis ${object.ic} vráti IČO partnera v adresári. Reťazec object je v názve premenných povinný — odkazuje sa ním na aktuálny záznam zobrazenej evidencie. Zoznam dostupných atribútov jednotlivých evidencií nájdete vo webovom rozhraní na adresách ako /flexi/{firma}/adresar/properties.

Premenná	Hodnota
`object`	Aktuálny záznam — jeho vlastnosti sa uvádzajú za bodkou, napríklad `${object.ic}`.
`objectIds`	Zoznam ID vybraných záznamov oddelených čiarkou. Pri veľkom počte záznamov sa nahrádza parametrom `data-url` — pozri nižšie.
`user`	Aktuálne prihlásený používateľ; dostupné vlastnosti pozri `/flexi/{firma}/uzivatel/properties`.
`url`	Úplná adresa objektu, na ktorom bolo tlačidlo vyvolané — napríklad `https://demo.flexibee.eu/c/demo/adresar/1`.
`companyUrl`	Adresa API rozhrania firmy — napríklad `https://demo.flexibee.eu/c/demo/`.
`flexiUrl`	Adresa webového rozhrania firmy — napríklad `https://demo.flexibee.eu/flexi/demo/`.
`evidence`	Meno evidencie, na ktorej je tlačidlo umiestnené.
`authSessionId`	Autentizačný token k aktuálnemu sedeniu používateľa. Počas platnosti sedenia ním možno autentizovať dotazy — pozri Autentizácia.
`customerNo`	Číslo zákazníka zodpovedajúce licencii.
`licenseId`	Identifikátor licencie.
`language`	Jazyk, v ktorom aplikácia beží — `cs`, `sk`, `en`, `de`.

⚠️ Premenné object a objectIds sa vzájomne vylučujú.

evidence

Určuje evidenciu, prípadne konkrétnu väzbu (reláciu) evidencie, pre ktorú má byť tlačidlo zobrazované — napríklad adresar pre obchodných partnerov alebo faktura-vydana pre vydané faktúry. Vo variante pre väzby potom napríklad faktura-vydana-polozka pre položky vydanej faktúry či majetek-zapujcka pre výpožičky v evidencii majetku.

Pre evidencie použite reťazec, ktorý sa objavuje v URL webového rozhrania. Zoznam všetkých evidencií vráti:

GET https://demo.flexibee.eu/c/demo/evidence-list.json

Pre väzby evidencií použite názov evidencie doplnený o pomlčku a reťazec väzby, ktorý zistíte na prehľade väzieb danej evidencie:

GET https://demo.flexibee.eu/c/demo/cenik/relations.json

Neexistujúca evidencia sa pri importe odmietne chybou validace.neplatnyCiselnik.

location

Určuje, či sa tlačidlo zobrazí na prehľade záznamov, alebo na karte konkrétneho záznamu:

Hodnota	Umiestnenie
`list`	Prehľad záznamov.
`detail`	Karta konkrétneho záznamu.

Ak má byť tlačidlo dostupné na prehľade záznamov aj na karte konkrétneho záznamu, je nevyhnutné pripraviť dve definície, ktoré sa budú líšiť hodnotou location.

title

Text zobrazený na tlačidle.

description

Detailný popis tlačidla zobrazovaný v bubline. Je povinný — bez neho import skončí chybou validace.notNull.

browser

Určuje prehliadač, v ktorom sa URL otvorí. Interný prehliadač sa zobrazí rýchlejšie, ale nemusí obsahovať používateľské prispôsobenie a dáta — heslá, cookies, dáta formulárov, navštívené odkazy. Externý prehliadač je prostredím, na ktoré je používateľ zvyknutý.

Hodnota	Prehliadač
`automatic`	Interný prehliadač; ak nie je dostupný, otvorí sa externý. Predvolená hodnota.
`desktop`	Externý prehliadač.

Vo webovom rozhraní je nastavenie prvku browser z podstaty ignorované. Neplatná hodnota pri browser aj location sa odmietne chybou validace.notAvailableValue.

Príklad vytvorenia

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button>
    <id>code:JUSTICECZ</id>
    <url><![CDATA[https://or.justice.cz/ias/ui/rejstrik-$firma?ico=${object.ic}&jenPlatne=VSECHNY]]></url>
    <title>Obch. rejstřík</title>
    <description>Zobraz záznam firmy v obchodním rejstříku justice.cz</description>
    <evidence>adresar</evidence>
    <location>detail</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Príklad aktualizácie tlačidla

Ak v definícii uvediete jednoznačnú identifikáciu existujúceho tlačidla, môžete ho aktualizovať. ABRA Flexi umožňuje čiastočné aktualizácie záznamov, takže pri zmene adresy obchodného registra stačí tlačidlo identifikovať a uviesť novú hodnotu URL:

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button>
    <id>code:JUSTICECZ</id>
    <url><![CDATA[https://or.justice.cz/ias/ui/rejstrik-$firma?ico=${object.ic}&jenPlatne=VSECHNY&polozek=500]]></url>
  </custom-button>
</winstrom>

Príklad zmazania tlačidla

Na zmazanie existujúceho tlačidla slúži atribút action — viac o jeho použití v článku Vykonávanie akcií:

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button action="delete">
    <id>code:JUSTICECZ</id>
  </custom-button>
</winstrom>

Dlhé URL a parameter data-url

Pri veľkom počte vybraných záznamov by URL s vymenovanými ID mohla prekročiť povolenú dĺžku. V takom prípade ABRA Flexi zoznam ID uloží do dočasného úložiska a do výslednej URL namiesto premennej ${objectIds} vloží parameter data-url, ktorý odkazuje na endpoint, odkiaľ je možné úplný zoznam ID stiahnuť.

Pre šablónu http://example.com/action?ids=${objectIds} tak môže výsledná adresa vyzerať takto:

http://example.com/action?ids=data-url&data-url=https%3A%2F%2Finstance.flexibee.eu%2Fc%2Fmojefirma%2Fcustom-button%2Fdata%3Fid%3D2f1c…

Stiahnutie zoznamu ID

Dočasne uložený zoznam ID sa sťahuje metódou GET na adresu z parametra data-url:

GET https://demo.flexibee.eu/c/demo/custom-button/data?id=2f1c8b7e-1a2b-4c3d-9e0f-abcdef012345

Odpoveď má Content-Type: application/json;charset=utf-8:

{
  "objectIds": [101, 102, 103, 104, 105]
}

Záznam je dostupný iba používateľovi, ktorý ho vytvoril, a len počas doby svojej platnosti. Po expirácii — alebo pre iného používateľa — vracia endpoint 404 s kódom adresaNeplatna. Vynechaný parameter id skončí chybou 400 missing_param_exception.

Konfigurácia dočasného úložiska

Správanie dočasného úložiska sa riadi voľbami v konfigurácii servera flexibee-server.xml (kde ho nájsť):

Voľba	Význam	Predvolené
`objectStore.type`	Typ úložiska.	`LOCAL` (lokálny súborový systém)
`objectStore.localDirectory`	Adresár na serveri, do ktorého sa dáta ukladajú pri type `LOCAL`.	—
`objectStore.defaultTtlMinutes`	Doba platnosti dočasného záznamu v minútach.	`60`
`objectStore.maxUrlLength`	Maximálna dĺžka URL, pri jej prekročení sa použije `data-url`.	`2000`

Súvisiace

Sorodni članki

Používateľské tlačidlo