|
Dokumentace
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
Stránku napište v kódu, který odpovídá zvolenému implicitnímu
kódu serveru (ve skutečnosti kódování stránky
není omezeno).
Vystavte ji, jak je obvyklé. Jediné, co se změní, bude URL, kterým
je třeba se odkázat na stránku. Jestliže URL stránky bez překódování by
bylo
http://www.kdesi.cz/cesta/stranka.html
bude URL téže stránky při požadavku jejího překódování do sedmibitového
ASCII
http://www.kdesi.cz/toASCII/cesta/stranka.html
za předpokladu, že používáte Apache CSáček.
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
Na základě externí šablony bude vygenerována stránka, kde bude
uživateli bude oznámeno, že cílový dokument obsahuje
diakritická znaménka a umožní mu zvolit kód, který považuje za optimální.
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.
CSáček od verze 2.0 automaticky přepisuje odkazy v dokumentu tak, aby
se v daném URL opět objevil a zachovala se tak informace
o vybraném kódování. Nemusíte se tedy o odkazy jakýmkoli
způsobem starat, CSáček vše upraví za Vás. Je nutno pouze zachovat
opatrnost při skládání odkazů v JavaScriptu - tyto odkazy samozřejmě
CSáček nemůže změnit. Pokud je to jen trochu možné, použijte
tady relativní odkazy.
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>
CSáček kóduje pouze dokumenty typu text/html (HTML
dokumenty) a obecně text/* (jako textová data).
Dokumenty, které mají neznámý textový typ (např. text/javascript)
jsou zpracovány jako text/plain, tedy nerozeznávají
se tam žádné HTML značky a nepřepisuje se URL.
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
Implicitní výchozí kód, ve kterém budou psány dokumenty, určuje správce
serveru při instalaci CSáčku. Mělo by se jednat o kód, ve kterém
bude vytvářena většina stránek (nejlépe všechny). Pokud autor používá
jiné kódování, má v základě dvě možnosti:
- 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.
Následující text platí pouze pro (Fast)CGI CSáček; pokud je CSáček
součást WWW serveru (Apache modul nebo ISAPI filter), použijí
se bezpečnostní mechanismy daného serveru bez toho, že by je
CSáček nějak ovlivňoval.
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
Pokud do browseru zadáte URL na stránku na serveru s CSáčkem a připojíte
k URL ?csacek_info,
CSáček vytvoří a vypíše krátkou informační HTML stránku s popisem
konfigurace pro toto URL a seznamem zakompilovaných nastavení.
Tato vlastnost je užitečná zejména při aktualizaci či ladění konfigurace
CSáčku pro daný server. Tuto vlastnost lze při kompilaci vypnout.
Zpět
Apache CSáček
CSáček na Apache byl původně na 1.2.4. Nyní je primárně vyvíjen
na Apache 1.3.19 s tím, že je možné ho používat i na Apache 1.1.1
i Apache 1.2.X. Není nutné patchovat server,
CSáček modul se do serveru přidává jako kterýkoli jiný modul.
Pod Apache 1.3.X je ho možné dokonce (s pomocí axps)
zkompilovat jako DSO modul a nahrávat do serveru dynamicky.
Jak se konfiguruje Apache verze
Seznam konfiguračních direktiv viz
konfigurační direktivy CSáčku.
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
U modulu Apache-SSL stačí od verze 1.17 v souboru
apache_ssl.c změnit SSL_IS_OPTIONAL na TRUE.
Apache-SSL pak bude fungovat
i bez CSáčku, pouze se přidá několik testů na obsah některých struktur.
Tyto testy jsou nutné proto, aby CSáček byl schopen během své práce
dočasně "vypnout" SSL. Komunikace s klientem (čtení vstupu od něj
i výstup ze serveru) jsou stále v SSL, toto jen vypne SSL při
vnitřním zpracování tak, aby CSáček data dostal nezakódovány.
mod_ssl
Od verze 2.1.2 funguje CSáček i společně
s mod_ssl. Nejsou třeba
žádné úpravy kódu. Od verze 2.1.9 funguje CSáček i v případě,
že se nepoužívá autentifikace uživatelů.
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
Od verze 2.1.3 CSáček funguje i pod Strongholdem. Testováno
na verzi Stronghold 2.4.2 pro NetBSD/i386.
Zpět
ISAPI CSáček
V rámci vývoje webových stránek Masarykovy univerzity byl financován
i vývoj CSáčku pro IIS, tj. ISAPI filtru. ISAPI CSáček je nyní
dopracován a od verze 2.1 je k dispozici jako komerční software.
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
Seznam konfiguračních direktiv viz
konfigurační direktivy CSáčku.
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
V konfiguraci virtuálního serveru mohou být uvedeny všechny direktivy
stejně jako v globální. Hodnoty nastavení csacekServers
jsou ale globální a sdílené všemi virtuálními servery - nemá význam
mít nastavení různě pro různé servery.
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
Některé vlastnosti CSáčka lze ovlivnit vhodným nastavením.
Pro CGI CSáčka to lze pouze v čase kompilace (možnost
run-time konfigurace není pro CGI rozumná). Chování
Apache CSáčku a ISAPI CSáčku lze ale poměrně jednoduchým způsobem
ovlivnit i později - nastavením
v kofiguraci serveru (Apache)
nebo nastavením v registry (ISAPI).
Zde je popis jednotlivých direktiv:
- 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/).
CSáček je standardně "zapnutý", pokud ho chcete vypnout, je třeba
ho explicitně vypnout pomocí csacekEngine.
Stále se bude interně z URL odstraňovat CSáčková část (tj. pokud
server bude požádán o http://server/toASCII/dir/doc.html,
převede se požadavek interně na http://server/dir/doc.html),
CSáček ale s dokumentem poslaným nazpátek klientovi nebude nic dělat.
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říkazy v CSáčku se uzavírají mezi
<? a ?>. ? je použito proto, že
se jedna o speciální SGML "tag", určený pro vkládání příkazů
jazyků vložených (embedded) do SGML dokumentu. Kvůli kompatibilitě
s SaCzechem je podporováno také <!-- a -->.
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:
... a popis:
V následujícím popisu hranaté závorky označují části, které nemusí
(ale mohou) být zadány. U každého příkazu je uvedena
jeho syntax, jeden jednoduchý příklad použití, dále
pak krátký popis, co daný příkaz dělá a poté případně přehled
voleb či parametrů, které můžete příkazu zadat. U některých je
uveden ještě odkaz na další, podrobnější příklady užití.
- 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
Následující příkazy jsou stále podporovány v řadě 2.1.*, ale budou
odstraněny ve verzi 3.0:
- BAR
- BARDEF
- PART
- DOMAIN
- CHARSET
- csacekServer
- csacekServers (konfigurační direktiva zůstává)
Zpět
|