Struktura katalogów i plików
Dokument opisuje podstawowe zasady działania szablonu oraz strukturę plików odpowiedzialnych za renderowanie sklepu.
Katalogi i zasada działania
Przedstawiona lista zawiera tylko część najważniejszych plików i katalogów struktury szablonu.
- css - katalog z czcionkami, plikami less, css
-
- fonts
- less
- atomstore-responsive.css
- atomstore.css
- bootstrap.css
- font-awesome.css
- template.css
- images - katalog z elementami graficznymi szablonu
- js - katalog z bibliotekami Javascript
- layouts
- default.ctp - główny layout strony
- views - katalog i pliki odpowiadające poszczególnym podstronom sklepu, ponadto elementy ładowane w dowolnych miejscach
- ...
- categories
- elements - pliki z elementami strony (np. element menu, nagłówek, stopka itp.)
- products
- user_carts
- users
- home.ctp - główna strona, homepage
- ...
Zależność struktury plików i kolejność wywoływania poszczególnych plików (elementów) zostanie przedstawiona na przykładzie głównej strony sklepu.
Głównym plikiem od którego zaczyna się renderowanie strony, jest plik /layouts/default.ctp, w którym ładowane są poszczególne elementy strony. W pliku tym powinny się znaleźć wszystkie elementy, które są powtarzalne na każdej podstronie (np. stopka, menu itp), a także bardzo ważna zmienna $content_for_layout, w której znajduje się treść poszczególnych podstron (plik odpowiadający za str. główną to /views/users/home.ctp). Przykładowa zawartość pliku layouts/default.ctp oraz jej odzwierciedlenie na stronie:
<!DOCTYPE html>
<head>
<?php
/* Meta tagi */
echo this->element(TEMPLATE_NAME.DS.'head')
?>
</head>
<body>
<div class="wrap-header">
<?php
/* Nagłówek strony */
echo this->element(TEMPLATE_NAME.DS.'header')
?>
</div>
<div class="wrap-navbar">
<div class="container">
<?php
/* Nawigacja - kategorie */
echo this->element(
TEMPLATE_NAME.DS.'main_nav',
array(
'cache' => array(
'time' => Configure::read('Cache.short_time'),
'key' => getStandardCacheKey()
)
)
)
?>
</div>
</div>
<div class="wrap-content">
<div class="main-container container">
<?php
/* Ścieżka okruchów */
echo this->element(TEMPLATE_NAME.DS.'breadcrumbs')
?>
<div class="row">
<?php if ($left_boxes = getSidebarContent('left_column')): ?>
<aside class="sidebar sidebar-left">
<?php
/* Wyświetlenie lewego sidebara */
echo this->element(
TEMPLATE_NAME.DS.'sidebar',
array(
'boxes' => $left_boxes
)
)
?>
</aside>
<?php endif ?>
<section class="main-content <?php echo $left_boxes ? 'sidebar-left-true' : 'sidebar-left-false' ?>">
<?php
/* Komunikaty systemowe */
echo this->element(TEMPLATE_NAME.DS.'message')
?>
<?php
/* Treść strony */
echo $content_for_layout
?>
</section>
</div>
</div>
</div>
<div class="wrap-footer">
<?php
/* Stopka */
echo this->element(TEMPLATE_NAME.DS.'footer')
?>
</div>
<?php
/* Informacja o ciasteczkach */
echo this->element(TEMPLATE_NAME.DS.'cookies')
?>
<?php
/* JavaScript i Szablony */
echo this->element(TEMPLATE_NAME.DS.'scripts')
?>
</body>
</html>
W treści znajduje się m.in. wywołanie metody getSidebarContent() - pobiera ona nazwy elementów które mają być załadowane na stronie, wg konfiguracji z panelu administratora (USTAWIENIA → SZABLONY).
Pliki
Pliki szablonowe posiadają rozszerzenie "ctp". Są to pliki, w których można wykorzystywać funkcje i skrypty PHP. Każda podstrona posiada indywidualny plik odpowiedzialny za jej wyrenderowanie, np. /views/static_pages/show.ctp odpowiada za wyświetlenie każdej strony statycznej. Oprócz plików odpowiadających poszczególnym podstronom sklepu szablon zawiera m.in. layout główny oraz tzw. elementy.
Pliki z elementami
W plikach szablonu bardzo często używane jest odwołanie do innych elementów, np:
echo $this->element( TEMPLATE_NAME.DS.'sidebar', array( 'boxes' => $left_boxes ) )
Pierwszy parametr "TEMPLATE_NAME" wskazuje na aktywny szablon (stała zawiera nazwę aktywnego szablonu, np "atomdemo").
Drugi parametr jest tablicą, która zawiera informacje przekazywane do danego elementu. Takie "elementy" można dowolnie tworzyć, znajdują się one w katalogu views/elements/.
Drugim rodzajem elementów, są elementy zwracane bezpośrednio z silnika sklepu, takich elementów nie da się edytować, ich wywołanie wygląda np w ten sposób:
echo $this->element( '_default'.DS.'bottom_page_scripts' )
W tym przypadku, pierwszy parametr wywołania funkcji zamiast stałej TEMPLATE_NAME posiada ciąg znaków '_default', co oznacza że element znajduje się poza katalogiem elements i nie da się go edytować.
Zmienne w widokach
Poszczególne widoki sklepu posiadają dedykowane zmienne, zdefiniowane poza widokiem. Dla przykładu, jeśli wyświetlany jest widok karty produktu, wówczas potrzebne dane znajdują się w zmiennej $product. Może się zdażyć, że nie wszystkie dane znajdują się w takiej tablicy, wtedy możemy skorzystać z globalnych funkcji PHP wymienionych w innym rozdziale dokumentacji.
Moduły i ustawienia
W widokach używana jest funkcja module(), która jako parametr przyjmuje klucz z nazwą modułu. W zależności od modułów, które są uruchomione na sklepie, część elementów nie jest wyświetlana. Np. do sprawdzenia czy moduł filtrów jest aktywny, trzeba wywołać funkcję w postaci: module('FILTER').
Do odczytywania ustawień ze sklepu służy funkcja setting(). Jako parametr przyjmuje ona ciąg znaków z nazwą ustawienia, np. jeśli chcemy odczytać nazwę sklepu, wówczas wywołujemy funkcję z parametrem: setting('GLOBAL_STORE_NAME').
Moduły i ustawienia znajdują się w panelu administracyjnym sklepu → USTAWIENIA → KONFIGURACJA SKLEPU.
Główny layout
W katalogu wybranego szablonu mamy nastepującą strukturę:
|-css
|-images
|-js
|-layouts
|-views
Główny plik z layoutem, znajduje się w pliku layouts/default.ctp. W tym pliku renderowane są wszystkie wywołania sklepu (oprócz wywołań ajax'owych). Jest to standardowa postać HTML ze znacznikami html, head, body. W pliku tym wyświetlane powinny być powtarzalne elementy występujące na wszystkich podstronach sklepu (stopka, nawigacja itp).
Znajduje się tu kluczowa zmienna $content_for_layout, która zawiera treść poszczególnych stron (logowania, listy produktów, stron statycznych, rejestracji itd.), wszystkich stron oprócz wywołań ajaxowych. Zmienna ta jest zastępowana treścią poszczególnych widoków (plików), opisanych częściowo poniżej.
Przykład podstrony - strona główna
Główna strona generowana jest w pliku: /views/users/home.ctp
Nie posiada ona zmiennych dedykowanych, całość wygenerowana jest na podstawie elementów i funkcji globalnych. Wszystkie elementy wywołane w tym widoku znajdują się w katalogu /views/elements/.
Może się zdażyć sytuacja, że element będzie się znajdować w katalogu poziom niżej, wówczas wywołanie takiego elementu może wyglądać w ten sposób (element w katalogu /views/elements/boxes/news.ctp):
echo $this->element( TEMPLATE_NAME.DS.'boxes'.DS.'news', array( 'id' => 'News' ) )
W domyślnym szablonie (w zależności od ustawień), przez elementy pobierane są takie treści jak: strefy banerowe, nowości, bestsellery, aktualności itp.
Przykład podstrony - strona statyczna
Strona statyczna wyświetlana jest za pośrednictwem pliku: /views/static_pages/show.ctp
Całość treści znajduje się w dedykowanej zmiennej $page.
Na podstawie stron statycznych, można także budować menu strony, w szablonie demo jest element "menu_static_page.ctp", który zawiera przykładową strukturę takiego menu.
Pobieranie stron statycznych może się także odbywać na innych stronach sklepu, służą do tego specjalnie przygotowane funkcje globalne, opisane w dokuemntacji ("Szablon"»"Funkcje").
Przykład podstrony - strona logowania
Treść strony logowania znajduje się w pliku: /views/users/login.ctp
W pliku login.ctp, wywoływany jest element "login_page". Treść strony logowania została przeniesiona do tego pliku, ponieważ jest on wyświetlany także w innych widokach i tym samym pozwala na uniknięcie dublowania kodu.
Element "login_page", oprócz standardowego sposobu logowania, zawiera kod umożliwiający logowanie poprzez np facebook'a, czy google.
Możliwość logowania przez facebook'a czy google'a, możliwa tylko po odpowiedniej konfiguracji z poziomu panelu administratora sklepu.
Javascript do obsługi logowania przez wtyczki znajduje się w elemencie "scripts", który ładowany jest w głównym layoucie sklepu. W elemencie "scripts" znajduje się wywołanie elementów z silnika sklepu ( $this->element(TEMPLATE_NAME.DS.'scripts') ), którego nie można edytować i jest wymagane do prawidłowego funkcjonowania.
Less i CSS
Szablon zbudowany jest na dynamicznym arkuszu stylów LESS oraz frameworku Bootstrap CSS. Wszystkie pliki znajdują się w katalogu css/less szablonu. W głównym folderze css znajdują się pliki z rozszerzeniem .css, które są wynikiem kompilacji wszystkich plików less.
- atomstore-responsive.css - style dotyczące responsywnej wersji szablonu, przekompilowane pliki katalogu less/atomstore
- atomstore.css - przekompilowane pliki katalogu less/atomstore
- bootstrap.css - przekompilowane pliki katalogu less/bootstrap
- font-awesome.css - przekompilowane pliki katalogu less/font-awesome
- template.css - jest to plik, w którym trzymane są arkusze stylów, edytowane poprzez panel administracyjny sklepu (Ustawienia/szablony/edycja szablonu)
- styles.min.css* - skompresowany plik css, wygenerowany na podstawie plików z powyższej listy (dostępny tylko na wersji produkcyjnej sklepu)
Jeśli nastąpiła zmiana w plikach less, odpowiednio pliki z rozszerzeniem *.css zostają na nowo przekompilowane (oprócz pliku template.css który zarządzany jest przez panel sklepu).
Sklep może działać w dwóch trybach: developerskim oraz produkcyjnym.
W wersji developerskiej, każda zmiana w plikach less jest wykrywana i pliki css generowane są automatycznie na nowo. Do źródła strony dodane są poszczególne pliki (nie jak w wersji produkcyjnej skompresowany jeden plik styles.min.css)
W wersji produkcyjnej, pliki less nie są już sprawdzane ze względu na optymalizację sklepu. Zmiany wprowadzone w less'ach wymagają usunięcia plików css (atomstore-responsive.css, atomstore.css, bootstrap.css, font-awesome.css, styles.min.css, UWAGA! template.css musi pozostać), aby wymusić ponowne wygenerowanie skompresowanego arkusza styli styles.min.css.
W katalogu css/less/atomstore znajduje się plik o nazwie variables.less, który zawiera podstawową konfigurację szablonu.
Pliki less, css oraz javascript do szablonu ładowane są w pliku views/elements/head.ctp.
Javascript i biblioteki
Wszystkie biblioteki i funkcje javascriptowe zlokalizowane są w katalogu js.
|-vendor
|-atomstore
|-atomstore.app.js
|-scripts.min.js*
vendor - w tym katalogu dodawane są biblioteki oraz pluginy, w obecnej wersji szablonu używane są komponenty jak:
- jquery - w wersji v1.11.0
- blueimp-gallery - w wersji 2.14.1
- bootstrap - w wersji v3.1.1
- Modernizr - w wersji 2.7.0
- ketchup - w wersji 0.3.2
atomstore - katalog zawiera dedykowane pliki js, odpowiedzialne za działanie oraz wygląd poszczególnych elementów na stronie sklepu (formularzy, elementów formularzy, walidację itp).
scripts.min.js - plik, który zawiera skompresowaną wersję wszystkich plików, dostępny TYLKO dla wersji produkcyjnej sklepu. Dla sklepu w wersji developerskiej, wszystkie pliki ładowane są osobno.
Konfiguracja i dodawanie nowych plików javascript'owych znajduje się w pliku views/elements/head.ctp. Jeśli sklep znajduje się w wersji produkcyjnej, wówczas zmiana w poszczególnych plikach, wymaga ponownego wygenerowania pliku scripts.min.js (wystarczy usunąć plik scripts.min.js, który zostanie utworzony automatycznie z plików skonfigurowanych w head.ctp).
Newsletter
Szablony newslettera definiowane są przez panel administracyjny → NEWSLETTER → SZABLONY, jednak w plikach szablonu można określić sposób renderowania produktów w treści mailingu.
- views/elements/newsletter
-
- product - możliwe sposoby renderowania pojedynczego produktu
- products - możliwe sposoby renderowania grupy produktów
- product.ctp - domyślny sposób renderowania pojedynczego produktu
- products.ctp - domyślny sposób renderowania grupy produktów
Administrator wybiera odpowiedni plik szablonu podczas uzupełniania treści newslettera w zakresie pól typu 'produkt':
lub 'grupa produktów':
zobacz DEMO
