Pomoc - Podstawowy kod szablonu

Start

Programowanie

Szablon

Podstawowy kod szablonu

Projektowanie rozpoczniemy od stworzenia prostego podstawowego kodu szablonu. Kod umieszczany jest w skrypcie index.php. Szablon nazwiemy 00_podstawa, a więc dokładnie tak samo, jak założony wcześniej katalog.

Pseudokod - struktura skryptu index.php

Plik index.php jest skryptem zapisywanym w języku PHP, na co wskazuje trzyliterowe rozszerzenie jego nazwy. Językiem PHP posługujemy się po to, aby określić czynności, które zostaną wykonane na serwerze, zanim powstanie dokument HTML wysyłany do przeglądarki użytkownika. Skrótowo mówiąc, instrukcje języka PHP generują wynikowy dokument HTML.

Rola PHP w skrypcie szablonu

Instrukcje PHP mogą posłużyć nam do:

uruchomienia skryptów Joomla! lub Mambo, które dostarczą treści dokumentu HTML
odczytania niezbędnych informacji z plików konfiguracyjnych,
wpisania tych treści do dokumentu HTML,
włączenia do dokumentu HTML zawartości innych plików,
komentowania treści dokumentu HTML,

W pierwszym przypadku posługujemy się funkcjami Joomla! i Mambo przeznaczonymi do wykorzystania w szablonach.

W drugim przypadku korzystamy z instrukcji PHP odczytujących potrzebne dane,

W trzecim przypadku korzystamy z funkcji echo () języka PHP.

W przypadku czwartym korzystamy z funkcji include () lub funkcji include_once() języka PHP,

W ostatnim korzystamy ze sposobów oznaczania komentarzy w skryptach PHP.

Struktura dokumentu HTML

Dokument HTML musi zawierać:

deklarację typu dokumentu - DOCTYPE
jeden element główny - HTML
jeden nagłówek w elemencie głównym - sekcję HEAD,
jedną sekcję BODY zawierajacą treść strony WWW

Skrypt index.php musi zatem mieć następującą strukturę:

<php
// kod PHP przygotowujący utworzenie dokumentu HTML
?>
<!DOCTYPE ....... />   <!-- :: deklaracja typu dokumentu -->
<html>                 <!-- :: rozpoczęcie dokumentu HTML -->
   <head>              <!-- :: rozpoczęcie nagłówka dokumentu HTML -->
   </head>             <!-- :: zakończenie nagłówka dokumentu HTML -->
   <body>              <!-- :: rozpoczęcie treści strony WWW -->
   </body>             <!-- :: zakończenie treści strony WWW -->
</html>                <!-- :: zakończenie dokumentu HTML -->

Polecenia HTML można wpisywać w skryptach PHP bezpośrednio. Nie trzeba ich wprowadzać instrukcjami PHP. Tworzenie skryptu możemy więc rozpocząć od wypisania znaczników HTML budujących prosty poprawny dokument HTML:

<!DOCTYPE ....... />
<html>
   <head>
   </head>
   <body>
   </body>
</html>

Zawartość pliku index.php dla szablonu Podstawa

Otwórz w swoim edytorze zapisany wcześniej w katalogu 00_podstawa plik index.php, wprowadź do niego poniższą zawartość, a następnie zachowaj plik.

<?php
/* 00_podstawa.php. Szkielet pliku index.php */
defined( '_VALID_MOS' ) or die( 'Zasób zastrzeżony' );
/* konieczne, wyodrębnia kod ISO ze stałej _ISO z pliku etykiet i komunikatów językowych  */
$iso = explode( '=', _ISO );
/* xml prolog - skomentowany, aby wymusić tryb zgodności */
// echo '<?xml version="1.0" encoding="'. $iso[1] .'"?' .'>';
?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo _LANGUAGE; ?>" lang="<?php echo _LANGUAGE; ?>">
<head>
  <meta http-equiv="Content-Type" content="text/html; <?php echo _ISO; ?> " />
  <?php
     mosShowHead(); 
     if ($my->id) {initEditor(); } 
  ?>
  <script type="text/javascript"></script>
  <link rel="stylesheet" type="text/css" title="Standardowy" 
   href="<?php echo $GLOBALS['mosConfig_live_site']; ?>/templates/<?php 
    echo $mainframe->getTemplate(); ?>/css/template_css.css"
    media="screen" />
  <link rel="shortcut icon" href="<?php echo $mosConfig_live_site;?>/images/favicon.ico" />
</head>
<body>
 <div id="header">          <!-- nagłówek -->
   <h1><?php echo $GLOBALS['mosConfig_sitename']; ?></h1> 
 </div>
 <div id="content_main">    <!-- treść główna -->
   <?php mosMainBody(); ?> 
 </div>
 <div id="nav_bar">         <!-- pasek nawigacyjny -->
   <?php mosLoadModules( 'left' ); ?>
 </div>
 <div id="misc_bar">        <!-- różne inne treści -->
   <?php mosLoadModules( 'right' ); ?>
 </div> 
 <div id="footer">          
   <?php include_once( $GLOBALS['mosConfig_absolute_path'] . '/includes/footer.php' ); ?>
 <div>
</body>

Objaśnienia

Głównym zadaniem pliku index.php jest generowanie dokumentów HTML przesyłanych do przeglądarek internetowych. Toteż skrypt ten ma budową pobobną do dokumentu HTML, a dokładniej XHTML, bo tą wersją języka znakowania stron internetowych będziemy się tutaj posługiwać. Patrz na zawartość tego skryptu, jak na dokument XHTML poszerzony o fragmenty napisane w PHP.

Nagłówek pliku PHP i prolog XML

Skrypt rozpoczyna się od nagłówka.

001 <?php
002 /* 00_podstawa.php. Szkielet pliku index.php */
003 defined( '_VALID_MOS' ) or die( 'Zasób zastrzeżony' );
004 /* konieczne, wyodrębnia kod ISO ze stałej _ISO  z pliku etykiet i komunikatów językowych  */
005 $iso = explode( '=', _ISO );
006 /* prolog XML - skomentowany, aby wymusić tryb zgodności */
007 // echo '<?xml version="1.0" encoding="'. $iso[1] .'"?' .'>';
008 ?>

Linia 1: znacznik rozpoczynający, sygnalizuje serwerowi, że rozpoczyna się fragment napisany w PHP.
Linia 2: komentarz: zapisaliśmy w nim nazwę pliku i określiliśmy jego rolę.
Linia 3: Uniemożliwia bezpośrednie uruchomienie skryptu. Zawarta tu instrukcja powoduje, że serwer sprawdza, czy wcześniej została zdefiniowana stała globalna _VALID_MOS. Jej definicję zawiera plik index.php umieszczony w głównym katalogu serwisu, uruchamiany każdorazowo, gdy serwer otrzyma żądanie pokazania strony.
Linia 4: komentarz objaśniający instrukcję w następnej linii.
Linia 5: Została objaśniona w komentarzu. Kod ISO będzie potrzebny do określenia w nagłówku dokumentu HTML systemu kodowania znaków.
Linia 6: Komentarz dotyczący linii 7. Informuje, że w kolejnej znajduje się - skomentowany, a więc wyłączony, prolog XML.
Linia 7: Skomentowany prolog XML. Więcej na ten temat dowiesz się z opracowania w aneksie - Prolog XML
Linia 8: znacznik kończący fragment w PHP.

Deklaracja typu dokumentu i sekcja HEAD dokumentu HTML

Tuż za nagłówkiem i prologiem XML umieszczona została wymagana w dokumentach HTML deklaracja rodzaju dokumentu, a następnie znacznik <html> wskazuje, że w tym miejscu rozpoczyna się element główny dokumentu HTML. Jak w każdym dokumencie HTML, mamy w nim dwie sekcje <head> i <body>. Przyjmijmy, że kod HTML w sekcji <head> jest zrozumiały. Szczegóły objaśniamy w aneksie. Zobacz m.in. Element HTML i Element HEAD. Tu zwróćmy uwagę na kolejny fragment zaspiany w PHP:

  <?php
     mosShowHead(); 
     if ($my->id) {initEditor(); } 
  ?>

Mamy tutaj dwa polecenia.

Polecenie mosShowHead(), to wywołanie jednej z funkcji Joomla! i Mambo. Jej zadaniem jest wygenerować zestaw charakterystycznych dla sekcji head metaznaczników. Szczegóły znajdziesz w dodatku Element HEAD.

Instrukcja warunkowa: if ($my->id) {initEditor(); powoduje sprawdzenie, czy przeglądający stronę użytkownik zalogował się. Jeśli tak, do pamieci jego komputera zostanie wczytany kod edytora WYSIWYG, by mógł z niego skorzystać w razie potrzeby. Umieszczenie tej instrukcji powoduje zauważalne przyspieszenie wczytywania stron Joomla! i Mambo w przeglądarkach.

Struktura treści - kod elementu <body>

Prosty układ W elemencie body znalazł się zestaw zanaczników HTML oraz instrukcji PHP wywołujących funkcje Joomla! i Mambo generujące treści strony.

Każdy element objęliśmy znacznkiem div z selektorem identyfikatora, wskazującym na jego funkcję w strukturze treści.

#header - nagłówek strony, użyjemy w tej roli nazwy serwisu ujętej w znacznik h1; nazwa zostanie odczytana ze zmiennej $mosConfig_sitename, zapisanej w konfiguracji witryny,
#content_main - treść główna, którą wygeneruje instrukcja <?php mosMainBody(); ?>,
#nav_bar - pasek nawigacyjny, wygeneruje go instrukcja <?php mosLoadModules('left'); ?>
#misc_bar - pasek z różnościami, jego treść wygeneruje instrukcja <?php mosLoadModules('right'); ?>
#footer - stopka, który zostanie wczytany z pliku /includes/footer.php

Polskie czy angielskie nazwy?

To wprawdzie drobna kwestia, właściwie bez znaczenia, ale rozstrzygnijmy ją na początku. Będziemy tut posługiwać się nazwami z angielskim źródłosłowiem. Taka konwencja nazw nada projektom waloru uniwersalności. Jeśli zechcemy nasz projekt upublicznić, skorzystają na tym użytkownicy z innych nacji.

Ale jako się rzekło - po polsku czy angielsku - nie ma znaczenia. Ważniejsze, czy czy nazwy nazywają treści, funkcje, jakie spełnia obiekt, czy też służą oznakowaniu wyglądu - położenia, kształtu, rozmiaru, koloru…

Znakowanie semantyczne

Dobrą praktyką jest znakowanie semantyczne. Nazwa powinna wskazywać, co to jest, a nie jakie jest, czy gdzie zostało umieszczone. Nazwiesz pasek nawigacyjny #lewy, a potem uznasz, że chcesz nawigację umieścić po prawej stronie. Oczywiście, wystarczy zmienić nazwę… Na pewno? A powiązania?

Znakowanie semantyczne to także wykorzystanie elementów HTML w ich właściwej roli: Jeśli element jest tytułem, stosuj h1 h2… h6, jeśli coś jest akapitem, stosuj p, jeśli jest listą, wykazem, stosuj ul lub ol i li.

Pierwszy test

Efekt uruchomienia szablonu

Nasz szablon zawiera już niezbędne skrypty: konfiguracyjny, index.php, a nawet arkusz stylu (pusty, ale przecież dopiero zaczynamy). Możemy sprawdzić uzyskany efekt.

Wywołaj swoją witrynę testową w dowolnej przeglądarce. Jeśli uruchomiłeś sewer na lokalnym komputerze, wystarczy w pasku adresu wpisać np.: http://localhost/testowa. Niekiedy wymagane jest jeszcze podanie portu: http://localhost:8888/testowa

Skorzystaj z modułu Zmień szatę. Wybierz z listy rozwijanej szablon 00_podstawa, a następnie kliknij przycisk Ustaw. Hokus, pokus… Szablon działa! Pierwszy sukces. Jak widzisz, naprawdę nic trudnego!

Oczywiście. Efekt jest na razie ubogi. Opublikowane materiały sformatowane zostały zgodnie z regułami arkusza stylów przeglądarki. Opublikowane zostały jeden pod drugim - podział treści głównej na kolumny to efekt działąnia kodu formatującego ten element zawartości, a nie szablonu. Szablon spełnił tylko jedną ze swych funkcji: umożliwił wygenerowanie na serwerze dokumentu źródłowego strony i przesłanie go do przeglądarki.

Ale to oznacza, że strona zostanie pokazana także w innych urządzeniach odczytujących.

Uwagi, źródła

Jeżeli masz sugestie odnośnie treści lub chcesz zgłosić poprawki do tego rozdziału, skomentuj go albo umieść wiadomość na forum: Dokumentacja - Propozycje, zmiany, poprawki

Dziękujemy!

Stefan Wajda, Zespół Dokumentacji PCJ