Batflat/docs/pl.md

Ogólne

Batflat to polski system zarządzania treścią, który jest prosty, lekki i szybki. Po raz pierwszy został wydany w maju 2016. Darmowa wersja aplikacji jest udostępniona w ramach licencji, która wymaga pozostawienia informacji o autorach oraz linku zwrotnego. Batflat sprawdza się świetnie podczas tworzenia małych serwisów, takich jak wizytówki firmowe, portfolia, blogi czy strony domowe. Dzięki tej dokumentacji dowiesz się jak go zainstalować, skonfigurować, a także jak tworzyć własne moduły i motywy.

Dokumentacja została podzielona na kilka sekcji. Pierwsza dotyczy ogólnych instrukcji, druga jest skierowana do web designerów, a dwie ostatnie do web deweloperów.

Wymagania

Wymagania systemowe dla Batflata są skromne, zatem powinien je spełnić każdy nowoczesny serwer WWW:

• Apache 2.2+ z trybem mod_rewrite
• PHP w wersji 5.6+
• Dostęp do SQLite

Konfiguracja PHP musi posiadać następujące rozszerzenia:

• dom
• gd
• mbstring
• pdo
• zip
• cURL

Instalacja

Na początek należy pobrać najnowszą wersję Batflata.

Wypakuj wszystkie pliki ze skompresowanej paczki, a następnie przenieś je do katalogu lokalnego lub zdalnego serwera. W przypadku serwera zdalnego, należy połączyć się z nim poprzez klienta (S)FTP, np. darmowym programem FileZilla. Zazwyczaj pliki należy wgrać do folderu www, htdocs lub public_html.

Uwaga! Upewnij się, że plik .htaccess również znalazł się na serwerze. Bez niego skrypt nie będzie działał.

Niektóre serwery mogą wymagać nadania dodatkowych uprawnień chmod 777 dla następujących katalogów i plików:

• tmp/
• uploads/
• admin/tmp/
• inc/data/
• inc/data/database.sdb

Otwórz przeglądarkę i przejdź do adresu, w którym zlokalizowane są pliki Batflata. Powinien ukazać się domyślny szablon wraz z przykładową treścią.

Aby przejść do panelu administracyjnego, dodaj /admin/ na koniec adresu. Początkowy login i hasło to "admin". Wypada je zmienić zaraz po zalogowaniu ze względów bezpieczeństwa. Zalecamy również zmianę nazwy katalogu z panelem administracyjnym (trzeba wtedy zmienić wartość stałej w pliku defines).

Konfiguracja

CMS można skonfigurować poprzez edycję ustawień w panelu administracyjnym oraz poprzez plik z definicjami. Nie zalecamy jednak zmieniać konfiguracji w pliku, jeżeli jesteś osobą niedoświadczoną.

Panel administracyjny

Aby zmienić podstawową konfigurację w panelu administracyjnym, wybierz zakładkę Ustawienia. Możesz wprowadzić tam nazwę strony, jej opis czy słowa kluczowe, które będą zawarte w meta-tagach, a także w innych miejscach szablonu domyślnego, np. w nagłówku. Zmienisz tutaj również stronę startową, domyślny język (zarówno dla strony jak i panelu), zdefiniujesz treść stopki oraz wybierzesz rodzaj edytora (HTML lub WYSIWYG), który będzie dostępny podczas edycji podstron oraz wpisów na blogu.

Konfigurację pozostałych modułów zmienisz w zakładkach odpowiadających ich nazwie.

Plik defines

Bardziej zaawansowane rzeczy możesz zmienić w pliku inc/core/defines.php, który zawiera definicje stałych wartości.

• ADMIN — nazwa katalogu zawierająca panel administracyjny
• THEMES — ścieżka do katalogu zawierającego motywy
• MODULES — ścieżka do katalogu zawierającego moduły
• UPLOADS — ścieżka do katalogu zawierającego wgrane pliki
• FILE_LOCK — blokada możliwości edycji plików poprzez panel administracyjny
• BASIC_MODULES — lista podstawowych modułów, których nie można usunąć
• HTML_BEAUTY — ładne formatowanie kodu HTML po jego przeparsowaniu
• DEV_MODE — tryb dewelopera, podczas którego pokazywane są błędy i notatki PHP

Aktualizacja

Jeżeli chcesz być na bieżąco wraz ze wszelkimi nowościami oraz poprawkami błędów i zabezpieczeń, powinieneś regularnie sprawdzać aktualizacje Batflata. Możesz to zrobić w zakładce Ustawienia -> Aktualizacje. System sprawdzi czy dostępna jest nowa wersja skryptu oraz automatycznie pobierze z naszego serwera nową paczkę i zaktualizuje pliki rdzenia oraz modułów.

W przypadku komplikacji (np. niepowodzenia pobrania nowej paczki) możesz skorzystać z trybu manualnego. W tym celu należy ręcznie pobrać najnowszą wersję Batflata, wgrać ją do głównego katalogu aplikacji, a następnie na końcu adresu URL zakładki z aktualizacją dodać parametr &manual. CMS powinien wykryć wgraną paczkę ZIP i po kliknięciu w przycisk aktualizacji, przeprowadzić proces wypakowania i nadpisania plików.

Przed każdą aktualizacją, Batflat wykonuje kopię zapasową. Znajdziesz ją w katalogu skryptu, w folderze backup/. W razie niepowodzenia przeprowadzonej aktualizacji, możesz w każdej chwili ją przywrócić.

Motywy

Struktura

Struktura motywów w Batflacie jest bardzo prosta. Wystarczy utworzyć nowy folder z nazwą motywu w katalogu themes/ oraz następujące pliki:

• index.html — domyślny szablon dla podstron
• manifest.json — informacje o motywie
• preview.png — zrzut ekranu przedstawiający motyw (opcjonalne)

Każda podstrona może korzystać z innego szablonu, zatem prócz wspomnianego pliku możesz utworzyć także inne, np. xyz.html. Wybór szablonu jest dostępny w panelu administracyjnym podczas tworzenia strony. Nie ma określonych reguł co do plików CSS oraz JS. Panuje pełna dowolność.

W katalogu motywu możesz również stworzyć własne widoki modułów. Aby to zrobić, musisz utworzyć katalog modules/nazwa_modułu/ oraz pliki *.html z nazwami odpowiadającymi nazwom oryginalnych widoków. Przykładowo, widok modułu formularza kontaktowego powinien być zawarty w następującej ścieżce: themes/nazwa_motywu/modules/contact/form.html. Batflat automatycznie wykryje nowy widok i użyje go zamiast domyślnego widoku modułu.

Tagi szablonów

CMS korzysta z prostego systemu szablonów, który zawiera następujące tagi:

Zmienne

{$foo}        // zwykła zmienna
{$foo|e}      // HTML escape dla zmiennej
{$foo|cut:10} // zawartość zmiennej ucięta do 10 znaków
{$foo.bar}    // tablica

Dostęp do elementów tablicy odbywa się poprzez znak kropki.

Warunki

{if: $foo > 5}
    lorem
{elseif: $foo == 5}
    ipsum
{else}
    dolor
{/if}

Pętle

<ul>
{loop: $foo}
    <li>{$key}, {$value}, {$counter}</li>
{/loop}

{loop: $foo as $bar}
    <li>{$key}, {$bar}, {$counter}</li>
{/loop}

{loop: $foo as $bar => $baz}
    <li>{$bar}, {$baz}, {$counter}</li>
{/loop}
</ul>

Tag pętli posiada 3 stopnie rozbudowania. W pierwszym wystarczy zmienna tablicowa, którą system szablonów rozbije na trzy zmienne o nazwach $key, $value oraz $counter, która zlicza kolejne iteracje począwszy od zera. Drugi stopień pozwala określić nazwę zmiennej przechowującą wartość, zaś trzeci również nazwę zmiennej indeksu.

Dołączanie plików szablonu

<html>
    <body>
    {template: header.html}
    <main>
        <p>Lorem ipsum dolor sit amet.</p>
    </main>
    {template: footer.html}
    </body>
</html>

Kod PHP

Dzisiejsza data: {?= date('Y-m-d') ?}

Jeżeli opuścisz znak =, kod jedynie się wykona i nic nie wyświetli. Dzięki temu można, np. zdefiniować nowe zmienne wewnątrz szablonu:

{? $foo = 5 ?}

Wyłączenie parsowania

{noparse}Użyj tagu {$contact.form}, aby wyświetlić formularz kontaktowy.{/noparse}

Wszelkie tagi wewnątrz wyrażenia noparse pozostaną w niezmienionym stanie.

Komentarze

{* to jest komentarz *}

Komentarze nie są widoczne w pliku źródłowym po skompilowaniu szablonu.

Języki

{lang: pl_polski}
    Witaj świecie!
{/lang}
{lang: en_english}
    Hello world!
{/lang}

Jeżeli chcesz dostosować elementy szablonu do konkretnego języka, użyj powyższych tagów.

Zmienne systemowe

Batflat, podobnie jak i jego moduły, dostarcza wiele zmiennych (zazwyczaj tablicowych), które służą do wyświetlania poszczególnych elementów strony. Oto najważniejsze z nich:

• {$settings.pole} — element tablicy zawierający wartość danego pola ustawień Batflata
• {$settings.moduł.pole} — element tablicy zawierający wartość danego pola ustawień modułu
• {$bat.path} — przechowuje ścieżkę, w której znajduje się system
• {$bat.lang} — wyświetla aktualnie wykorzystywany język
• {$bat.notify} — ostatnie powiadomienie
• {$bat.notify.text} - tekst powiadomienia
• {$bat.notify.type} - typ komunikatu odpowiadający klasom bootstrapa (danger, success)
• {$bat.header} — dodatkowe meta-tagi, skrypty JS i arkusze stylów CSS ładowane przez moduły
• {$bat.footer} — dodatkowe skrypty JS ładowane przez moduły
• {$bat.theme} — wyświetla ścieżkę do aktywnego szablonu strony wraz z hostem
• {$bat.powered} — wyświetla napis Powered by Batflat z linkiem do oficjalnej strony
• {$navigation.xyz} — wyświetla listę <li> elementów danej nawigacji
• {$page.title} — wyświetla nazwę podstrony
• {$page.content} — wyświetla zawartość podstrony

Przykład

manifest.json

{
    "name": "Example",
    "version": "1.0",
    "author": "Bruce Wayne",
    "email": "contact@waynecorp.com",
    "thumb": "preview.png"
}

index.html

<!doctype html>

<html>
<head>
  <meta charset="utf-8">
  <title>{$page.title} - {$settings.title}</title>
  <meta name="description" content="{$settings.description}">
  <meta name="keywords" content="{$settings.keywords}">
  <link rel="stylesheet" href="{$bat.theme}/styles.css">
  {loop: $bat.header}{$value}{/loop}
</head>

<body>
    <nav>
        <ul>
            {$navigation.main}
        </ul>
    </nav>
    
    <main>
        <h1>{$page.title}</h1>
        {$page.content}
    </main>
    
    <footer>
        {$settings.footer} {$bat.powered}
    </footer>
   
    <script src="{$bat.theme}/scripts.js"></script>
    {loop: $bat.footer}{$value}{/loop}
</body>
</html>

Moduły

Struktura

Każdy moduł, podobnie jak motywy, musi znajdować się w osobnym folderze utworzonym w ścieżce inc/modules/. Należy zwrócić uwagę na to, by katalog nie zawierał wielkich liter oraz znaków specjalnych, np. spacji.

Podczas tworzenia modułu należy zastanowić się nad tym, jakiego typu ma być to moduł. Czy ma być konfiguralny w panelu administracyjnym, czy może ma działać wyłącznie po stronie gości odwiedzających stronę? Ze względu na taki podział, w Batflacie wyróżniamy trzy główne pliki modułu:

• Info.php — zawiera informacje o module, takie jak nazwa, opis, autor czy ikona
• Admin.php — zawartość tego pliku będzie dostępna poprzez panel administracyjny
• Site.php — zawartość tego pliku będzie dostępna dla gości odwiedzających stronę

Czwartym, lecz opcjonalnym plikiem jest ReadMe.md, który powinien zawierać dodatkowe informacje dla przyszłego użytkownika zapisane w jęzku Markdown, np. sposób używania modułu.

Jeżeli planujesz napisać moduł, który będzie używał HTML, to dobrze byłoby zadbać o to, by kod PHP był oddzielony od hipertekstowego języka znaczników. W tym celu, wewnątrz folderu z modułem, musisz utworzyć katalog views. W nim składuj wszelkie pliki widokowe.

Podobnie wygląda sprawa z wielojęzycznością modułu. Wystarczy stworzyć pliki językowe z rozszerzeniem ini wewnątrz katalogu lang.

Struktura modułu powinna wyglądać mniej więcej w taki sposób:

example/
|-- lang/
|    |-- admin/
|    |    |-- en_english.ini
|    |    |-- pl_polski.ini
|    |-- en_english.ini
|    |-- pl_polski.ini
|-- views/
|    |-- admin/
|    |    |-- bar.html
|    |-- foo.html
|-- Admin.php
|-- Info.php
|-- Site.php
+-- ReadMe.md

Tworzenie modułu

Plik Info

Najważniejszy plik każdego modułu. To w nim zawarte są podstawowe informacje oraz polecenia wykonywane podczas instalacji oraz deinstalacji.

<?php

    return [
        'name'          =>  'Example',                  // Nazwa
        'description'   =>  'Lorem ipsum....',          // Opis
        'author'        =>  'Robin',                    // Autor
        'version'       =>  '1.0',                      // Wersja
        'compatibility' =>  '1.3.*',                    // Kompatybilność z wersją Batflata
        'icon'          =>  'bolt',                     // Ikona
        
        'pages'         =>  ['Example' => 'example'],   // Rejestracja jako strona (opcjonalne)

        'install'       =>  function() use($core)       // Polecenia instalacji
        {
            // lorem ipsum...
        },
        'uninstall'     =>  function() use($core)       // Polecenia deinstalacji
        {
            // lorem ipsum...    
        }
    ];

Lista ikon, które możesz użyć w tym pliku, znajduje się na stronie fontawesome.io. Pamiętaj, by nie wprowadzać nazwy ikony z przedrostkiem fa-.

Rejestracja modułu jako strony pozwala na swobodniejsze stosowanie routingu oraz wybranie go jako stronę startową.

Plik Admin

Zawartość tego pliku będzie uruchomiona w panelu administracyjnym.

<?php
    namespace Inc\Modules\Example;

    use Inc\Core\AdminModule;

    class Admin extends AdminModule
    {
        public function init()
        {
            // Procedury wywoływane przy inicjalizacji modułu
        }

        public function navigation()
        {
            return [
                'Foo'   => 'foo',
                'Bar'   => 'bar',
            ];
        }

        public function getFoo($parm)
        {
            return "Foo $parm!";
        }

        public function postBar()
        {
            return "Bar!";
        }
    }

W metodzie navigation należy zawrzeć tablicę z podstronami modułu. Do każdej z podstron powinna być przypisana jakaś metoda (bez prefiksu). Elementy tej tablicy zostaną wyświetlone w menu panelu administracyjnego.

Metody mogą przyjmować również argumenty, które są przekazywane poprzez adres URL. Przykładowo, po wprowadzeniu adresu /example/foo/abc, metoda getFoo zwróci tekst "Foo abc!".

Jak można zauważyć w powyższym listingu, każda metoda reprezentująca podstronę modułu powinna być opatrzona prefiksem określającym typ żądania. W większości przypadków będziemy stosować nazewnictwo getFoo, zaś dla przesyłanych formularzy postFoo. Jeżeli metoda ma obsługiwać wszystkie typy, to powinna być poprzedzona prefiksem any *(przykładowo: anyFoo)*s. Jest to ważne, ponieważ bez prefixu strony nie będą obsłużone. Obsłużone metody są tłumaczone przez dynamiczny routing w następujący sposób:

• getFoo() — jako /example/foo dla żądania typu GET
• getFoo($parm) — jako /example/foo/abc dla żądania typu GET
• postBar() — jako example/bar dla żądania typu POST (przesyłanie formularzy)
• anyFoo() — jako /example/foo dla każdego rodzaju żądania

Plik Site

Plik ten odpowiada za część widzianą przez gości odwiedzających stronę. Jeżeli moduł jest dość spory, dobrą praktyką jest zarejestrowanie go jako strony i zastosowanie routingu.

<?php

    namespace Inc\Modules\Example;
    
    use Inc\Core\SiteModule

    class Site extends SiteModule
    {
        public function init()
        {
            $this->_foo();
        }

        public function routes()
        {
            $this->route('example', 'mySite');
        }

        public function mySite()
        {
            $page = [
                'title' => 'Sample title..',
                'desc' => 'Site description',
                'content' => 'Lorem ipsum dolor...'
            ];

            $this->setTemplate('index.html');
            $this->tpl->set('page', $page);
        }

        private function _foo()
        {            
            $this->tpl->set('bar', 'Why So Serious?');
        }
    }

W powyższym przykładzie została utworzona nowa zmienna szablonowa bar, która poprzez wywołanie metody _foo() w inicjalizatorze modułu, będzie mogła być użyta w plikach motywu jako {$bar}. Dodatkowo w metodzie routes() został utworzony routing do podstrony /example, wskazujący wywołanie metody mySite(). Jeżeli przejdziemy pod adres http://example.com/example zostanie wywołana metoda mySite() modułu.

Pliki językowe

Moduł może zawierać zmienne językowe, z których można korzystać zarówno w klasach, jak i widokach. Pliki językowe posiadają rozszerzenie .ini, a ich miejsce znajduje się w katalogu lang danego modułu. Przykładowo, jeżeli chcesz dodać plik językowy zawierający angielskie wyrażenia dla części administracyjnej modułu Example, pownieneś utworzyć nowy plik w ścieżce inc/modules/example/lang/admin/en_english.ini. Zawartość powinna przypominać poniższy listing:

full_name           = "Firstname and surname"
email               = "E-mail"
subject             = "Subject"
message             = "Message"
send                = "Send"
send_success        = "Mail successfully sent. I will contact you soon."
send_failure        = "Unable to send a message. Probably mail() function is disabled on the server."
wrong_email         = "Submited e-mail address is incorrect."
empty_inputs        = "Fill all required fields to send a message."
antiflood           = "You have to wait a while before you will send another message."

Aby skorzystać z utworzonych zmiennych w klasie modułu należy użyć konstrukcji $this->lang('subject'), zaś w widoku {$lang.example.subject}. W przypadku klasy możemy opuścić drugi parametr metody lang jakim jest nazwa modułu, z którego będzie pobierane tłumaczenie.

Routing

Routing to proces przetwarzania otrzymanego adresu żądania i na jego podstawie decydowanie, co powinno zostać uruchomione lub wyświetlone. Ma on za zadanie wywołać odpowiednią metodę/funkcję na podstawie adresu URL strony. Z routingu należy korzystać wewnątrz publicznej metody routes().

void route(string $pattern, mixed $callback)

Pierwszym parametrem metody route jest wyrażenie regularne. Niektóre z wyrażeń zostały już zdefiniowane:

• :any — dowolny ciąg znaków
• :int — liczby całkowite
• :str — ciąg znaków będący slugiem

Drugim parametrem jest nazwa metody lub anonimowa funkcja, która przekazuje dowolną liczbę argumentów zdefiniowanych w wyrażeniu regularnym.

Przykład

public function routes()
{
    // URL: http://example.com/blog

    // - poprzez wywołanie metody wewnątrz modułu:
    $this->route('blog', 'importAllPosts');

    // - poprzez wywołanie anonimowej funkcji:
    $this->route('blog', function() {
        $this->importAllPosts();
    });

    // URL: http://example.com/blog/2
    $this->route('blog/(:int)', function($page) {
        $this->importAllPosts($page);
    });

    // URL: http://example.com/blog/post/lorem-ipsum
    $this->route('blog/post/(:str)', function($slug) {
        $this->importPost($slug);
    });

    // URL: http://example.com/blog/post/lorem-ipsum/4
    $this->route('blog/post/(:str)/(:int)', function($slug, $page) {
        $this->importPost($slug, $page);
    });
}

Metody

Moduły posiadają specjalne fasady, które ułatwiają dostęp do metod wewnątrz rdzenia. Dzięki temu można skrócić wywołania typu $this->core->foo->bar.

db

void db([string $table])

Umożliwia operowanie na bazie danych. Szczegóły zostały opisane w sekcji rdzenia.

Argumenty

• table — nazwa tabeli bazy danych (opcjonalne)

Przykład

$this->db('table')->where('age', 20)->delete();

draw

string draw(string $file [, array $variables])

Zwraca skompilowany kod widoku, w którym wcześniej zostały użyte tagi systemu szablonów. Pozwala również na zdefiniowanie zmiennych zastępując metodę set().

Argumenty

• file — nazwa pliku z widokiem wewnątrz modułu lub ścieżka do pliku znajdującego się poza nim
• variables — tablica z definicją zmiennych, które będzie można wykorzystać jako tagi (opcjonalne)

Przykład

// Kompilacja widoku znajdującego się wewnątrz modułu
$this->draw('form.html', ['form' => $this->formFields]);

// Kompilacja widoku znajdującego się poza modułem
$this->draw('../path/to/view.html', ['foo' => 'bar']);

lang

string lang(string $key [, string $module])

Zwraca zawartość klucza tablicy językowej z aktualnego modułu bądź wskazanego poprzez drugi argument.

Argumenty

• key — nazwa klucza tablicy językowej
• module — nazwa modułu, z którego ma zostać pobrany klucz (opcjonalne)

Przykład

// Odwołanie się do tłumaczenia lokalnego
$this->lang('foo');                 // $this->core->lang['module-name']['foo'];

// Odwołanie się do ogólnego tłumaczenia
$this->lang('cancel', 'general');   // $this->core->lang['general']['cancel'];

// Odwołanie się do tłumaczenia modułu "pages"
$this->lang('slug', 'pages')        // $this->core->lang['pages']['slug'];

notify

void notify(string $type, string $text [, mixed $args [, mixed $... ]])

Umożliwia wywołanie notyfikacji dla użytkownika.

Argumenty

• type — rodzaj powiadomienia: success lub failure
• text — treść powiadomienia
• args — dodatkowe argumenty (opcjonalne)

Przykład

$foo = 'Bar';
$this->notify('success', 'This is %s!', $foo); // $this->core->setNotify('success', 'This is %s!', $foo);

settings

mixed settings(string $module [, string $field [, string $value]])

Pobiera lub ustawia wartość ustawień danego modułu.

Argumenty

• module — nazwa modułu i opcjonalnie nazwa pola oddzielona kropką
• field — nazwa pola modułu (opcjonalne)
• value — wartość na jaką zostanie zmienione pole modułu (opcjonalne)

Przykład

// Pobranie pola "desc" z modułu "blog"
$this->settings('blog.desc');    // $this->core->getSettings('blog', 'desc');

// Pobranie pola "desc" z modułu "blog"
$this->settings('blog', 'desc'); // $this->core->getSettings('blog', 'desc');

// Ustawienie zawartości pola "desc" z modułu "blog"
$this->settings('blog', 'desc', 'Lorem ipsum...');

setTemplate

void setTemplate(string $file)

Umożliwia podmianę pliku z szablonem na froncie. Metoda działa wyłącznie w klasie Site.

Argumenty

• file — nazwa pliku z szablonem

Przykład

$this->setTemplate('index.html'); // $this->core->template = 'index.html';

Rdzeń

Jest to swoiste jądro / silnik Batflata, czyli najważniejsza część, która jest odpowiedzialna za wszystkie jego podstawowe zadania. Rdzeń zawiera wiele definicji stałych, funkcji i metod, które możesz wykorzystać podczas pisania modułów.

Stałe

Wszelkie definicje stałych zostały opisane w pierwszej części tej dokumentacji. Aby z nich skorzystać, wystarczy w pliku PHP wywołać ich nazwy. Stałe szczególnie przydają się przy budowie adresów URL i ścieżek do plików.

Przykład

echo MODULES.'/contact/view/form.html';

Funkcje

Batflat posiada kilka wbudowanych funkcji pomocniczych, które ułatwiają tworzenie modułów.

domain

string domain([bool $with_protocol = true])

Zwraca nazwę domeny z protokołem http(s) lub bez.

Argumenty

• with_protocol — decyduje czy adres zostanie zwrócony z protokołem czy bez

Wartość zwracana

Tekst z nazwą domeny.

Przykład

echo domain(false);
// Wynik: example.com

checkEmptyFields

bool checkEmptyFields(array $keys, array $array)

Sprawdza czy tablica zawiera puste elementy. Przydaje się podczas walidacji formularzy.

Argumenty

• keys — lista elementów tablicy, które funkcja ma sprawdzić
• array — tablica źródłowa

Wartość zwracana

Zwraca TRUE, gdy przynajmniej jeden element jest pusty. FALSE, gdy wszystkie elementy są uzupełnione.

Przykład

if(checkEmptyFields(['name', 'phone', 'email'], $_POST) {
    echo 'Wypełnij wszystkie pola!';
}

currentURL

string currentURL([bool $query = false])

Zwraca aktualny adres URL.

Argumenty

• query — decyduje czy adres zostanie zwrócony ze zmiennymi czy bez

Przykład

echo currentURL();
// Wynik: http://example.com/contact

echo currentURL(true);
// Wynik: http://example.com/contact?foo=bar

createSlug

string createSlug(string $text)

Zamienia w tekście znaki językowe na bez ogonków, spacje na myślniki oraz usuwa znaki specjalne. Służy do tworzenia slugów w adresach URL i nazw zmiennych w systemie szablonów.

Argumenty

• text — tekst do konwersji

Wartość zwracana

Zwraca tekst w postaci slugu.

Przykład

echo createSlug('Być albo nie być; oto jest pytanie!');
// Wynik: byc-albo-nie-byc-oto-jest-pytanie

deleteDir

bool deleteDir(string $path)

Rekurencyjna funkcja, która usuwa katalog wraz z całą zawartością.

Argumenty

• path — ścieżka do katalogu

Wartość zwracana

Zwraca TRUE w przypadku sukcesu lub FALSE przy niepowodzeniu.

Przykład

deleteDir('foo/bar');

getRedirectData

mixed getRedirectData()

Zwraca dane przekazane do sesji podczas użycia funkcji redirect().

Wartość zwracana

Tablica lub null.

Przykład

$postData = getRedirectData();

htmlspecialchars_array

string htmlspecialchars_array(array $array)

Zamienia znaki specjalne z elementów tablicy na encje HTML.

Argumenty

• array — tablica, która zostanie przekonwertowana

Wartość zwracana

Zwraca skonwertowany tekst.

Przykład

$_POST = htmlspecialchars_array($_POST);

isset_or

mixed isset_or(mixed $var [, mixed $alternate = null ])

Zamienia pustą zmienną na wartość alternatywną.

Argumenty

• var — zmienna
• alternate — wartość zastępcza zmiennej (opcjonalne)

Wartość zwracana

Zwraca wartość alternatywną.

Przykład

$foo = isset_or($_GET['bar'], 'baz');

parseURL

mixed parseURL([ int $key = null ])

Parsuje aktualny adresu URL skryptu.

Argumenty

• key — numer parametru adresu URL (opcjonalne)

Wartość zwracana

Tablica lub jej pojedynczy element.

Przykład

// URL: http://example.com/foo/bar/4

var_dump(parseURL())
// Wynik:
// array(3) {
//   [0] =>
//   string(3) "foo"
//   [1] =>
//   string(3) "bar"
//   [2] =>
//   int(4)
// }

echo parseURL(2);
// Wynik: "bar"

redirect

void redirect(string $url [, array $data = [] ])

Przekierowanie do wskazanego adresu URL. Pozwala ona na zapisanie danych z tablicy do sesji. Przydaje się do zapamiętywania niezapisanych danych z formularzy.

Argumenty

• url — adres, na który nastąpi przekierowanie
• data — tablica, która będzie przekazana do sesji (opcjonalne)

Przykład

redirect('http://www.example.com/');

// Zapisanie tablicy do sesji:
redirect('http://www.example.com/', $_POST);

url

string url([ mixed $data = null ])

Tworzy bezwzględny adres URL. W panelu administracyjnym automatycznie dodaje token.

Argumenty

• data — tekst lub tablica

Wartość zwracana

Bezwzględny adres URL.

Przykład

echo url();
// Wynik: http://example.com

echo url('foo/bar')
// Wynik: http://example.com/foo/bar

echo url('admin/foo/bar');
// Wynik: http://example.com/admin/foo/bar?t=[token]

echo url(['admin', 'foo', 'bar']);
// Wynik: http://example.com/admin/foo/bar?t=[token]

Metody

Prócz funkcji, istnieje kilka istotnych metod, które przyspieszają proces tworzenia nowych funkcjonalności systemu.

addCSS

void addCSS(string $path)

Importuje plik CSS w nagłówku motywu.

Argumenty

• path — adres URL do pliku

Przykład

$this->core->addCSS('http://example.com/style.css');
// Wynik: <link rel="stylesheet" href="http://example.com/style.css" />

addJS

void addJS(string $path [, string $location = 'header'])

Importuje plik JS w nagłówku lub stopce motywu.

Argumenty

• path — adres URL do pliku
• location — lokalizacja: header lub footer (opcjonalne)

Przykład

$this->core->addJS('http://example.com/script.js');
// Wynik: <script src="http://example.com/script.js"></script>

append

void append(string $string, string $location)

Dodaje do nagłówka lub stopki ciąg znaków.

Argumenty

• string — ciąg znaków
• location — lokalizacja: header lub footer

Przykład

$this->core->append('<meta name="author" content="Bruce Wayne">', 'header');

getModuleInfo

array getModuleInfo(string $dir)

Zwraca informacje o module. Metoda działa wyłącznie w klasie Admin.

Argumenty

• name — nazwa katalogu modułu

Wartość zwracana

Tablica z informacjami.

Przykład

$foo = $this->core->getModuleInfo('contact');

getSettings

mixed getSettings([string $module = 'settings', string $field = null])

Pobiera wartość ustawień danego modułu. Domyślnie są to główne ustawienia Batflata.

Argumenty

• module — nazwa modułu (opcjonalne)
• field — pole z definicją ustawienia (opcjonalne)

Wartość zwracana

Tablica lub tekst.

Przykład

echo $this->core->getSettings('blog', 'title');

getUserInfo

string getUserInfo(string $field [, int $id ])

Zwraca informacje o zalogowanym użytkowniku lub o danym ID. Metoda działa wyłącznie w klasie Admin.

Argumenty

• field — nazwa pola w bazie danych
• id — numer identyfikacyjny (opcjonalne)

Wartość zwracana

Ciąg znaków z wybranego pola.

Przykład

// Aktualnie zalogowany użytkownik
$foo = $this->core->getUserInfo('username');

// Użytkownik o danym ID
$foo = $this->core->getUserInfo('username', 1);

setNotify

void setNotify(string $type, string $text [, mixed $args [, mixed $... ]])

Generuje notyfikację.

Argumenty

• type — rodzaj powiadomienia: success lub failure
• text — treść powiadomienia
• args — dodatkowe argumenty (opcjonalne)

Przykład

$foo = 'Bar';
$this->core->setNotify('success', 'Pomyślnie zainstalowano moduł %s!', $foo);
// Wynik: "Pomyślnie zainstalowano moduł Bar!"

Baza danych

Zastosowana w Batflacie baza danych to SQLite w wersji 3. Do jej obsługi CMS wykorzystuje prostą klasę, która ułatwia budowanie zapytań. Nie musisz znać języka SQL, by móc na niej operować.

Dodatkowo polecamy narzędzie phpLiteAdmin do zarządzania bazą. Jest to jednoplikowy skrypt PHP, podobny do phpMyAdmin, przy pomocy którego można administrować tabelami Batflata. Pozwoli on zapoznać się ze strukturą istniejących tabel. Plik bazy znajduje się w inc/data/database.sdb.

SELECT

Pobieranie wielu rekordów:

// JSON
$rows = $this->core->db('table')->toJson();

// Tablica
$rows = $this->core->db('table')->select('foo')->select('bar')->toArray();

// Obiekt
$rows = $this->core->db('table')->select(['foo', 'b' => 'bar'])->toObject();

Pobieranie pojedycznego rekordu:

// JSON
$row = $this->core->db('table')->oneJson();

// Tablica
$row = $this->core->db('table')->select('foo')->select('bar')->oneArray();

// Obiekt
$row = $this->core->db('table')->select(['foo', 'b' => 'bar'])->oneObject();

WHERE

Wybór wiersza o określonym numerze w kolumnie id:

$row = $this->core->db('table')->oneArray(1);
// lub
$row = $this->core->db('table')->oneArray('id', 1);
// lub
$row = $this->core->db('table')->where(1)->oneArray();
// lub
$row = $this->core->db('table')->where('id', 1)->oneArray();

Złożone warunki:

// Pobranie wierszy, których wartość kolumny 'foo' jest WIĘKSZA od 4
$rows = $this->core->db('table')->where('foo', '>', 4)->toArray();

// Pobranie wierszy, których wartość kolumny 'foo' jest WIĘKSZA od 4 i MNIEJSZA od 8
$rows = $this->core->db('table')->where('foo', '>', 4)->where('foo', '<', 8)->toArray();

OR WHERE:

// Pobranie wierszy, których wartość kolumny 'foo' jest RÓWNA 4 LUB 8
$rows = $this->core->db('table')->where('foo', '=', 4)->orWhere('foo', '=', 8)->toArray();

WHERE LIKE:

// Pobranie wierszy, których kolumna 'foo' ZAWIERA ciąg znaków 'bar' LUB 'baz'
$rows = $this->core->db('table')->like('foo', '%bar%')->orLike('foo', '%baz%')->toArray();

WHERE NOT LIKE:

// Pobranie wierszy, których kolumna 'foo' NIE ZAWIERA ciągu znaków 'bar' LUB 'baz'
$rows = $this->core->db('table')->notLike('foo', '%bar%')->orNotLike('foo', '%baz%')->toArray();

WHERE IN:

// Pobranie wierszy, których wartość kolumny 'foo' ZAWIERA SIĘ w tablicy [1,2,3] LUB [7,8,9]
$rows = $this->core->db('table')->in('foo', [1,2,3])->orIn('foo', [7,8,9])->toArray();

WHERE NOT IN:

// Pobranie wierszy, których wartość kolumny 'foo' NIE ZAWIERA SIĘ w tablicy [1,2,3] LUB [7,8,9]
$rows = $this->core->db('table')->notIn('foo', [1,2,3])->orNotIn('foo', [7,8,9])->toArray();

Grupowanie warunków:

// Pobranie wierszy, których wartość kolumny 'foo' to 1 lub 2 ORAZ posiadają status = 1
$rows = $this->core->db('table')->where(function($st) {
            $st->where('foo', 1)->orWhere('foo', 2);
        })->where('status', 1)->toArray();

Dozwolone operatory porównania: =, >, <, >=, <=, <>, !=.

JOIN

INNER JOIN:

$rows = $this->core->db('table')->join('foo', 'foo.table_id = table.id')->toJson();

LEFT JOIN:

$rows = $this->core->db('table')->leftJoin('foo', 'foo.table_id = table.id')->toJson();

HAVING

$rows = $this->core->db('table')->having('COUNT(*)', '>', 5)->toArray();

OR HAVING:

$rows = $this->core->db('table')->orHaving('COUNT(*)', '>', 5)->toArray();

INSERT

Metoda save może dodać nowy rekord do tabeli lub zaktualizować istniejące, gdy zostanie opatrzona warunkiem. Po dodaniu nowego rekordu zostanie zwrócony jego numer identyfikacyjny.

// Dodanie nowego rekordu
$id = $this->core->db('table')->save(['name' => 'James Gordon', 'city' => 'Gotham']);
// Wartość zwracana: numer ID nowego rekordu

// Aktualizacja istniejącego rekordu
$this->core->db('table')->where('age', 50)->save(['name' => 'James Gordon', 'city' => 'Gotham']);
// Wartość zwracana: TRUE w przypadku sukcesu lub FALSE przy niepowodzeniu

UPDATE

Aktualizacja rekordów w przypadku powodzenia zwróci wartość TRUE. W przeciwnym razie będzie to FALSE.

// Zmiana jednej kolumny
$this->core->db('table')->where('city', 'Gotham')->update('name', 'Joker');

// Zmiana wielu kolumn
$this->core->db('table')->where('city', 'Gotham')->update(['name' => 'Joker', 'type' => 'Villain']);

SET

$this->core->db('table')->where('age', 65)->set('age', 70)->set('name', 'Alfred Pennyworth')->update();

DELETE

Pomyślne usunięcie rekordów zwróci ich liczbę.

// Usunięcie rekordu o `id` równym 1
$this->core->db('table')->delete(1);

// Usunięcie rekordu z warunkiem
$this->core->db('table')->where('age', 20)->delete();

ORDER BY

Sortowanie rosnące:

$this->core->db('table')->asc('created_at')->toJson();

Sortowanie malejące:

$this->core->db('table')->desc('created_at')->toJson();

Łączenie sortowania:

$this->core->db('table')->desc('created_at')->asc('id')->toJson();

GROUP BY

$this->core->db('table')->group('city')->toArray();

OFFSET, LIMIT

// Pobranie 5 rekordów, zaczynając od dziesiątego
$this->core->db('table')->offset(10)->limit(5)->toJson();

PDO

Nie wszystkie zapytania da się stworzyć przy pomocy wyżej wymienionych metod (np. utworzenie lub usunięcie tabeli), dlatego możesz również pisać zapytania przy pomocy PDO:

$this->core->db()->pdo()->exec("DROP TABLE `example`");

System szablonów

Obsługa systemu szablonów jest łatwa i opiera się głównie na dwóch metodach. Jedna pozwala na przypisanie zmiennych, natomiast druga zwraca skompilowany kod. W wyjątkowych sytuacjach przydają się pozostałe dwie metody.

set

void set(string $name, mixed $value)

Przypisuje wartość lub funkcję do zmiennej, którą będzie można się posługiwać w widokach.

Argumenty

• name — nazwa zmiennej
• value — wartość zmiennej lub anonimowa funkcja

Przykład

// Przypisanie tablicy
$foo = ['bar', 'baz', 'qux'];
$this->tpl->set('foo', $foo);

// Przypisanie funkcji anonimowej
$this->tpl->set('bar', function() {
   return ['baz' => 'qux']; 
})

draw

string draw(string $file)

Zwraca skompilowany kod widoku, w którym wcześniej zostały użyte tagi systemu szablonów.

Argumenty

• file — ścieżka do pliku

Wartość zwracana

Ciąg znaków, tj. skompilowany widok.

Przykład

$this->tpl->draw(MODULES.'/galleries/view/admin/manage.html');

noParse

string noParse(string $text)

Chroni przed kompilacją tagów systemu szablonów.

Argumenty

• text — tekst, który ma być pozostawiony bez zmian

Przykład

$this->tpl->noParse('Place this tag in website template: {$contact.form}');

noParse_array

array noParse_array(array $array)

Chroni przed kompilacją tagów systemu szablonów wewnątrz tablicy.

Argumenty

• array — tablica, która ma być pozostawiona bez zmian

Przykład

$this->tpl->noParse_array(['{$no}', '{$changes}']);

Języki

Wszelkie pliki językowe znajdują się w katalogach lang wewnątrz modułów oraz pod ścieżką inc/lang. W tej ostatniej ścieżce istnieją foldery odpowiadające nazwom języków w następującym formacie: en_english. Pierwszy człon to skrót języka, a drugi to jego pełna nazwa. Wewnątrz katalogu mieści się plik general.ini, w którym zawarte są ogólne zmienne językowe dla systemu. Po utworzeniu nowego folderu językowego, Batflat automatycznie wykryje dodany język i umożliwi jego wybranie w panelu administracyjnym. Należy jednak pamiętać, że procedurę stworzenia nowego języka należy powtórzyć dla każdego modułu.