Nastavení

Životní cyklus nastavení aplikace

Fáze nastavení

Nastavení aplikace se dělí na 2 fáze. Na Přidání aplikace a Konfiguraci aplikace. Při prvním přidání aplikace na instanci dochází i k vytváření uživatele za aplikaci, prvnímu nastavení práv a poprvé obdržíme token pro komunikaci s naším API. Tyto fáze se v prvních krocích liší, proto je níže máte zakreslené zvlášť pro lepší orientaci. Do fáze Konfigurace se dostaneme, jakmile již jednou úspěšně přidáme aplikaci na instanci a dokončíme její nastavení. Také zde již máme uložený token a nějaký config, který můžeme pomocí tokenu identifikovat. A následně config aplikace pouze upravujeme.

Přidání aplikace

Po kliknutí na tlačítko Přidat u aplikace dochází k Requestu GET a sice na základní url aplikace, odkud jako odpověď dostaneme JSON, pokud je tedy status HTTP 200. Tento JSON obsahuje inicializaci naší aplikace. Strukturu JSONu nalezneme v sekci Inicializace.

Zobrazí se nám zde práva aplikace a při stisku na tlačítko Pokračovat dojde k vytvoření neplnohodnotného uživatele, kterému se nastaví práva. Request se posílá POST, který míří na callback uvedený v naší inicializaci, ze kterého obdržíme token. Tento token potřebujeme pro komunikaci s API. A také podle něho můžeme vyhledat nastavení, které jsme si vytvořili při prvním přidání aplikace, tento token lze použít pro všechny prodejní kanály v naší instanci, ve které je aplikace nastavena.

A vrací se nám JSON, který musí obsahovat parametr ident, což bude pole o dvou prvních. Musíme zde uvést parametr name, který bude obsahovat název aplikace a language, což bude zkratka jazyka naší aplikace. Další parametr bude form, kde si navolíme, jaký typ formuláře chceme na straně Retailysu vygenerovat v prvním kroku nastavení. Tuto volbu učiníme v parametru type, který může obsahovat string, textarea, select, checkbox a link. Parametr name nám určuje název parametru, který se nám bude vracet v dalších Requestech jako pole naplněné informacemi o prodejních kanálech. Ostatní parametry upřesňují nastavení našeho prvku. Jako options uvedeme všechny prodejní kanály, které si načteme přes naše API. Zde je potřeba uvést pole, kde index bude identifikátor prodejního kanálu a hodnota bude název prodejního kanálu.

Jako hodnoty default_value zvolíme stejný formát pole, ale již je zde potřeba uvést pouze prodejní kanály, u kterých byla aplikace již vytvořena, tzn má již nějaký config uložený v databázi.

A nakonec je tu potřeba parametr callback, což bude cesta, která povede na další krok nastavení. Například https://aplikace.cz/config-save, cesta musí vést na adresu aplikace, nemůže vést na jinou doménu.

Příklad JSON odpovědi pro první krok (formulář)

{
	"ident": {
		"name": "Konfigurace aplikace Example",
		"language": "cs"
	},
	"form": [{
		"type": "select",
		"name": "channels",
		"multiple": true,
		"label": "Prodejn\u00ed k\u00e1naly",
		"options": {
			"1": "Prvn\u00ed prodejn\u00ed kan\u00e1l",
			"2": "Druh\u00fd prodejn\u00ed kan\u00e1l"
		},
		"required": true,
		"default_value": 1,
		"placeholder": "Pros\u00edm vyberte alespon jeden prodejn\u00ed kan\u00e1l.",
		"select2": true
	}],
	"callback": "config-save"
}

Po kliknutí na tlačítko Pokračovat se posílá HTTP Request POST, ve kterém se nám vrátí parametr s názvem, který jsme si zvolili v předchozím kroku u parametru form jako name, u nás je to tedy channels, který obsahuje identifikátory prodejních kanálů a parametr token, který používáme pro komunikaci s API.

Poté uložíme data do databáze a pokud bude uložení úspěšné máme dvě možnosti. Buď můžeme konfiguraci dokončit tím, že vrátíme JSON, který bude obsahovat parametr message, kde bude oznámení pro uživatele a parametr state, který bude obsahovat hodnotu success, aby se úspěšně dokončilo nastavení.

 return $this->json(
            [
                'message' => 'Úspěšně nastaveno',
                'state' => 'success',
            ]
        );

A nebo vrátíme snippet, kde vykreslíme šablonu a předáme jí potřebná data, která se nám v ní zobrazí tzn informace o prodejních kanálech, jejich nastavení, případně již uložená data u prodejních kanálů v databázi aplikace. Tento snippet pak vrátíme v JSON formátu, který bude obsahovat parametr snippet a v ní bude celá vykreslená šablona. V této šabloně můžeme využít obyčejného html a také zde můžeme využít styly pomocí Bootstrap 4.

Příklad ve frameworku Symfony s šablonovacím systémem twig

$snippet = $this->renderView('config/save.html.twig', [
        'config' => $config,
        'channelsData' => $channelsData,
        'configChannels' => $configChannels,
]);

return $this->json(
    [
        'snippet' => $snippet,
    ]
);

Data které načteme do šablony následně můžeme v šabloně zobrazit. A také se následně budou posílat na data-url, kterou nesmíme zapomenout někde na konci šablony uvést, která bude obsahovat cestu, kde budeme potřebné informace ukládat do databáze tzn další krok.

<div class="row">
  <div class="col-lg-3 col-xl-2 ">
   <input id="token" type="hidden" name="token" value="{{ config.token }}">
   {% for channelData in channelsData %}
   <div>
     <span>{{channelData.name}}</span>
   </div>
   {% endfor %}
  </div> 
<div id="callbackUrl" data-url="https://aplikace.cz/config-done"></div>

Výsledný snippet může vypadat různě, například může mít formu tabů, přepínacích s jednotlivými prodejními kanály.

Tento cyklus se opakuje do té doby, než se rozhodneme dokončit konfiguraci vrácením JSONU s úspěšnou zprávou.

Po úspěšném nastavení se nám v administraci zobrazí hláška se zeleným pozadím, kterou jsme si nastavili jako hodnotu parametru message, která se nám vrátí na konci funkce, která nám ukládá data z formuláře do databáze aplikace.

Taktéž se nám v administraci v seznamu aplikací u aplikace, kterou jsme právě nastavili změní ikona z Přidat na Konfigurace

Konfigurace Aplikace

Po kliknutí na tlačítko Konfigurace u aplikace dochází k dvěma Requestům. První je methodou GET a směřuje na základní url aplikace, odkud jako odpověď dostane JSON, pokud je status HTTP 200, ve kterém je inicializace aplikace. Strukturu JSONu nalezneme v sekci Inicializace.

Jako druhý Request se posílá POST, který míří na callback uvedený v naší inicializaci, ze kterého obdržíme token. Tento token potřebujeme pro komunikaci s API. A také podle něho můžeme vyhledat nastavení, které jsme si vytvořili při prvním přidání aplikace, tento token lze použít pro všechny prodejní kanály v naší instanci, ve které je aplikace nastavena.

{
	"ident": {
		"name": "Konfigurace aplikace Example",
		"language": "cs"
	},
	"form": [{
		"type": "select",
		"name": "channels",
		"multiple": true,
		"label": "Prodejn\u00ed k\u00e1naly",
		"options": {
			"1": "Prvn\u00ed prodejn\u00ed kan\u00e1l",
			"2": "Druh\u00fd prodejn\u00ed kan\u00e1l"
		},
		"required": true,
		"default_value": 1,
		"placeholder": "Pros\u00edm vyberte alespon jeden prodejn\u00ed kan\u00e1l.",
		"select2": true
	}],
	"callback": "config-save"
}JSON

Práva aplikace a nastavení

Při vstupu do nastavení aplikace můžeme v administraci Retailys vidět záložku Práva aplikace, jedná se o přehled uživatelských práv aplikace, které jsme nastavili v inicializaci na rootovské adrese aplikaci.

V druhé záložce Nastavení bychom se měli dostat na výběr prodejních kanálů, na které chceme aplikaci nastavit, zde můžeme uvést více prodejních kanálů najednou.

Po kliknutí na tlačítko Aktualizovat nastavení se posílá HTTP Request POST, ve kterém se nám vrátí parametr s názvem, který jsme si zvolili v předchozím kroku u parametru form jako name, u nás je to tedy channels, který obsahuje identifikátory prodejních kanálů a parametr token, který používáme pro komunikaci s API.

 return $this->json(
            [
                'message' => 'Úspěšně nastaveno',
                'state' => 'success',
            ]
        );

Příklad ve frameworku Symfony s šablonovacím systémem twig

$snippet = $this->renderView('config/save.html.twig', [
        'config' => $config,
        'channelsData' => $channelsData,
        'configChannels' => $configChannels,
]);

return $this->json(
    [
        'snippet' => $snippet,
    ]
);

<div class="row">
  <div class="col-lg-3 col-xl-2 ">
   <input id="token" type="hidden" name="token" value="{{ config.token }}">
   {% for channelData in channelsData %}
   <div>
     <span>{{channelData.name}}</span>
   </div>
   {% endfor %}
  </div> 
<div id="callbackUrl" data-url="https://aplikace.cz/config-done"></div>