Dokumentace

• Proč zvolit právě CSáček ?
• Návod k použití
  • Základy - URL stránky
  • Zachování kódu při odkazech
  • Kóduje se pouze text a HTML
  • Změna výchozího kódu
  • Překódovávání "chráněných" stránek
  • Vypisování konfigurace CSáčka
• Apache CSáček
  • Jak se konfiguruje Apache verze
  • Podpora SSL
• ISAPI CSáček
  • Jak se konfiguruje ISAPI verze
  • Objednávka ISAPI CSáčku
• Konfigurační direktivy
• Příkazy CSáčku
  • Příklady použití
• Úvodní stránka

Zpět k hlavní stránce

CSáček nabízí

• možnost funkce jako CGI, FastCGI nebo Apache modul, na UN*Xu (NetBSD, Linux, Solaris, IRIX, Digital Unix), CGI a ISAPI na MS Windows NT
• pod Apache 1.3.X možnost používat CSáček jako DSO modul
• on-fly kompresi dokumentů, posílaných klientovi (kompresi podporuje např. Netscape 4.5+, lynx, MSIE 4.0+)
• podpora META tagu pro označení kódování češtiny v dokumentu
• podporu Unicode (UTF-8)
• podporu relativních odkazů i absolutních odkazů, automatické přepisování absolutních odkazů pro zachování výběru kódování
• možnost používat různé typy kódování češtiny ve zdrojových textech stránek; je dokonce možno použít víc kódů v rámci jedné stránky
• možnost kódovat i dynamicky vytvářené stránky (např. výsledky různých skriptů)
• překódování vstupu od klienta (data z formulářů) do kódování serveru
• podporu azbuky

Zpět

Základ - URL stránky

http://www.kdesi.cz/cesta/stranka.html

http://www.kdesi.cz/toASCII/cesta/stranka.html

Tento odkaz však předpokládá, že předem víte, jaký kód bude uživatel vyžadovat. To často nemusí být pravda. V takovém případě doporučuji spustit CSáček v módu whichcode - URL bude vypadat nějak takto:

http://www.kdesi.cz/whichcode/cesta/stranka.html

Druhá možnost je použít toGUESS. V tomto módu se CSáček pokusí zjistit, jaké kódování a jazyk klient podporuje a přesměruje klienta na URL, které odpovídá jeho jazykovým/kódovacím schopnostem. Momentálně každému klientovi z Česka vnutí ISO-8859-2 (klient, který by nerozuměl tomuto kódování se dá považovat za nefunkční), ostatním pak ASCII. Pokud by měl uživatel tu smůlu, že používá nefunkčního klienta, může si typ kódování později změnit explicitně přes whichcode.
  V případě Apache modulu a ISAPI filteru se mód toGUESS používá implicitně v případě, že URL neobsahuje CSáček, tj. jedná se o jednoduché URL typu http://www.nekde.cz/cosi.html. Zjednodušuje se tak URL v obvyklém případě, kdy uživateli uhádnutý default vyhovuje.

Zachování kódování při odkazech

Pokud se odkazujete na jiné servery s CSáčkem a chcete, aby se při odkazech zachovala informace o uživatelem vybraném kódování, musíte CSáčkovi seznam takových serverů sdělit. CSáček pak upravuje URL v dokumentech podobným způsobem, jako při odkazech v rámci "svého" serveru. Podrobněji viz popis konfiguračního příkazu Apache csacekServers. CSáček jako Apache modul automaticky přidá do seznamy všechny virtuální servery WWW serveru, na kterém běží.

Samozřejmě lze na stránku napsat obvyklý seznam odkazů pro zobrazení dokumentu v ASCII, ISO-8859-2 či CP1250:

<A HREF="/toASCII/">ASCII/</A>
<A HREF="/toISO-8859-2/">ISO-8859-2/</A>
<A HREF="/toCP1250/">CP1250/</A>

Kóduje se pouze text a HTML

Dokumenty netextových typů (tj. cokoliv co má MIME typ jiný než text/*) předá CSáček beze změny.

Kvůli rychlosti zpracování CGI CSáček implicitně pokládá za "překódovatelné" soubory s příponou .html, .htm, .txt. O všechny ostatní dokumenty požádá zpět WWW server a rozhodne se, zda daný dokument kódovat nebo ne, podle informací, které server vrátí (zpracování přes další požadavek je samozřejmě pomalejší).

Apache/ISAPI CSáček má informaci o typu souboru vždy jednoduše k dispozici, proto tam neexistuje žádný pevný seznam přípon a vše záleží jen na konfiguraci serveru.  

Změna výchozího kódu

Převést stránku do implicitního kódu.

To je méně pohodlné a navíc to komplikuje pozdější úpravy na stránce (každá úprava bude vyžadovat nové překódování).

Ponechat stránku v kódu původním a vyznačit jej.

CSáček podporuje META tag a zařídí se podle informace, která je tam uvedena, tj. je-li tam <META HTTP-Equiv="Content-Type"Content="text/html; charset=windows-1250"> CSáček správně pochopí, že obsah dokumentu je v kódování používaném na MS Windows a zařídí se podle toho.

CSáček podporuje také jiný mechanismus vyznačení kódování textu - pomocí příkazu MYCHARSET. Vhodný je zejména tehdy, pokud různé části dokumentu obsahují text v různém kódování. Pokud máte celý dokument v jednom kódování, použijte raději příslušný META tag. Prohlížeč tak má informaci o kódování dokumentu i v případě, že dokument nedostane přes CSáček.

Účinnost příkazu MYCHARSET, popř. META tagu začíná místem, kde byl uveden. Přestože CSáček povoluje použít META tag s vyznačením kódování několikrát, toto není platné užití podle HTML standardu.

Podpora chráněných stránek

Při přímém předávání obsahu souboru CGI CSáček dává pozor, jestli se na "cestě" k němu nevyskytuje nějaký konfigurační soubor (standardně .htaccess). Pokud ano, o dokument požádá server.
Bohužel pak nastane problém v tom, že WWW server většnou z bezpečnostních důvodů nepředává CGI skriptům login a heslo poslané klientem. Při zpětném požadavku o chráněný dokument tedy CGI CSáček nemůže tuto informaci poslat a přístup k dokumentu je tedy zamítnut.

Lze samozřejmě upravit zdrojový kód serveru tak, aby tuto informaci CGI skriptům předával. Jedná se ale o možné bezpečnostní riziko a tedy toto nedoporučuji. Pokud potřebujete překódování veřejně nepřístupných stránek, použijte CSáček jako Apache modul.  

Vypisování konfigurace CSáčka

  Zpět

Apache CSáček

Jak se konfiguruje Apache verze

Apache CSáček se nastavuje pomocí sady direktiv, uvedených v konfiguračních souborech serveru (globálním httpd.conf nebo případných .htaccess). CSáček lze nastavovat různě pro každý virtualní server i adresář, je třeba jen direktivů uvést v příslušné sekci <Location> či <VirtualHost>.
Pokud je jako parametr direktivy řetezec obsahující mezery, je nutné jej celý uzavřít mezi uvozovky (může být případ csacekTemplateDir).

Příklad z konfigurace:

csacekEngine On
csacekDefaultCharset windows-1250

Podpora SSL

Apache-SSL

mod_ssl

Pozor:

Při použití LoadModule v konfiguraci serveru je třeba zařídit, aby se CSáček modul nahrál dříve než mod_ssl. Toto je nutné kvůli tomu, že CSáček potřebuje v určité fázi zpracování změnit vnitřní struktury spojení, ale příslušný kód musí být spuštěn po mod_ssl. Moduly jsou v každé fázi zpracování provolávány v opačném pořadí než byly nahrány, tedy CSáček musí být do serveru nahrán před mod_ssl.

Stronghold

  Zpět

ISAPI CSáček

ISAPI CSáček překódovává korektně výstup z ASP, CGI, server extensions (včetně FP extensions) a samozřejmě statické stránky, funguje i pri provozu s SSL a je velmi rychlý - podle namátkových testů asi dvakrát rychlejší než CZFILTER.

Pokud máte zájem ISAPI CSáček vyzkoušet, je k dispozici časově omezená verze, která přestane fungovat přibližně po měsíci. Objednat CSáček lze na samostatné stránce.  

Jak se konfiguruje ISAPI verze

ISAPI CSáček je konfiguruje pomocí záznamu v MS Windows Registry. Jeho větev je HKEY_LOCAL_MACHINE\Software\CSacek.

Záznam v CSáčkovském klíči Registry platí jako "globální". Je ale také možno nastavit vlastnosti CSáčka pro jednotlivé virtuální servery. Konfigurace pro každý virtuální server je uvedena v podklíči CSáček klíče - jako jméno klíče se použije název virtuálního serveru. Je možno uvést i port, od jména serveru je oddělen dvojtečkou. Pokud je port uveden, konfigurace platí jen při přístupu na tento konkrétní port, pokud ne, platí pro jakýkoli přístup na daný virtuální server. Příklad názvu podklíče:

www.muj.cz
www.jiny.cz:8000

Po každé změně konfigurace je nutno přestartovat Web server - jen tak se zajistí, aby CSáček změněný záznam z registry znovu načetl.

  Zpět

Konfigurace CSáčka

csacekChangeURL On nebo Off

Nastavuje, jestli se v dokumentu odkazy upravovat tak, aby šly "přes CSáček".
Default: On

csacekCompress On nebo Off

Nastavuje, jestli se má použít komprese nebo ne.
Default: On

csacekDefaultCharset

Nastavuje defaultní kódování serveru. CSáček bude předpokládat, že stránka je v tomto kódování, pokud si sama neřekne jinak. Textová data od klienta budou převedeny do tohoto kódování před předáním dat ostatním modulům.
Default: iso-8859-2 na Unixu a windows-1250 na MS Windows

csacekEngine On nebo Off

Zapíná CSáček (a'la Apachovske RewriteEngine).
Default: On

csacekImplicitWork On nebo Off

Pokud cílové kódování není v URL uvedeno (URL je typu http://kdesi/cosi/neco.html, tj. bez toXXX), CSáček se pokusí uhádnou klientem podporované kódování a automaticky do něj požadovaný dokument převede. Pokud se vám toto chování nehodí, lze implicitní překódování pomocí této direktivy vypnout.
Default: On

csacekServers

Seznam "CSáček kompatibilních" serverů - v předávaných HTML dokumentech se odkazy na tyto servery automaticky upraví tak, aby se zachovalo uživatelem používané kódování a jazyková verze
Jednotlivé názvy serverů se píšou navzájem oddělené čárkou. Je možné zadat i port (od jména serveru oddělený dvojtečkou) - pak se budou odkazy měnit jen pokud URL vede na daný port daného serveru.
Default: Apache - všechny virtuální servery, ISAPI - servery, které mají vlastní konfiguraci v CSáček větvi v registry
Příklad: www.nekde.cz:900,www.cosi.cz

csacekTemplateDir

Adresář se šablonami - momentálně pouze šablonou k whichcode (soubor whichcode_template.html).
Default: /www/csacek na UN*Xu a C:/CSacek na MS Windows.

csacekTestJS On nebo Off

Experimentální vlastnost, v příští verzi může zmizet nebo se změnit.
Zapíná heuristiku pro rozpoznávání "čistého" JavaScript dokumentu (default vypnuto). Pokud je dokument typu text/html, při zapnutí této direktivy CSáček prohlédne prvních 200 znaků dokumentu nebo první tři neprázdné řádky. Pokud se zde nalezne řetězec // nebo /* (JavaScript komentář) nebo znak ; na konci řádku (případné mezery nebo tabelátory mezi znakem ; a koncem řádku jsou ignorovány), dokument zpracovává jako text/plain, tedy HTML tagu (např. odkazy) nejsou přepisovány.

Pozor - při neopatrném použití může tato heuristika dávat špatné výsledky. Mohou existovat platné HTML stránky, které splňují výše uvedené kritéria a nejedná se přitom o JavaScript zdrojový kód. Pokud možno tuto direktivu vždy aplikujte jen na omezený podstrom dokumentů a zkontrolujte, že absolutní odkazy a tagů <A>, <FORM> atd. jsou správně přepisovány při použití explicitního překódování (jako např. /toASCII/).

Direktivy, které jsou nadále podporovány v řadě 2.1.*, ale budou zrušeny ve verzi 3.0:

• csacekBarDef
• csacekDefaultPartname
• csacekIgnorePrefix
• csacekServer (csacekServers bude nadále podporováno)

Zpět

Seznam příkazů

Příklad použití:

<? SET EXECCMDS=YES ?>

Od verze 3.0 bude podporována pouze (nová) notace <?csacek příkaz ?>.

Obecně platná pravidla:

• může být uveden pouze jediný příkaz
• příkaz včetně parametrů může být na několik řádků
• ve jméně příkazu nezáleží na velkých/malých písmenech (tj. např. SET se považuje za ekvivalentní s SeT)
• u názvů parametrů nezáleží na velkých/malých písmenech
• parametry příkazu se vyhodnocují obvyklým způsobem zleva doprava, jsou podporováný znaky " a ' s obvyklým HTML významem; zápis \x způsobí, že znak x nebude chápán jako speciální
• při zadání vzájemně protikladných parametrů platí poslední uvedený
• nastavení z příkazu má vždy přednost před defaultním nastavením
• pokud se příkaz nepozná, v dokumentu se ponechá

Příkazy:

• MYCHARSET
• SET

... a popis:

MYCHARSET

Syntax: MYCHARSET=kódování

Příklad použití: MYCHARSET=ISO-8859-2

• říká CSáčku, že následující text je zapsán v zadaném kódování.
• může být uvedeno jméno kteréhokoli podporovaného kódování
• příkaz lze v dokumentu použít i několikrát, vztahuje se na něj omezení PART, DOMAIN a CHARSET

SET

Syntax: SET volba1=hodnota1 ...

Příklad použití: SET CHANGEURL=NO

Nastavuje některé vlastnosti zpracování textu. Rozpoznávané parametry mohou být nastaveny na YES nebo NO.

Parametry:

CHECKURL	nastavuje, jestli se má v následujícím textu u HTML značek, používajících URL (A, BASE atd.), toto URL přepisovat tak, aby vedlo přes CSáček; defaultně zapnuto
EXECCMDS	nastavuje, jestli se v následujícím textu mají provádět CSáček příkazy; i v případě, že je provádění příkazů vypnuto se stále některé provádějí (např. SET) - jinak by nebylo možné příznak zase zapnout; defaultně zapnuto

Zastaralé příkazy

• BAR
• BARDEF
• PART
• DOMAIN
• CHARSET
• csacekServer
• csacekServers (konfigurační direktiva zůstává)

Zpět