Prázdný¶

Download	Sources
not relevant	https://github.com/pluginsGLPI/empty

Tento zásuvný modul… nic nedělá. Opravdu!

Toto je navrženo jako startovní bod pro psaní zásuvných modulů, se skutečně minimálními výchozími užitečnými skripty a pár radami. Pokud hledáte co je možné v zásuvných modulech dělat, podívejte se na zásuvný modul pro ukázku.

Vytvořit nový zásuvný modul¶

Je poskytován nástroj-skript pro vytváření nových zásuvných modulů – plugin.sh. Vyvolává se s názvem zásuvného modulu, verzí a volitelně popisem umístění, ve kterém chcete, aby chcete byl vytvořen:

$ ./plugin.sh MyGreatPlugin 0.0.1

Skript sanuje a převede na malá písmena poskytnutý název, zkopíruje soubory šablon do nové složky a udělá nějaká nahrazení.

Použitím skriptu bez parametru cíle, je vytvořena složka vašeho zásuvného modulu, mygreatplugin hned vedle jeho vlastní složky. Jinak by vytvořil novou složku v zadaném umístění:

$ ./plugin.sh MyGreatPlugin 0.0.1 /path/to/glpi/plugins/

Aktualizovat stávající zásuvný modul¶

Neexistuje automatizovaný způsob, jak aktualizovat stávající zásuvný modul, protože by bylo příliš mnoho případů, které podchytit. Ale nebojte se, postup je velmi jednoduchý ;)

Použití prázdných funkcí je snadné jako vytvoření několika souborů:

composer.json,
.travis.yml,
Robofile.php,
.gitignore.

Pokud doposud nemáte soubor s nastavením pro composer nebo travis, je možné jednoduše zkopírovat ty z prázdného zásuvného modulu. Pokud už máte; do composer.json přidejte:

{
  "minimum-stability": "dev",
  "prefer-stable": true
}

A poté spusťte composer require glpi-project/tools.

V souboru s nastaveními pro travis stačí přidat CS volání:

script:
  - vendor/bin/robo --no-interaction code:cs

Do souboru .gitignore přidejte následující:

dist/
vendor/
.gh_token
*.min.*

Ohledně souboru s nastaveními Robo.li, mějte na paměti, že ten obsažený v prázdném zásuvném modulu je poněkud specifický a bude ho proto třeba upravit aby vše fungovalo. Viz další informace níže.

A nakonec, protože projekt tools vám poskytne některé funkce, můžete odebrat duplikované skripty-nástroje (soubory jako třeba release, extract_template.sh, …) které by se nacházely ve vašem zásuvném modulu.

Funkce¶

Standardy zápisu zdrojových kódů¶

Sady pravidel GLPI PHPCodeSniffer jsou poskytovány jako vendor/glpi-project/coding-standard/GlpiStandard/.

Pro kontrolu standardu zápisu zdrojových kódů stačí použít Robo.li úlohu code:cs:

$ ./vendor/bin/robo code:cs

Poznámka

Výše uvedený příkaz bude ignorovat vendor a bude spuštěný na stávající složce.

Pokud chcete přizpůsobit seznam ignorovaného nebo kontrolované složky, stačí přepsat $csignore a/nebo $csfiles v souboru RoboFile.php zásuvného modulu:

<?php

class RoboFile extends Glpi\Tools\RoboFile
{
   protected $csignore = ['/vendor/', '/lib/'];
   protected $csfiles  = ['./', 'setup.php.tpl']
   [...]
}

Automatizované kontroly¶

Pro pohodlí je poskytován také soubor .travis.yml, který je nastavený na:

zkontrolovat dodržení standardu zápisu zdrojových kódů
spustit na více různých nastaveních

Pro aktivaci automatizovaných testů je i tak třeba zapnout travis-ci sestavení z webové stránky.

Soubor .travis.yml lze samozřejmě poladit; je možné přidat jednotkové testy, vytvářet/aktualizovat databázi, zapnout upozorňování, atd. Více informací viz dokumentace k Travis-CI.

Sloučení CSS a JS¶

Varování

Zakázáno od 0.1.13, protože libs použitý od Robo jsou zastaralé a nelze je nahradit.

Je poskytován pohodlný skript, využívající Robo.li. Soubor RoboFile.php je prázdná třída které rozšiřuje Glpi\Tools\RoboFile (poskytovanou závislostí glpi-project/tools) ve které si můžete nastavit své vlastní věci.

Tímto způsobem je možné velmi snadno aktualizovat společný soubor a přitom vaše vlastní úlohy zůstanou, jak jsou.

Pro získání potřebných knihoven bude třeba nainstalovat composer a pak spustit:

$ composer install -o

Zde jsou k dispozici tři cíle:

minify které minifikuje všechny CSS a JS soubory (viz níže),
minify:css které minifikuje všechny tabulky css stylů ve složce css zásuvného modulu, vytvoří verzi``.min.css`` vedle původního souboru,
minify:js které minifikuje všechny javascript soubory ve složce js zásuvného modulu, vytvoří verzi .min.js vedle původního souboru.

Stačí zvolit cíl a spustit něco jako:

$ ./vendor/bin/robo minify:css

Poznámka

Mějte na paměti, že zkompilované soubory by neměly být nahrávány do zdrojů ve vašem repozitáři. Pro minifikaci souborů slouží proces vydávání.

Nezapomeňte přizpůsobit své skripty tak, aby načítaly minifikované verze (pokud jsou k dispozici) a náhradně ty původní :)

U GLPI 9.2; se není třeba starat o načítání minifikovaných souborů při použití háčků add_css a add_javascript! Jen je třeba nevyvolávat minified skripty; a GLPI použije minified verzi pokud existuje a pokud není v režimu DEBUG (ladění).

Překlady¶

GLPI a zásuvné moduly pro něj používají pro překlady gettext. Aby to fungovalo, je třeba několika kroků:

1 přeložitelné řetězce je třeba vytáhnout ze souborů se zdrojovými kódy, podle toho bude vytvořen nebo aktualizován POT soubor, 2 PO soubory je třeba vytvořit nebo aktualizovat z POT souboru, 3 PO soubory je třeba přeložit, 4 MO soubory je třeba sestavit z nejnovějších PO.

Ve složce vendor/bin naleznete skript extract_template.sh. Je navržen pro extrakci přeložitelných znaků ze zdrojových kódů (viz první bod výše).

Jakmile byl spuštěný, bude vytvořen/aktulizován soubor locale/mygreatplugin.pot.

Pro druhý a třetí krok, bude třeba rozhodnout. Pro aktualizaci PO souborů je možné použít nástrojů gettext a přeložit je vyhrazeným nástroje, jako třeba poedit; nebo můžete použít online překladový systém jako Transifex nebo Zanata. GLPI samotné a mnoho existujících zásuvných modulů je nyní překládáno na Transifex.

Jakmile zaktualizujete PO soubory, bude třeba je zkompilovat do MO souborů. Můžete to spustit ručně, skript pro vydávání je zkompiluje i tak; viz sekce kompilace MO souborů.

Script pro vydání¶

Skript pro vydání se nachází v vendor/bin/plugin-release. Toto je „jednoduchý“ Python skript; stačí mít nainstalovaný Python (ve většině linuxových distribucí je ve výchozím stavu nainstalovaný).

Varování

Uvědomte si, že uvolňovací skript je kompatibilní, pouze pokud používáte sémantické verzování!

S pouze výchozími parametry se skript pokusí získat nejnovější štítek ve vašem git repozitáři, přidat potřebné součásti od třetích stran a vytvořit Vydání na github projektu:

$ ./vendor/bin/plugin-release
Do you want to build version 1.9.5? [Yes/no] y
Building glpi-order-1.9.5...
Archiving GIT tag 1.9.5
Adding vendor libraries
$ ls dist
glpi-order-1.9.5.tar.bz2  glpi-order-1.9.5.tar.bz2.asc

Požadavky¶

Je třeba mít nainstalovaný interpret jazyka python a následující moduly:

termcolor,
gitdb,
github (pro zjištění existujících verzí také v konceptech, a vytvoření github vydání), pokud nepoužijete volbu --nogithub

Pro zobrazení nápovědy ke scriptu ho spusťte takto ./vendor/bin/plugin-release -h.

Proces¶

Proces vydání pro vás udělá následující úkoly:

zkontrolovat zda je konstanta verze stejná jako štítek který požadujete;
zkontrolovat zda verze v XML souboru této webové stránky je stejná jako štítek který požadujete;
zkontrolujte zda vydání už existuje, místně a vzdáleně (předpokládejme že projekt je hostován v organizaci pluginsGLPI a vydání je veřejné);
udělejte git archive umístění která nejsou vynechány (.git, tools, tests, …);
pokud nějaké, nainstalujte součásti, které composer potřebuje;
pokud nějaké, zkompilujte své MO soubory;
pokud nějaké, zkompilujte své tabulky CSS stylů a soubory Javascript (pomocí Robo.li);
vytvořte archiv s vydáním, obsahující toto vše; který bude k dispozici ve složce dist;
podepsat archiv pomocí GPG

Poznámka

Standardní proces vydávání nebude fungovat přímo na vašich souborech, udělá před tím kopii složky v dist/src. Jedinou výjimkou je volba kompilace MO.

Pro kontrolu zda je vše v pořádku před skutečným vydáním; vytvořte štítek a spusťte ./vendor/bin/plugin-release -C před push svého štítku. Tímto způsobem bude schopní opravit případné problémy a znovuvytvořit štítek místně (pamatujte, že zveřejněné štítky by nikdy neměly být odebírány).

Kompilace MO souborů¶

Proces vydávání automaticky zkompiluje každý PO soubor který nalezne ve složce locales. Pro účely testování ale nejspíš chcete, aby zdrojové kódy obsahovaly nejnovější MO soubory. Skript pro vydávání pro toto nabízí volbu --compile-mo (nebo -m):

$ ./vendor/bin/plugin-release --compile-mo

Varování

Výše uvedený příkaz bude fungovat pouze přímo na souborech vašeho zásuvného modulu; nikoli na kopii jako ostatní příkazy.

Předběžná vydání¶

Ve výchozím stavu, skript pro vydávání bude fungovat pouze na existujících štítcích. Jakékoli předběžné vydání by mělo mít svůj štítek; ale v některých případech může být třeba vytvořit archiv vydání bez jakýchkoli štítků.

Co umístit do archivu se skriptu pro vydávání zadává několika parametry:

--commit (nebo -c) dávající otisk příspěvku,
--release (nebo -r) dávající verzi vydání (obvykle to bude další verze vydání),
--extra (nebo -e) pro zadání dalšího řetězce (jako třeba alpha, beta, rc1, atd…)

Jako příklad se zásuvným modulem objednávky:

$ ./vendor/bin/plugin-release --commit 632d515d4ac0 --release 1.9.5 --extra alpha1
$ ls dist
glpi-order-1.9.5-alpha1-20161103-632d515d4a.tar.bz2

Podepisování vydání¶

Podepisování vydání GPG klíčem umožňuje uživatelům ověřovat neporušenost před instalací. Budete potřebovat GPG klíč veřejně dostupný uživatelům; volba podepisování je ve výchozím stavu zapnutá, je možné ji vypnout pomocí volby --nosign (nebo -S).

Ve složce dist bude vytvořen soubor obsahující podpis se stejným názvem jako archiv s příponou .asc.

GitHub vydání¶

Skript pro vydání vytvoří vydání ve vašem GitHub repozitáři, jako koncept, pokud nepoužijete volbu --nogithub (nebo -g).

Poznámka

Žel nebylo možné získat nově vytvořený archiv nahraný do tohoto nového vydání… Snad toto bude opraveno v budoucnu.

Pro získání této funkce bude třeba nainstalovat github ; a budete potřebovat přístupový klíč. Přístupový token je platný pro konkrétního uživatele a dává přístup do všech repozitářů.

Je třeba jít do nastavení vašeho účtu na github, panel osobní přístupový token. Kliknout na generate new token (vytvořit nový token), zadat popis a zaškrtnout pouze public_repo (není třeba zaškrtávat cokoli jiného, je možné vytvořit více přístupových tokenů, pokud je to třeba).

Token bude zobrazen pouze jednou; uložte ho do souboru .gh_token ve složce se zásuvným modulem; a je to!

Vyloučené soubory¶

Můžete vytvořit soubor `` .ignore-release`` v kořenovém adresáři vašeho pluginu a uvést zde soubory a adresáře, které chcete explicitně vyloučit z archivu vydání. Napište jeden výraz <https://docs.python.org/2/library/re.html> `_ na řádek

.+\.png
screenshots/

Některé soubory budou automaticky vyloučeny:

.git*,
.gh_token
.tx/
tools/
tests/
.atoum.php
.travis.yml
.circleci/
.ignore-release
composer.lock
Robofile.php

ccbyncnd