Bloxxy - dokumentace


Co je Bloxxy?

Bloxxy je jednoduchý publikační systém vytvořený v PHP pro tvorbu, správu a generování blogů. Jednotlivé příspěvky se řadí do skupin, z nichž jsou poté podle předloh generovány statické dokumenty (HTML, XHTML, XML, TXT - podle typu předlohy). Publikační možnosti Bloxxy zhruba odpovídají Bloggeru (není ale nutný FTP přístup).

Bloxxy používá automatické formátování podobné (ale ne stejné) systému vikki. Příspěvky lze tedy psát zcela bez použití HTML značek (pokud ale nějaké použijete, jsou ponechány v textu beze změny).

Verze (historie)

Aktuální verze je 0.4b. Více viz soubor history.txt

Potřebné vybavení

PHP na straně serveru, FTP přístup s možností nastavení přístupových práv pro adresáře a soubory. Na straně klienta libovolný prohlížeč s podporou cookies (kvůli autentifikaci). Na serveru se předpokládá nastavený korektní čas a datum, je na ně vázána správa vkládání příspěvků.


Instalace

Upravte nastavení aplikace v souboru index.php (viz dále) a umístěte adresář Bloxxy na WWW server. Pokud chcete použít soubor index k jinému účelu (třeba homepage blogu právě v tomto adresáři), index.php klidně můžete přejmenovat (např. editor.php). Ostatním souborům ale jména neměňte. Víc dělat není potřeba.

Nastavení aplikace

V souboru bloxxy-files/bloxxy-settings.php je v několik předdefinovaných proměnných, jejichž správná hodnota je důležitá pro fungování Bloxxy. Před prvním spuštěním je nutné tyto hodnoty korektně nastavit.

Adresáře a URL

Do proměnné $bloxxy_URL zapište URL adresáře, v němž se nachází Bloxxy (adresář, v němž je index.php), např. "http://www.mujserver.cz/mujblog/bloxxy". Adresář $path_to_data je relativní cesta od souboru index.php. Tento adresář musí existovat a Bloxxy musí mít právo zde číst a zapisovat. Ve výchozí instalaci není třeba upravovat nic kromě přístupových práv (pokud nevíte jak, nastavte tomuto adresáři práva 0777).

Uživatelé

Bloxxy používá jednoduchou autentifikaci uživatelů, přihlášení probíhá pouze při prvním spuštění editoru (pro práci s editorem musíte mít v prohlížeči povoleny cookies). Seznam uživatelů (autorů) je uložen přímo v souboru bloxxy-settings.php. Změňte zde (pole $authors) své identifikační údaje - přihlašovací jméno, heslo, zobrazované jméno a e-mail. Přihlašovací jméno slouží jako index pole, budete-li se např. přihlašovat jako 'beda' s heslem '12345' (určitě si ale vymyslíte lepší heslo), vaše příspěvky mají být podepsány Béďa Novák s e-mailem beda@novak.cz, bude pole vypadat takto:

   $authors['beda']['passwd'] = '12345'
   $authors['beda']['name'] = 'Béďa Novák'
   $authors['beda']['e-mail'] = 'beda@novak.cz'
 

POZOR: Obsahuje-li položka (především jméno) znaky s diakritikou, musíte počítat s tím, že všechna data se zpracovávají podle nastaveného kódování (viz níže). Máte-li proto nastaveno např. kódování ISO Latin2, musíte sem údaje zapsat v tomto kódování, jinak se budou zobrazovat chybně.

Můžete přidat více uživatelů (s jiným přihlašovacím jménem), jejich příspěvky pak budou evidovány podle přihlášení.

Jazyk a kódování

Bloxxy je připraveno pro mutaci do jiných jazyků. Po instalaci obsahuje rozhraní v angličtině a češtině v kódováních iso-8859-2 (ISOlatin2) a windows-1250 (CP1250). Protože obsah příspěvků i rozhraní se zobrazují na stejných stránkách, musí být jazyk a kódování editoru i výsledných stránek stejné (Bloxxy neobsahuje překódovávání a nemyslím, že někdy bude).

Použitý jazyk a kódování se nastavuje v proměnné $use_language. Možné hodnoty jsou "en" (anglické rozhraní, kódování iso-8859-1), "cs-iso" (čeština, iso-8859-2) a "cs-win" (čeština, windows-1250). Nastavení předpokládá, že v konfiguračním adresáři existuje soubor "bloxxy-strings-KOD", kde KOD je nastavená hodnota jazyka. Chcete-li vytvořit další alternativy, zkopírujte některý z existujících souborů "bloxxy-strings-KOD", přejmenujte KOD na (dosud nepoužitou) zkratku a upravte soubor podle nového nastavení. Např. budete-li chtít stránky ve slovenštině s kódováním UTF-8, postup je tento:

Další proměnné v nastavení

$use_autoformat - hodnoty "HTML", "XHTML", nebo "" (či false). Povoluje/zakazuje použití automatického formátování příspěvků s použitím syntaxe BXTags (viz dále). S hodnotou HTML/XHTML jsou příspěvky formátovány v jazyce HTML, resp. XHTML. Použijte false, pokud chcete psát příspěvky pouze v HTML a autoformátování nehodláte nikdy používat. $items_perpage - hodnotou je číslo větší než 1. Určuje počet příspěvků na stránce v seznamu příspěvků v editoru (netýká se výsledných stránek). $textarea_columns, resp. $textarea_rows - hodnotou je číslo, které určuje rozměry vstupního pole pro psaní příspěvku (počet sloupců, resp. řádek). $week_starts_moday - true/false. Použijte true, pokud má týden začínat pondělkem; s hodnotou false se bude počítat od neděle (používá se pro dělení archivů po týdnech).

Do proměnné $description_prefix zapište prefix odstavce, který se bude považovat za popis (náhled, stručné shrnutí) příspěvku (používá se v %bx_item_autopreview%). Pokud jím bude např. ":", za popis příspěvku se budou považovat všechny odstavce začínající ":" (nadpisy h4). Užitečné může být použít zde odstavce dané třídy - např. použijete-li např. $description_prefix="=popis", jako náhledy příspěvků se použijí všechny odstavce začínající "=popis". Použít můžete kterýkoli z existujících prefixů (viz dále), včetně "|||" (skrytý odstavec, popis v textu příspěvku nebude vidět - tím lze vytvářet popisy, které nejsou součástí textu příspěvku).

$replace_macros - s hodnotou true se budou v příspěvcích překládat makra (^makro^, viz makra dále); pokud se makra nemají překládat, nastavte hodnotu false. $use_smileys - obdobně; s true bude Bloxxy nahrazovat znaky pro smajlíky příslušnými obrázky (viz smajlíky dále).

Pokud používáte komentáře (viz dále), v proměnné $path_to_comments musí být cesta k adresáři, do nějž se budou komentáře ukládat (v tomto adresáři musí mít bloxxy práva čtení a zápisu). V proměnné $comments_template je šablona stránky pro zobrazení komentářů (relativní cesta z adresáře Bloxxy).


Práce s Bloxxy

Bloxxy pracuje se třemi typy údajů: příspěvky, skupinami a publikacemi. Příspěvky jsou jednotlivé zprávy/články, tvořící obsah stránek. Ty jsou uspořádány do skupin (každá zpráva je právě v jedné skupině). Publikace definují výsledné stránky, do kterých se následně generují příspěvky z přiřazené skupiny.

Skupiny

Každý příspěvek je zařazen do nějaké skupiny. Výchozí (ne-tak-úplně) skupinou, která vždy existuje, je "nezařazen". Příspěvky v této skupině nejsou zařazeny do žádné "skutečné" skupiny a nejsou také publikovány na stránkách.

Tlačítkem "Zobrazit" zobrazíte příspěvky ve zvolené skupině, tlačítkem "Zobrazit všechny" pak všechny existující příspěvky. Tlačítkem "Nová skupina" vytvoříte novou skupinu libovolného jména (jméno skupiny se nikde na stránkách nezobrazuje). Mazání a ani editaci skupin Bloxxy (ještě) nepodporuje, změny lze ale (s nejvyšší opatrností) provést ručně - informace o skupinách jsou v souboru groups.conf v konfiguračním adresáři.

Příspěvky

Tlačítkem "Nový příspěvek" otevřete editor příspěvku. Zde vyplníte jeho text, kterým je prostý text se syntaxí automatického formátování BXTags (není-li vypnuto), nebo HTML/XHTML/XML kód. Zvolíte skupinu, do níž se má příspěvek umístit, a uložíte jej. Pokud je zvolená skupina součástí nějaké publikace, je příspěvek ihned publikován na stránky. Pokud jej označíte jako "nezařazen", na stránkách se naopak neobjeví.

V zobrazeném seznamu příspěvků jsou u každého z nich k dispozici tři akce. "Upravit" otevře editor příspěvku. Uložené změny se ihned promítnou na stránkách - pokud byl příspěvek na nějaké stránce a přesunete jej do skupiny "nezařazen" (nebo jej smažete), ze stránek bude odstraněn, pokud jej přesunete do nějaké publikované skupiny, bude zařazen do příslušných stránek. "Náhled" zobrazí text příspěvku tak, jak bude formátován na stránce. "Publikovat" přegeneruje všechny stránky, na které je tento příspěvek umístěn.

Publikace

Publikace jsou mezičlánek mezi skupinami příspěvků a výslednými stránkami. Při vytvoření nové publikace určujete skupinu(y), z níž se mají publikovat příspěvky a parametry výsledných stránek. Publikací může být libovolné množství, stejný příspěvek tedy můžete zobrazit na více stránkách s různým formátováním. Lze tak snadno vytvořit jak několik tématicky oddělených blogů, tak i meta-blog obsahující příspěvky ze všech ostatních publikací, stránku se stručným přehledem příspěvků, RSS soubory pro jeden nebo všechny blogy atd. Přidání/změna jednoho příspěvku se pak automaticky promítá do všech dotčených publikací.

Nastavení publikace:

Odkazem "Přegenerovat" vygenerujete všechny stránky, které jsou s touto publikací svázány (hlavní stránka, všechny archivované stránky, obsah archivu a všechny metablogy). Tlačítkem "Přegenerovat všechny" znovu vygenerujete všechny publikované stránky (včetně všech metablogů). Při změně nastavení se nemažou žádné soubory - pokud např. změníte prefix či umístění archivu, dříve vygenerované stránky zůstanou na původním místě. Informace o publikacích jsou v souboru publications.conf v konfiguračním adresáři (lze s nejvyšší opatrností upravovat).


Automatické formátování (BXTags)

Bloxxy používá pro snazší psaní příspěvků automatické formátování (BXTags). Jeho idea vychází z podobných existujících editorů, ale žádný nekopíruje - BXTags byly vytvořeny úplně od začátku, jen podle mých vlastních potřeb (ostatně stejně jako celé Bloxxy). Použití automatického formátování lze zcela vypnout v nastavení (v souboru bloxxy-settings.php), stejnou proměnnou se nastavuje, zda se příspěvky formátují jako HTML, nebo jako XHTML (výchozí nastavení).

BXTags primárně pracuje s odstavci. Nový odstavec určuje odřádkování, vše mezi dvěma entery (resp. začátkem/koncem textu) je jeden odstavec. Pokud není určeno jinak, odstavec se formátuje jako <p>odstavec</p>. Pouze v prípadě, kdy nový odstavec začíná znakem +, spojí se s předchozím odstavcem a + je nahrazeno značkou <br>, resp. <br /> v případě XHTML. Vše je potom zpracováváno jako jeden odstavec.

BXTags rozpoznává tři druhy formátovacích značek: celořádkové (značka na samostatném řádku), prefixy (podle prvního znaku odstavce se určí jeho formátování) a vnitřní formátování. Následuje popis jednotlivých formátovacích značek:

Celořádkové značky - odstavec obsahuje pouze:

\ ............. zastaví/spustí autoformátování
--- ........... vodorovná linka HR (tři a více pomlček)
{-- ........... začátek PRE
--} ........... konec PRE

Prefixy - odstavec začíná následujícím znakem/sekvencí (kromě + musí následovat alespoň jedna mezera):

\ cokoli ...... neformátuj tento odstavec
|| cokoli ..... odstavec je komentář
||| cokoli .... odstavec se nezobrazí
+cokoli ....... odstavec se připojí k předchozímu odstavci
: cokoli ...... odstavec je nadpis H4
:: cokoli ..... odstavec je nadpis H3
::: cokoli .... odstavec je nadpis H2
:::: cokoli ... odstavec je nadpis H1
" cokoli ...... odstavec je citací BLOCKQUOTE

=class cokoli ... odstavec dané třídy (nahradí se <p class="class">)

# cokoli ...... odstavec je položkou číslovaného seznamu OL
- cokoli ...... odstavec je položkou nečíslovaného seznamu UL
* cokoli ...... dtto
. cokoli ...... dtto

Za sebou následující položky stejného typu tvoří jeden seznam, jiný typ odstavce seznam přeruší. Vnořené seznamy proto nelze vytvořit (musíte použít [X]HTML).

Vnitřní formátování - kdekoli uvnitř textu odstavce (za případným prefixem):

*cokoli* ...................... zesílený text (STRONG)
~cokoli~ ...................... zvýrazněný text (EM)
[text|URL], [URL] ............. odkaz (A HREF=URL)
[?zkratka|popis], [?zkratka] .. zkratka (ABBR)
[@imgURL|alttext] ............. obrázek
[@imgURL|alttext|w=číslo] ..... obrázek s náhledem
[@imgURL|alttext|h=číslo] ..... obrázek s náhledem
[@imgURL|alttext|URLnáhledu] .. obrázek s náhledem
{{"cokoli}} ................... citace (Q)
{{'cokoli}} ................... citace (CITE)
{{cokoli}} .................... kód (CODE)

Speciální znaky a sekvence:

\znak   znak (\ ruší speciální význam následujícího znaku)
\\ .... \
& ..... znak & (&amp;)
_ ..... nedělitelná mezera (&nbsp;)
" ..... uvozovka (&quot;)
\> .... > (&gt;)
\< .... < (&lt;)
 -  ... sekvence mezera-divis-mezera se nahradí dlouhou pomlčkou (mezera &mdash; mezera)

Mohou se překládat také smajlíky (viz dále).


Předlohy (šablony) stránek

Předlohy stránek jsou dvou typů - předloha pro stránky a předloha pro archiv (seznam archivovaných stránek). Jejich syntaxe je obdobná, ale přece jen odlišná a předloha pro archiv podporuje podstatně méně příkazů. Předloha se vytvoří jako libovolný dokument, při generování jsou v něm pouze zaměněna klíčová slova za skutečný obsah. Předlohy tedy nemusí být nutně pouze HTML/XHTML, ale i XML, RSS, textové atd. Podobu výsledné stránky ovlivňujete sami vhodně připravenou předlohou. V adresáři Bloxxy najdete připravené jednoduché předlohy pro stránky i pro archiv, v nichž najdete příklad použití většiny klíčových slov.

Klíčová slova v předlohách stránek

Předlohy pro stránky mohou obsahovat následující klíčová slova. Jsou ohraničena znakem %. Neznámá nebo nevhodně umístěná klíčová slova se nepřekládají a zůstanou ve výsledné stránce.

Klíčová slova v příspěvku

Následující klíčová slova lze použít pouze v bloku příspěvku, jinde nemají žádný význam:

Klíčová slova v bloku DEN

Následující klíčová slova lze použít pouze v bloku DEN:

%bx_date DATE% - datum příspěvků v tomto bloku Nastavení hodnoty DATE viz níže.

Klíčová slova v předlohách archivu

Předlohy pro archiv mohou obsahovat pouze následující klíčová slova, jejich význam je obdobný jako v předlohách stránek.

Nastavení hodnoty DATE

V klíčových slovech %bx_date% v šablonách se používá parametr DATE, který popisuje formát data/času. Níže uvedené znaky a sekvence se nahradí příslušným údajem, ostatní znaky jsou ponechány, např.: %bx_date YYYY-MM-DD,HH:MIN% se zobrazí třeba jako 2003-02-27,14:06 (podle příslušného časového údaje).

Použitelné znaky a sekvence:

Pozn.: Názvy měsíců a dní v týdnu jsou uloženy v souboru s jazykovou verzí. Potřebujete-li jejich jiný tvar, upravte příslušné řetězce v tomto souboru.

Příklady:

Pro datum 4. února 2003, čas 8:52:48


Makra

S nastavením $replace_macros=true se budou překládat v příspěvcích makra. Za makro se považuje sekvence znaků mezi dvěma ^, např. ^w3^. Celá sekvence se pak nahradí řetězcem definovaným pro danou sekvenci v souboru 'bloxxy-settings.inc'.

Smajlíky

S nastavením $use_smileys=true se budou v příspěvcích nahrazovat smajlíky obrázky. Textový smajlík musí být ohraničen mezerami, sousedí-li s jinými znaky, nahrazen nebude. Nastavení použitých obrázků je v souboru 'bloxxy-settings.inc'. Základní instalace Bloxxy obsahuje nejčastěji používané smajlíky a pokud vám stačí, nic měnit nemusíte. Bloxxy nyní překládá tyto smajlíky:

 :)  :-)  (:-)  atd.         smile
 :)) :-))  :-D  (:-D  atd.   laught
 ;) ;-)                      blink
 :[  ):-[  atd.              grr
 :/  (:-/                    hmm
 :-o  (:0  :-O  atd.         oops
 :(  ):-( atd.               sad

Import dat z Bloggeru

Do Bloxxy lze naimportovat stávající archivy z Bloggeru. Chcete-li své starší blogy naimportovat, musíte postupně provést následující kroky:

  1. V nastavení svého bloggu na Blogger.com (Settings) nastavte zobrazení data a času (Date/Time format) na plný formát (M/D/YYY H:M:S AM/PM) a uložte.
  2. Otevřete šablonu (Template) a těsně kolem těla položky ($BlogItemBody$) umístěte následující komentáře:
    <!--BLOGITEM|<$BlogItemDateTime$>|<$BlogItemAuthor$>|<$BlogItemAuthorEmail$>-->
    <$BlogItemBody$>
    <!--BLOGITEMEND-->

    (pokud nepoužíváte jméno, ale přezdívku, místo $BlogItemAuthor$ použijte $BlogItemAuthorNickname$)
  3. Uložte šablonu a přegenerujte archivy (nebo jen ty, které chcete importovat)
  4. V Bloxxy zvolte "Blogger import" a zadejte URL archivu, který chcete načíst, a skupinu, do níž se mají importované příspěvky vložit.

Protože Bloxxy používá jako ID příspěvku kód odpovídající času jeho vložení, nemělo by se stát, že se importem nějaké příspěvky přepíší (musely by mít na sekundu shodné časy). Pokud si ale myslíte, že to hrozí, raději si data v Bloxxy předem zazálohujte (pravděpodobnost je ale velmi malá).

Zálohování dat z Bloxxy

Bloxxy nepoužívá žádnou databázi a příspěvky jsou generované do statických stránek. Protože ty je možné kdykoli během okamžiku všechny znovu vygenerovat, důležité je zálohovat si především zdrojová data. Ta jsou uložena v samostatném adresáři bloxxy-data (obsahuje texty příspěvků, nastavení skupin a publikací), který si stačí jednoduše zkopírovat na lokální disk. Soubor bloxxy-settings.php je třeba zálohovat jen kvůli provedeným nastavením - obsahuje nastavení aplikace, předdefinovaná makra (pokud jste je měnili) i nastavení smajlíků (pokud jste je měnili). Případně si zazálohujte i své šablony.


Komentáře

Možnost přidávat k příspěvkům komentáře čtenářů byla k Bloxxy připojena dodatečně (ve verzi 0.4). Zpracování komentářů není jeho přímou součástí, tvoří ho samostatný "modul", soubor comments.php. Pokud komentáře nechcete používat, nemusíte nic dělat, v samotném Bloxxy se nic nemění. Pokud je používat chcete, v konfiguračním souboru bloxxy-settings.php nastavte proměnné $path_to_comments a $comments_template a vytvořte adresář, kam se budou komentáře ukládat (Bloxxy v něm musí mít právo čtení a zápisu).

Nastavení šablon

V šabloně pro zobrazení příspěvků pak lze navíc použít následující klíčová slova (v bloku %bx_item%)

V šabloně pro komentáře lze použít tato klíčová slova:

Pozn.: Vzhled seznamu příspěvků a formuláře můžete ovlivnit pomocí CSS, případně zásahem do zdrojového kódu.

Používání komentářů

Chcete-li umožnit přidávání komentářů k příspěvkům, stačí do šablony vložit klíčové slovo %bx_item_commentlink%, zbytek už obstará Bloxxy. Za klíčové slovo %bx_item_commentcnt% se vkládá počet dosud přidaných komentářů - použít jej lze ovšem jen za jistých podmínek. Aby byl počet komentářů vždy aktuální (zobrazuje se ve staticky vygenerované stránce), je sem vložen jako obrázek (PNG). Tento obrázek není statický, generuje jej dynamicky skript comments.php - a je proto nutné mít nainstalované PHP s podporou generování grafiky. Bez ní tuto funkci nelze používat.

Pozn.: Pokud comments.php zavoláte bez parametrů, zobrazí se 20 nejnovějších komentářů seřazených podle času.

Pozn. 2: Pokud chcete, aby vám každý nový komentář chodil mailem, odkomentujte a upravte si řádek 132 v souboru comments.php - zadejte e-mailovou adresu, na kterou se mají komentáře posílat, upravte URL svého blogu, a případně změňte použité kódování na konci řádku.


To je asi vše.

Bloxxy je pouze betaverze, použití je na vaše vlastní nebezpečí. Oznámení závažných chyb a smysluplné připomínky vítám, reptání a stížnosti si nechte od cesty.

-pixy-