Dokumentacja sklepu

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.)
    •   user_carts - pliki obsługujące koszyk
  •   products
    •   index.ctp - lista produktów - listing
    •   show.ctp - karta produktu
  •   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 - w sekcji "Główny layout".

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. Przykładowe zmienne dla niektórych widoków:

 

karta produktu | $product

lista produktów | $products, $category

widok strony statycznej | $page

widok zamówienia | $order

 

Może się zdarzyć, że nie wszystkie dane znajdują się w dedykowanych zmiennych, wtedy możemy skorzystać z globalnych funkcji PHP wymienionych w rozdziale Funkcje niniejszej dokumentacji.

Przydatnym rozwiązaniem są dostarczane wraz z frameworkiem funkcje pozwalające programistycznie generować tagi html za pomocą kodu php, m.in.:

obrazki

echo $this->Html->image(
		$logo,
		[	
			'url'    => '/',
			'title'  => setting('GLOBAL_STORE_NAME'),
			'alt'    => setting('GLOBAL_STORE_NAME'),
			'width'  => '230',
			'height' => '48'
	
		]
	)
					

 

adresy url

echo $this->Html->url(getOrdersUrl())

 

linki

echo $this->Html->link($user_name, getUserAccountEditUrl(), array('escape' => false));
					

 

meta tagi

	echo $this->Html->meta(
		'favicon.ico',
		'/favicon.ico',
		['type' => 'icon']
	);
					

 

inputy

					echo $this->Form->input(
						$prefix.'.select_user_type',
						array(
							'type'        => 'radio',
							'div'         => false,
							'data-type'   => 'selected-user-type',
							'data-prefix' => strtolower($prefix),
							'legend'      => false,
							'default'     => 'p',
							'disabled'    => $disabled,
							'options'     => array(
								$user_type_key => $user_type_value
							)
						)
					)
					

 

dowolne tagi

						echo $this->Html->tag(
							'i',
							'',
							[
								'class' => 'fa fa-caret-right'
							]
						)
					

 

Standardowo internacjonalizację w warstwie tekstowej gwarantuje użycie metody __():

						__('Zamówienia', true)
					

Metoda ta przyjmuje dwa parametry: pierwszy to tekst, który ma być przetłumaczony, drugi - typu boolean - przechowuje informację, czy tekst ma być zwrócony (true), czy wyświetlony (false, defaultowe ustawienie).

 

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ładowa zawartość pliku layouts/default.ctp: 

 

<!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).

Odzwierciedlenie struktury pliku layout.ctp na stronie głównej:

 

 

 

 

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 dokumentacji ("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.

 

Przykład podstrony - strony koszyka

Treść poszczególnych stron koszyka znajduje się w plikach katalogu: /views/elements/user_carts

Proces zakupowy rozbity jest na 3 kroki, sterowane z poziomu pliku /views/elements/user_carts/index/index.ctp, odpowiedzialnego kolejno za wyświetlanie:

1. koszyka zakupowego: /views/elements/user_carts/index/1.ctp

2. formularzy adresowych dla użytkownika niezalogowanego: /views/elements/user_carts/index/2.ctp lub zalogowanego: /views/elements/user_carts/index/3.ctp

3. potwierdzenie złożonego zamówienia: /views/elements/user_carts/index/4.ctp

Ze względu na silne powiązanie z silnikiem sklepu i samą złożoność procesów, które gwarantują pełną i bezpieczną obsługę koszyka, logiczny podział na poszczególne kroki i sztywne przypisanie do nich określonych funcjonalności nie podlega rekonfiguracji.

Indywidualne pliki dla wybranych podstron

System AtomStore pozwala ustalić wyjątki w sposobie wyświetlania wybranych podstron:

• kategorie
• produkty
• producenci
• landing pages

Jeśli przykładowo wybrany, konkretny landing page ma zostać wyświetlony wg innego pliku szablonu niż pozostałe landing pages, to w panelu administracyjnym należy zadać plik ctp, jaki ma zostać wykorzystany podczas renderowania tej podstrony:

Analogicznie dla kategorii, produktów, producentów. 
Pliki ctp, które pozwala wybrać system, powinny być wcześniej dodane w szablonie sklepu, w przewidzianych do tego podkatalogach, odpowiednio:

• strony kategorii i producentów: views/products/index/
• strony produktów: views/products/show/ 
• landing pages: views/landing_pages/show/

Zawartość tych podkatalogów zostanie automatycznie wczytana do okna wyboru w panelu administracyjnym.

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 katalogu css/less/atomstore znajduje się plik o nazwie variables.less, który zawiera podstawową konfigurację szablonu.

 

Ścieżka do katalogów zawierających dodatkowe zasoby tworzona jest w oparciu o zmienne @{base-url} i @{template-name}, czego przykładem może być kod:

					@font-face{
						font-family: "roboto_medium";
						font-display: swap;
						src:  url("@{base-url}css/@{template-name}/fonts/roboto-500.woff2") format("woff2");
						font-weight: normal;
						font-style: normal;
					}
					
				

 

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 v3.7.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

- blazy - w wersji v1.8.2 

- select2 - w wersji v4.0.13 

- dropzone

 

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). Do każdego z głównych widoków przypisany jest plik zawierający dedykowane dla niego funkcje, przykładowo: 

- karta produktu - atomstore/atomstore.product.js

- listing produktów - atomstore/atomstore.productlist.js

- koszyk - atomstore/atomstore.cart.js

Całością steruje plik atomstore.app.js, odpowiedzialny za inicjowanie odpowiednich skryptów dla poszczególnych widoków.

 

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/scripts.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':