Woo Czech Vocative – dokumentace

K čemu plugin slouží

Woo Czech Vocative upravuje oslovení zákazníků ve WooCommerce e-mailech do přirozeného českého 5. pádu – vokativu.

Místo obecného nebo gramaticky nesprávného oslovení:

Dobrý den, Jan,

zákazník obdrží:

Dobrý den, Jane,

Plugin načte křestní jméno z fakturačních údajů objednávky, vyhledá jeho správný tvar ve slovníku a automaticky upraví oslovení při vytváření e-mailu. Nevyžaduje úpravu šablon ani ruční zásah do jednotlivých objednávek.

Hlavní funkce

• Automatický převod českých křestních jmen do 5. pádu.
• Vestavěný slovník se 161 položkami českých jmen a jejich variant.
• Vlastní slovník pro doplnění dalších jmen.
• Rozpoznání jména bez ohledu na velikost písmen a diakritiku.
• Použití prvního křestního jména u celého jména zákazníka.
• Bezpečný fallback pro jména, která slovník neobsahuje.
• Podpora standardních i starších nebo upravených WooCommerce e-mailových šablon.
• Kompatibilita s WooCommerce HPOS.
• Licenční správa a automatické aktualizace přes Allimedia.cz.

Požadavky

• WordPress 6.0 nebo novější
• WooCommerce 7.0 nebo novější
• PHP 8.1 nebo novější
• Aktivní licence pluginu

Instalace

1. Nainstalujte a aktivujte WooCommerce.
2. V administraci WordPressu otevřete Pluginy → Instalace pluginů.
3. Klikněte na Nahrát plugin a vyberte instalační ZIP soubor pluginu Woo Czech Vocative.
4. Plugin nainstalujte a aktivujte.
5. Otevřete Nastavení → Woo Czech Vocative Licence.
6. Zadejte licenční klíč a klikněte na Aktivovat licenci.
7. Plugin začne automaticky upravovat oslovení v podporovaných WooCommerce e-mailech.

Plugin nemá další povinné nastavení. Po aktivaci licence je připravený k použití.

Aktivace licence

Licenční obrazovku najdete na stránce Nastavení → Woo Czech Vocative Licence. Odkaz Licence je dostupný také přímo u pluginu na stránce Pluginy.

Licence se váže na doménu webu. Pokud chcete plugin přesunout na jinou doménu, nejprve licenci na původním webu deaktivujte.

Plugin ověřuje stav licence při aktivaci a následně jednou týdně prostřednictvím WordPress Cronu. Pokud je licenční API dočasně nedostupné, může plugin pokračovat v provozu po dobu až 14 dnů od posledního úspěšného ověření platné licence.

Bez platné licence:

• se oslovení v nově vytvářených e-mailech neupravuje;
• se v administraci zobrazí upozornění na neaktivní licenci;
• nejsou dostupné aktualizační balíčky pluginu.

Jak plugin vytváří oslovení

Plugin získá jméno zákazníka z fakturačních údajů objednávky. Z celého jména použije první část, normalizuje ji pro vyhledání ve slovníku a vloží nalezený vokativ do oslovení:

Dobrý den, [jméno v 5. pádu],

Příklady:

Jméno ve fakturačních údajích	Použité křestní jméno	Výsledné oslovení
Jan Novák	Jan	Dobrý den, Jane,
Petra Svobodová	Petra	Dobrý den, Petro,
Aleš Novotný	Aleš	Dobrý den, Aleši,
Marie Dvořáková	Marie	Dobrý den, Marie,

Při vyhledávání se nerozlišuje velikost písmen ani diakritika. Hodnoty Aleš, ALES a ales se proto při hledání považují za stejné jméno.

Víceslovná jména

Pokud zákazník uvede více jmen, plugin použije první část. Například ze jména Jan Pavel Novák použije Jan a vytvoří oslovení Dobrý den, Jane,.

Jméno není ve slovníku

Pokud plugin jméno ve vestavěném ani vlastním slovníku nenajde, zachová první křestní jméno beze změny a pouze sjednotí jeho první písmeno na velké.

Tento fallback zabraňuje tomu, aby plugin neznámé, zahraniční nebo neobvyklé jméno automaticky skloňoval nesprávně. Správný tvar můžete následně doplnit do vlastního slovníku.

Vlastní slovník jmen

Správu vlastních jmen najdete na stránce WooCommerce → Český vokativ. Odkaz Slovník je dostupný také přímo u pluginu na stránce Pluginy.

Vlastní slovník se hodí například pro:

• méně obvyklá česká jména;
• zahraniční jména;
• varianty zápisu, které vestavěný slovník neobsahuje;
• individuální způsob oslovení používaný vaším obchodem.

Přidání vlastního jména

1. Otevřete WooCommerce → Český vokativ.
2. Do pole Jméno zadejte křestní jméno v 1. pádu, například René.
3. Do pole Vokativ zadejte požadovaný tvar oslovení, například René.
4. Klikněte na Přidat do slovníku.

Do každého pole lze zadat nejvýše 80 znaků. Pole Jméno smí obsahovat pouze jedno křestní jméno bez mezer a příjmení.

Plugin nedovolí vložit jméno, které již existuje ve vestavěném nebo vlastním slovníku. Při kontrole duplicit nerozlišuje velikost písmen ani diakritiku.

Smazání vlastního jména

V části Vlastní jména najděte příslušnou položku a klikněte na Smazat.

Vestavěná jména nelze z administrace smazat ani přepsat. Pokud potřebujete opravit vlastní položku, smažte ji a znovu ji přidejte se správnou hodnotou.

Zpracování WooCommerce e-mailů

Plugin používá standardní mechanismus WooCommerce pro zákaznické oslovení. Zároveň obsahuje záložní způsob zpracování pro starší nebo individuálně upravené e-mailové šablony.

Záložní zpracování rozpoznává běžné varianty oslovení, například:

• Dobrý den, Jan,
• Dobrý den Jan Novák,
• Vážený zákazníku, Jan,
• Hello, Jan,
• Hi Jan,

V jednom e-mailu nahradí pouze první odpovídající oslovení. Ostatní text e-mailu zůstane beze změny.

Pokud vlastní šablona nepoužívá standardní WooCommerce oslovení ani žádný z rozpoznávaných formátů, plugin do jejího obsahu nezasáhne.

Aktualizace pluginu

Dostupné aktualizace se zobrazují standardně na stránce Pluginy a Nástěnka → Aktualizace v administraci WordPressu. Pro stažení aktualizačního balíčku je nutná platná licence.

Informace o dostupné verzi se dočasně ukládají do cache na 6 hodin. Pokud se očekávaná aktualizace nezobrazuje:

1. ověřte, že je licence aktivní;
2. otevřete Nástěnka → Aktualizace;
3. spusťte novou kontrolu aktualizací;
4. případně licenci deaktivujte a znovu aktivujte.

Aktualizační balíčky jsou přijímány pouze přes zabezpečené HTTPS spojení z povolené domény Allimedia.cz.

Externí služba a ochrana soukromí

Plugin neodesílá společnosti Allimedia.cz jména zákazníků, údaje objednávek ani obsah e-mailů. Převod jmen probíhá lokálně na vašem webu pomocí slovníku uloženého přímo v pluginu a ve WordPress databázi.

Při aktivaci, deaktivaci a pravidelné validaci licence plugin komunikuje přes HTTPS s licenčním API:

https://allimedia.cz/wp-json/allimedia-lmfw/v1

Pro licenční operace se odesílají pouze technické údaje potřebné k ověření licence:

• licenční klíč;
• doména webu;
• aktivační token při deaktivaci licence.

Při kontrole aktualizací se dále odesílá:

• URL webu;
• identifikace pluginu;
• nainstalovaná verze pluginu;
• technický název instalačního souboru pluginu.

Deaktivace a odinstalování

Při běžné deaktivaci pluginu zůstanou licenční údaje i vlastní slovník uložené. Plugin pouze ukončí pravidelnou licenční kontrolu a smaže dočasnou cache aktualizací. Po opětovné aktivaci může pokračovat se stávajícím nastavením.

Před úplným odinstalováním doporučujeme licenci nejprve deaktivovat. Tím se její aktivace uvolní pro použití na jiném webu.

Při odinstalování plugin odstraní:

• licenční klíč a uložený stav licence;
• údaje o posledních licenčních kontrolách;
• vlastní položky slovníku;
• cache aktualizací;
• naplánovanou kontrolu licence.

Odinstalování nemění objednávky ani zákaznické údaje ve WooCommerce.

Řešení problémů

Oslovení se v e-mailu nemění

Ověřte:

• zda je WooCommerce aktivní;
• zda je plugin Woo Czech Vocative aktivní;
• zda je licence platná;
• zda objednávka obsahuje křestní jméno ve fakturačních údajích;
• zda vlastní e-mailová šablona používá standardní nebo podporovaný formát oslovení.

Pokud používáte výrazně upravenou e-mailovou šablonu, může být nutné obnovit standardní WooCommerce oslovení nebo upravit šablonu individuálně.

Jméno zůstává v 1. pádu

Jméno pravděpodobně není ve vestavěném ani vlastním slovníku. Přidejte jeho správný tvar na stránce WooCommerce → Český vokativ.

Jméno nelze přidat do slovníku

Zkontrolujte, zda:

• jsou vyplněná obě pole;
• pole Jméno obsahuje pouze jedno křestní jméno bez mezer;
• jméno již neexistuje ve vestavěném nebo vlastním slovníku;
• žádná hodnota nepřesahuje 80 znaků.

Potřebuji změnit vlastní položku

Existující vlastní položku nejprve smažte a poté ji znovu přidejte se správným vokativem.

Licence je aktivní, ale funkce se po výpadku zastavila

Ověřte dostupnost webu allimedia.cz z vašeho serveru a funkčnost WordPress Cronu. Plugin licenci kontroluje jednou týdně a při dočasném výpadku API používá ochrannou lhůtu nejvýše 14 dnů od posledního úspěšného ověření.

Pro vývojáře

Úprava výsledného vokativu

Výsledné oslovení konkrétního jména lze upravit filtrem allimedia_wcv_vocative:

add_filter(
	'allimedia_wcv_vocative',
	static function ( string $vocative, string $first_name, string $full_name ): string {
		if ( 'Chris' === $first_name ) {
			return 'Chrisi';
		}

		return $vocative;
	},
	10,
	3
);

Filtr přijímá:

• vypočtený vokativ;
• původní křestní jméno;
• celé jméno zákazníka.

Plugin dále poskytuje filtry:

• allimedia_wcv_license_api_url – úprava URL licenčního API; z bezpečnostních důvodů je akceptováno pouze HTTPS na doméně Allimedia.cz;
• allimedia_wcv_update_cache_ttl – změna doby uložení informace o aktualizaci v cache.

Technická kompatibilita

Plugin podporuje:

• WordPress 6.0 a novější;
• WooCommerce 7.0 a novější;
• PHP 8.1 a novější;
• klasické ukládání objednávek i WooCommerce HPOS;
• standardní WooCommerce e-mailové šablony;
• vybrané starší a individuálně upravené šablony se známým formátem oslovení.

Podpora

Allimedia.cz
info@allimedia.cz
https://allimedia.cz