Použití FlaggedRevs pro kontrolu widgetu

Pro aktivaci procesu kontroly zabezpečení widgetu můžete použít rozšíření FlaggedRevs. Postup integrace rozšíření naleznete v této verzi dokumentace.

Změna adresáře pro ukládání zkompilovaných widgetů

Proměnnou $wgWidgetsCompileDir můžete použít ke změně adresáře pro ukládání zkompilovaných widgetů (v kódu je to $compile_dir). Výchozí nastavení je

$wgWidgetsCompileDir = "$IP/extensions/Widgets/compiled_templates/";

Pokud změníte umístění nastavením parametru s jiným adresářem, ujistěte se, že existuje a má správná oprávnění.

Uživatelská práva

Toto rozšíření přidává jmenný prostor s názvem "Widget", ale kvůli potenciálním bezpečnostním dopadům, které mohou vzniknout v důsledku použití nezabezpečeného kódu widgetu, je tento jmenný prostor upravitelný pouze uživateli s oprávněním editwidgets (pro přidávání uživatelů je také vytvořena skupina widgeteditor. Další podrobnosti viz Help:User rights ).

Funkce analyzátoru {{#widget}}

Pro přidání definovaného widgetu na stránky mohou uživatelé použít funkci parseru {{#widget}}. Syntaxe je následující:

{{#widget:WidgetName|param1=value1|param2=value2}}

Kde WidgetName je název stránky v jmenném prostoru Widget (např. Widget:WidgetName) a páry param=value jsou nastavitelné parametry definované v kódu widgetu.

Parametry lze uvnitř widgetu rozšířit pomocí [syntaxe https://www.smarty.net/syntax_comparison Smarty] takto:

<a href="<!--{$param1|escape:'url'}-->"><!--{$param2|escape:'html'}--></a>

Parametr escape určuje, jak bude parametr ve výsledném widgetu 'escapován' neboli zakódován. Je kriticky důležité, aby všechny parametry byly escapovány, aby se zabránilo zranitelnostem způsobujícím skriptování napříč weby. Některé escape metody jsou neúčinné. Obecně byste měli použít jednu z hodnot escape:html, escape:url, escape:urlpathinfo nebo escape:javascript. Více informací k tomuto tématu naleznete v části http://www.smarty.net/docsv2/en/language.modifier.escape.

Stránky ve jmenném prostoru widgetů

Všechny widgety na wiki jsou definovány vytvořením stránek ve speciálním jmenném prostoru "Widget:", například "Widget:WidgetName".

Chcete-li zobrazit všechny widgety definované ve vašem systému, přejděte na stránku "Special:AllPages", v rozbalovací nabídce jmenného prostoru vyberte "Widget" a klikněte na "Jděte".

Z bezpečnostních důvodů mohou tyto stránky upravovat pouze administrátoři wiki - více informací naleznete výše v části Uživatelská práva.

Mnoho předdefinovaných widgetů, které si můžete nainstalovat do své wiki, najdete na MediaWikiWidgets.org. Pokud máte zájem o vlastní tvorbu widgetů, podívejte se na další část.

Pole

Pokud použijete stejný parametr vícekrát, widget získá pole hodnot. K procházení pole můžete použít foreach.

Booleovské hodnoty

Kromě výchozího zpracování booleovských převodů v PHP můžete (na rozdíl od PHP) k nastavení booleovské hodnoty použít hodnoty "true" nebo "false". Například následující příkaz nastaví parametr $popup na hodnotu false:

{{#widget:WidgetName|popup=false}}

Kromě toho můžete nastavit booleovské parametry na hodnotu true pouhým použitím názvu parametru bez hodnoty, například takto:

{{#widget:WidgetName|popup}}

Tečkovaná notace

Názvy parametrů mohou obsahovat tečky a Smarty je interpretuje jako asociativní pole, takže k jejich procházení můžete použít foreach s atributy key i item, nebo můžete použít stejný název s tečkami, pokud chcete na parametr odkazovat přímo.

Příklad

Widget:AssocTest by mohl vypadat takto:

<includeonly><ul>
<!--{foreach from=$arg key=key item=item}-->
   <li><!--{$key|escape:'html'}-->: set to <!--{$item|escape:'html'}--></li>
<!--{/foreach}-->
</ul></includeonly>

...a tento widget můžete nazvat takto:

{{#widget:AssocTest|arg.foo=bar|arg.bar=oni}}

...což by se zobrazilo jako:

• foo nastaveno na bar
• bar nastaveno na oni

Modifikátor validate

Kromě [standardních modifikátorů Smarty s hodnotou https://www.smarty.net/docsv2/en/language.modifiers] (jako je hojně používaný escape) implementuje rozšíření Widgets modifikátor validate, který používá [filtrování dat PHP https://php.net/filter] k ověřování parametrů widgetu. Ověření parametru nenahrazuje escapování parametru. Modifikátor escape byste měli používat i při ověřování. Pro validaci jsou podporovány následující hodnoty (mapování na PHP validační filtry):

• url – Ověřit jako URL. povoluje pouze schémata URL uvedená v $wgUrlProtocols a na rozdíl od validace PHP nepovoluje URL se znaky nebezpečnými v HTML.
• url-php (FILTER_VALIDATE_URL) – Varování: Ověření jako URL stále umožňuje JavaScriptové URL, které mohou vést k XSS. Také povoluje URL adresy obsahující znaky, které jsou v HTML nebezpečné.
• int (FILTER_VALIDATE_INT) – ověří hodnotu jako celé číslo, volitelně ze zadaného rozsahu, a v případě úspěchu ji převede na int.
• boolean or bool (FILTER_VALIDATE_BOOLEAN) – vrací true pro "1", "true", "on" a "yes". V opačném případě vrátí false.
• float (FILTER_VALIDATE_FLOAT) – ověří hodnotu jako číslo s plovoucí desetinnou čárkou, volitelně ze zadaného rozsahu, a v případě úspěchu ji převede na číslo s plovoucí desetinnou čárkou.
• email (FILTER_VALIDATE_EMAIL) – Varování: Platná e-mailová adresa může stále obsahovat znaky, které jsou v HTML nebezpečné, proto nezapomeňte kromě ověření použít i znaky escape.
• ip (FILTER_VALIDATE_IP) – ověřuje hodnotu jako IP adresu, volitelně pouze IPv4 nebo IPv6, nebo ne z privátních či rezervovaných rozsahů.
• domain (FILTER_VALIDATE_DOMAIN) – Varování: Platné domény mohou stále obsahovat znaky, které jsou v HTML nebezpečné, proto je nutné kromě ověření použít i escape.
• mac (FILTER_VALIDATE_MAC) – ověřuje hodnotu jako MAC adresu.

Modifikátor allowedprefixes

Dalším vlastním modifikátorem, který můžete použít, rovněž z bezpečnostních důvodů, je allowedprefixes, který umožňuje zadat, že hodnota aktuálního parametru musí začínat jedním z uvedených řetězců (např. řetězcem URL). Zde je například způsob, jak mít v rámci widgetu prvek iframe, který nelze jednoduše předat v libovolných URL adresách: Here, for example, is a way to have an iframe within a widget that cannot simply be passed in arbitrary URLs:

<iframe src="<!--{$src |allowedprefixes:'https://trustedframe1.example.com/,https://trustedframe2.example.com/' |escape:html}">

They're hidden by default, but if they're visible on your wiki, it might say something like Attempting to read property "value" on null in [...]. One way to prevent an error from showing despite undefined parameters is to add default:'' to widget parameters that are at risk of remaining undefined. For an example, see param2 below:

<a href="<!--{$param1|escape:'url'}-->" class="<!--{$param2|default:''|escape:'html'}-->"><!--{$param3|escape:'html'}--></a>

Obnovení stránky widgetu

Pokud používáte volání widgetu přímo v rámci stránky widgetu, pak neuvidíte aktualizovaný widget (a vůbec žádný widget, pokud jste stránku právě vytvořili). K tomu dochází, protože obsah stránky není k dispozici rozšíření Widgets, dokud není stránka uložena, ale volání funkce parseru {{#widget}} se provede před uložením stránky. Po uložení stránky ji MediaWiki uloží do mezipaměti, takže výsledek neuvidíte, i když ji znovu načtete přes prohlížeč. Aby se zobrazily nejnovější úpravy kódu widgetu, je nutné obnovit stránku v mezipaměti. K tomu je třeba použít akci Purge (viz také rozšíření Purge) nebo počkat určitou dobu (až 24 hodin).

Widgety a šablony

Umístění widgetů do šablon z nich dělá neocenitelný nástroj pro vytváření komplexních zobrazení dat s minimálním počtem řádků kódu.

To je obzvláště užitečné, pokud chcete přednastavit některé parametry widgetu a zároveň umožnit uživatelům upravovat jiné (např. ID videa pro widget YouTube nebo uživatelské jméno pro widget Twitter).