LARPBuilder Wiki
Page
  • Zobrazit stránku
  • Starší verze
  • Zpětné odkazy
  • Nahoru
    • Site
  • Poslední úpravy
  • Správa médií
  • Mapa stránek
    • User

    Page tools

  • Zobrazit stránku
  • Starší verze
  • Zpětné odkazy
  • Nahoru

    • Site tools

  • Poslední úpravy
  • Správa médií
  • Mapa stránek

    • User tools
    Historie:

    Rozdíly

    Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.

    Odkaz na výstup diff

    Obě strany předchozí revizePředchozí verze
    Následující verze    		Předchozí verze
    cs:api [2025/03/03 00:31] – admincs:api [2025/04/05 13:49] (aktuální) – [Jak vložit formulář do WordPress (nebo jiného CMS)] admin
    Řádek 1: Řádek 1:
    -====== Úvod ====== +====== API ====== 
    -LARP Builder poskytuje REST API, které umožňuje externě spravovat data LARP aplikace. Konkrétně endpoint **Players** slouží k práci s hráči – umožňuje získat seznam hráčů, detail konkrétního hráče a přidávat nové hráče do systému. API tak lze využít například pro registrační formulář na vlastních webových stránkách nebo pro integraci s jinými nástroji.+LARP Builder poskytuje endpoint **Players**, který slouží k práci s hráči – umožňuje získat seznam hráčů, detail konkrétního hráče a přidávat nové hráče do systému. API tak lze využít například pro registrační formulář na vlastních webových stránkách (WordPress, Drupal, statické stránky atd.) nebo pro integraci s jinými nástroji.
      
     Pro přístup k API je vyžadována autorizace. Jsou podporovány dva hlavní mechanismy: Pro přístup k API je vyžadována autorizace. Jsou podporovány dva hlavní mechanismy:
       - **API klíč (API Key)**: Každý projekt v LARP Builderu má vlastní API klíč. Ten musí být součástí každého požadavku (v hlavičce, formulářových datech či JSONu).   - **API klíč (API Key)**: Každý projekt v LARP Builderu má vlastní API klíč. Ten musí být součástí každého požadavku (v hlavičce, formulářových datech či JSONu).
    -  - **Ověření zdroje požadavku (Origin)**: Server kontroluje, z jaké domény požadavek přichází. Pokud doména není povolená v nastavení projektu, server volání odmítne (//CORS a bezpečnost//).  +  - **Ověření zdroje požadavku (Origin)**: Server kontroluje, z jaké domény požadavek přichází. Pokud doména není povolená v nastavení projektu, server volání odmítne (//CORS a bezpečnost//).
       - **(Volitelně) Basic Auth**: Pro přístup k některým citlivějším částem API (nebo pro volání z nástrojů jako Postman) je vyžadováno přihlášení administrátora (email a heslo). Tento způsob umožňuje serveru ověřit, že uživatel má dostatečná práva k projektu.   - **(Volitelně) Basic Auth**: Pro přístup k některým citlivějším částem API (nebo pro volání z nástrojů jako Postman) je vyžadováno přihlášení administrátora (email a heslo). Tento způsob umožňuje serveru ověřit, že uživatel má dostatečná práva k projektu.
      
     ====== Použití API na stránkách akce (HTML kód) ====== ====== Použití API na stránkách akce (HTML kód) ======
    -Součástí integrace je  použití **Players** endpointu pomocí webového formuláře (např. registrační formulář pro hráče). +Níže je ukázka **Players** endpointu s webovým formulářem (např. registrační formulář pro hráče). V HTML formuláři se vyplní údaje o hráči (jméno, příjmení, email atd.) a spolu s nimi se odešle také API klíč. Odeslání probíhá ne klasickým //submit//, ale JavaScriptem, který zavolá API endpoint a data mu předá.
    - +
    -**Princip formuláře**   +
    -V HTML formuláři se vyplní údaje o hráči (jméno, příjmení, email atd.) a spolu s nimi se odešle také API klíč. Odeslání probíhá ne klasickým //submit//, ale JavaScriptem, který zavolá API endpoint a data mu předá.+
      
     <code html> <code html>
    Řádek 26: Řádek 23:
      
         <!-- ... další předdefinovaná nepovinná pole ... -->     <!-- ... další předdefinovaná nepovinná pole ... -->
    -        <label for="character_ids">Postava:</label> +    <!-- (výběr postavy, různé velikosti, poznámky atd.) -->
    -        <select name="character_ids" id="character_ids"> +
    -            <option></option> +
    -            <option value="160">Arwen</option> <!-- ... seznam postav podle jejich ID ... --> +
    -        </select>+
      
    -        <label for="zazitky">To nejdůležitější: Tři věty, co chceš hrát:</label> +    <!-- Skrytá povinná pole s API klíčem a dalšími parametry --> 
    -        <textarea id="zazitky" name="zazitky"></textarea>+    <input type="hidden" id="api_key" name="api_key" value="VAŠ_API_KLÍČ" /> 
     +    <input type="hidden" id="lang" name="lang" value="cs">  
     +    <input type="hidden" id="alerts_enabled" name="alerts_enabled" value="0"> 
     +    <input type="hidden" id="form_submit" name="form_submit" value="1">
      
    -        <label for="cinnosti">To nejdůležitější: Tři věty, co chceš na hře dělat:</label> +    <button type="submit">Odeslat</button> 
    -        <textarea id="cinnosti" name="cinnosti"></textarea>+</form>
      
    -        <label for="size_head">Obvod hlavy</label> +<!-- Potřebné skripty --> 
    -        <input type="number" id="size_head" name="size_head" min="0" max="999" value="0">cm+<script src="https://larpbuilder.cz/api/js/jquery-3.7.1.slim.min.js"></script> 
     +<script src="https://larpbuilder.cz/api/js/apiControl.js"></script> 
     +</code>
      
    -        <label for="size_breast">Obvod hrudi</label> +**Poznámka:**   
    -        <input type="number" id="size_breast" name="size_breast" min="0" max="999" value="0">cm+  - `api_key` = **API klíč** získaný z LARP Builderu (v nastavení konkrétního projektu).   
     +  - V LARP Builderu je nutné **přidat doménu** vašich stránek mezi povolené (např. `mojedomena.cz`), aby server akceptoval požadavky z této domény. 
     +  - Pokud chcete aby formulář napsal že registrace porběhla úspěšně či neúspěšně nastavte hodnotu "value" u alerts_enabled na 1 (<input type="hidden" id="alerts_enabled" name="alerts_enabled" value="0">) 
     +  - Můžete zmenit také jazyk jakým bude formulář odpovídat změněním cs v parametru lang jazyky na výběr jsou cs: čeština, en: angličtina, de: němčina, fr: francouzština, es: španělština 
     +  - Parametr form_submit říká zda se má po odeslání do LB API formulář snažit o odeslání také jako by šlo oběžný formulář na stránkách (vhodné třeba pro další zpracování formulářových dat do vlastní databáze)
      
    -        <label for="size_waist">Obvod pasu</label> +**Jak to funguje:**   
    -        <input type="number" id="size_waist" name="size_waist" min="0" max="999" value="0">cm+  - JavaScript v `apiControl.js` zachytí odeslání formuláře, sebere všechny údaje (včetně `api_key`) a pošle je metodou **POST** na `https://larpbuilder.cz/api/players/`.   
     +  - Server zkontroluje, zda doména (Origin) je povolená a API klíč je platný. Pokud ano, vytvoří nového hráče a vrátí JSON s výsledkem.  
      
    -        <label for="size_hips">Obvod boků</label> +====== Generování embed kódu formuláře vytvořeného v LARPBuilderu ====== 
    -        <input type="number" id="size_hips" name="size_hips" min="0" max="999" value="0">cm+V sekci **Seznam formulářů** je u již vytvořených formulářů k dispozici akce **Zobrazit HTML kód**, která automaticky generuje kompletní embed kód formuláře na základě uložených dat. Tento kód obsahuje kompletní HTML dokument s inline styly, speciálními typy polí jako je **scale** (bodovací škála), **paragraph** (odstavec) či **button** (tlačítko) a skrytými poli s aktuálním API klíčem který je uložitelný jako samostatná .html stránka nebo vložitelný například do Wordpressu bez nutnosti se více starat o HTML kód.
      
    -        <label for="size_clothes">Konfekční velikost (např. trička)</label> +=== Výhody === 
    -        <select name="size_clothes" id="size_clothes"> +  - **Samostatnost:** Embed kód je kompletní a nevyžaduje žádné další nastavení a skripty (kromě minimálně potřebných skriptů jquery a apiControl.js). 
    -            <option></option> +  - **Aktualizace:** Možnost dynamického doplnění selectů z databáze zajistí, že na webu bude vždy aktuální výběr. 
    -            <option value="XS">XS</option> +  - **Kompatibilita:** Kód je vhodný pro různé CMS, například pro WordPress, kde jej lze vložit pomocí HTML bloku nebo shortcodu. 
    -            <option value="S">S</option> +  - **Jednoduchost:** Stačí zkopírovat vygenerovaný kód a vložit jej na webovou stránku.
    -            <option value="M">M</option> +
    -            <option value="L">L</option> +
    -            <option value="XL">XL</option> +
    -            <option value="2XL">2XL</option> +
    -            <option value="3XL">3XL</option> +
    -            <option value="4XL">4XL</option> +
    -            <option value="5XL">5XL</option> +
    -            <option value="6XL">6XL</option> +
    -            <option value="7XL">7XL</option> +
    -            <option value="8XL">8XL</option> +
    -            <option value="9XL">9XL</option> +
    -        </select>+
      
    -        <label for="size_type">Typ</label> +====== Jak vložit formulář do WordPress (nebo jiného CMS) ====== 
    -        <select name="size_type" id="size_type"> +Pokud chcete snadno vložit vygenerovaný HTML kód formuláře do WordPressu, stačí postupovat následovně:
    -            <option></option> +
    -            <option value="F">Dámské</option> +
    -            <option value="M">Pánské</option> +
    -        </select>+
      
    -        <label for="avatar">Avatar</label> +**Zkopírujte embed kód:**  Použijte postup tak jak je napsán o odstavec výše (tento kód obsahuje všechny potřebné části a je připravený ke kopírování), nebo si vytvořte vlastní formulář a připojte k němu nutná pole a potřebné javaskripty. 
    -        <input type="file" id="avatar" name="avatar" accept="image/jpeg, image/png, image/gif"> +
    -    +
      
    -    <!-- Skrytá povinná pole s API klíčem a dalšími parametry --> +**Vložte kód do příspěvku:**  Ve WordPressu přejděte na tvorbu nebo úpravu příspěvku. V editoru (Gutenberg) přidejte blok „Vlastní HTML“ a do něj vložte zkopírovaný embed kód. Pokud používáte klasický editor, přepněte na záložku HTML a vložte kód přímo tam.
    -    <input type="hidden" id="api_key" name="api_key" value="VAŠ_API_KLÍČ" /> +
    -    <input type="hidden" id="lang" name="lang" value="cs"> <!-- Skryté pole pro jazyk cs (češtna) en (english) --> +
    -    <input type="hidden" id="alerts_enabled" name="alerts_enabled" value="0"> <!-- Skryté pole pro povolení nebo zakázání alertů --> +
    -    <input type="hidden" id="from_submit" name="from_submit" value="1"> <!-- Skryté pole pro povolení nebo zakázání alertů -->+
      
    -    <button type="submit">Odeslat</button> +**Uložte a publikujte:** Uložte změny a publikujte příspěvek. Formulář by se měl zobrazit přesně tak, jak byl vygenerován – s vlastními styly a funkcemi pro odeslání dat přes API.
    -</form> +
    -<script src="https://larpbuilder.cz/api/js/jquery-3.7.1.slim.min.js"></script> +
    -<script src="https://larpbuilder.cz/api/js/apiControl.js"></script> +
    -</code>+
      
    -Důležité je, aby vaše doména s registrací byla stejná jako ta, která je v LARP Builderu povolená pro daný projekt.+** Otestování**: Otevřete stránku s formulářem, vyplňte jej a klikněte //Odeslat//. Po úspěchu se v administraci LARP Builderu objeví nový hráč s vyplněnými údaji. Pokud dojde k chybě (např. špatná doména, chybějící povinné pole), zobrazí se chybová hláška (v případě že je <input type="hidden" id="alerts_enabled" name="alerts_enabled" value="1"> jinak se chybové hlášení nezobrazí). 
     + 
     +Tento postup nevyžaduje žádné složité nastavení ani zásahy do šablony. Stačí zkopírovat hotový kód a vložit jej na stránku. WordPress se postará o zobrazení kódu bez zásahu do dalších souborů či nastavení. 
     + 
     +**Tip:** Pokud se kód HTML a `<script>` v klasickém WordPress editoru //nezobrazí správně// nebo se //zahodí//, použijte místo toho blok //Vlastní HTML// (v novém Gutenberg editoru), případně shortcody v Code Snippets.   
     + 
     +===== Kde získám API klíč ===== 
     +    - V administraci LARP Builderu otevřete daný projekt.   
     +    - Přejděte do sekce //Nastavení projektu//.   
     +    - Najděte **API klíč** (obvykle v dolní části nastavení) a zkopírujte jej.   
     +    - Zároveň v této sekci přidejte //doménu//, ze které budete formulář volat (např. `moje-stranka.cz`), a uložte změny.
      
     ====== Použití API v Postmanu ====== ====== Použití API v Postmanu ======
    Řádek 101: Řádek 88:
       - **Autorizace**:     - **Autorizace**:  
         - V //Headers// přidejte: ''AuthorizationKey: Bearer <nowiki><API_KLÍČ></nowiki>''       - V //Headers// přidejte: ''AuthorizationKey: Bearer <nowiki><API_KLÍČ></nowiki>''  
    -    - Pokud voláte z Postmanu a nechcete řešit povolenou doménu, zadejte //Basic Auth// s přihlašovacími údaji administrátora (v záložce ''Authorization'').+    - Pokud voláte z Postmanu a nechcete řešit povolenou doménu, použijte //Basic Auth// s přihlašovacími údaji administrátora (v záložce ''Authorization''). V Basic Auth vyplníte //Username = váš email// a //Password = vaše heslo// používané pro LARP Builder.  
       - **Očekávaný výsledek**: JSON seznam hráčů (pole objektů). Pokud žádní hráči nejsou, vrátí se prázdné pole.   - **Očekávaný výsledek**: JSON seznam hráčů (pole objektů). Pokud žádní hráči nejsou, vrátí se prázdné pole.
      
    Řádek 114: Řádek 101:
       - **URL**: ''https://larpbuilder.cz/api/players/''     - **URL**: ''https://larpbuilder.cz/api/players/''  
       - **Tělo**: JSON (//raw body - application/json//) nebo //form-data// s požadovanými poli (např. ''firstname'', ''lastname'', ''email''). Minimální požadovaná jsou jméno, příjmení, email.     - **Tělo**: JSON (//raw body - application/json//) nebo //form-data// s požadovanými poli (např. ''firstname'', ''lastname'', ''email''). Minimální požadovaná jsou jméno, příjmení, email.  
    -  - **Hlavičky**: Opět ''AuthorizationKey: Bearer <nowiki><API_KLÍČ></nowiki>''. Pokud nejste na povolené doméně, použijte v Postmanu i Basic Auth.  +  - **Hlavičky**: Opět ''AuthorizationKey: Bearer <nowiki><API_KLÍČ></nowiki>''. Pokud nejste na povolené doméně, použijte v Postmanu i Basic Auth (stejný postup jako výše).  
       - **Očekávaný výsledek**: ''{"success":"Player added successfully"}'' (HTTP 200) nebo chybová hláška (HTTP 4xx/5xx).   - **Očekávaný výsledek**: ''{"success":"Player added successfully"}'' (HTTP 200) nebo chybová hláška (HTTP 4xx/5xx).
      
    Řádek 128: Řádek 115:
     ====== Závěr ====== ====== Závěr ======
     API LARP Builderu pro **Players** vám umožní integrovat správu hráčů do vlastních stránek a nástrojů. Základem je **API klíč** a volání z povolené domény (nebo Basic Auth pro administrátory).   API LARP Builderu pro **Players** vám umožní integrovat správu hráčů do vlastních stránek a nástrojů. Základem je **API klíč** a volání z povolené domény (nebo Basic Auth pro administrátory).  
    -Při implementaci se zaměřte na: 
    -  - Správné nastavení hlaviček (''AuthorizationKey''),   
    -  - Ošetření chybových stavů,   
    -  - Bezpečné ukládání API klíče (neprozrazujte jej veřejně).   
      
    -Doporučujeme nejprve vše otestovat v Postmanu (GET/POST požadavky), a poté nasadit do produkčního prostředí s ohledem na bezpečnost a spolehlivost. Pokud narazíte na potíže, hlášky v odpovědích JSON většinou napoví, kde je problém.  +**Stručný postup**: 
     +  - V administraci LARP Builderu: Získat API klíč a **přidat doménu** mezi povolené.   
     +  - Na svém webu (např. WordPress): Vložit HTML formulář s `api_key` a připojit JavaScript `apiControl.js`.   
     +  - Otestovat funkčnost (ideálně i v Postmanu).   
     + 
     +Po úspěšném odeslání se v LARP Builderu objeví nově přidaný hráč. Pokud narazíte na potíže, pomůže vám ladění v prohlížeči (konzole) nebo v Postmanu – chyby se vracejí v JSON odpovědích. Hodně štěstí s integrací!
      
    cs/api.1740958297.txt.gz · Poslední úprava: 2025/03/03 00:31 autor: admin