Skip to content

devel_intro

Jump to bottom
kojoty edited this page Apr 24, 2018 · 5 revisions

UWAGA: Ten dokument w wielu miejscach jest już nieaktualny, więc do czasu jego aktualizacji można traktować go jako materiał wspomagający. Jeśli potrzebujesz wprowadzenia w kod OCPL śmiało odezwij się: rt at opencaching.pl

Wprowadzenie do kodu OCPL

Ogólne informacje

Język angielski

Nasze repozytorium robi się coraz bardziej międzynarodowe. Starajmy się więc używać angielskiego gdzie się da. Np. indentyfikatory dla tr(...) powinny bazować na języku angielskim, tzn. piszemy raczej "status_found" niż "status_znaleziona". Wszystkie nowododawane teksty również powinny być od razu przetłumaczone na angielski (a nie tylko polski).

Podobnie - wszelkie komentarze, zmienne itp. w kodzie starajmy się pisać po angielsku. Jeśli nie znamy angielskiego, to koniecznie piszemy po polsku (lepszy komentarz po polsku niż brak komentarza).

Struktura

Główny kod jest napisany w PHP i znajduje się w głównym katalogu. Pozostałe katalogi zawierają pliki z definicjami funkcji, różne biblioteki, obrazki.

Katalog lib/ zawiera ustawienia globalne serwisu, pliki z pomocniczymi funkcjami używanymi przez cały kod. Jednym z ważniejszych plików jest lib/common.inc.php - zawiera m.in. definicje parametrów połączenia z bazą.

Pliki PHP w katalogu głównym często są powiązane z tak samo nazwanymi plkami w katalogu tpl/stdstyle/...:

  • tpl/stdstyle/ zawiera pliki nazwa_pliku.tpl.php (szablony). Są też pliki nazwa_pliku.inc.php, które zawierają dodatkowe zmienne używane w generowanym kodzie, czasami są to komunikaty o błędach, itp.
  • tpl/stdstyle/images/ zawiera zestaw różnych ikonek (większe obrazki sa umieszczone w głównym katalogu images)
  • tpl/stdstyle/email/ zawiera templaty do treści wysyłanych przez email,
  • tpl/stdstyle/articles zawiera informacje, które są wywoływane kodem article.php?page=nazwa_pliku_z_tego_katalogu
  • tpl/stdstyle/lib/ ważnym plikiem w tym katalogu jest menu.php, który odpowiada za strukturę menu na stronie,
  • tpl/stdstyle/js/ tu znajdują się różne elementy w javascript związane tym template,
  • tpl/stdstyle/css/ zawiera style css używane w kodzie.

Baza danych

OC posiada dwa sposoby łączenia z bazą danych. starsza to funkcja sql('zapytanie').

Drugi, nowszy sposób jest oparty na bibliotece PDO. Klasa znajduje się w pliku lib/db.php. Zawiera metody:

simpleQuery($query)
paramQuery($query, $param_array)
multiVariableQuery($query)
debugOC($position, $array)

Podstawową metodą jest paramQuery() oraz multiVariableQuery() Pierwsza wymaga tablicy ze zmiennymi, gdzie każda zmienna musi mieć klucz, wartość i typ danych. Druga przyjmuje dowolną ilość zwykłych zmiennych.

  • paramQuery()
paramQuery($query, $param_array)

$query - zapytanie $param_array - parametry zapytania zawierające klucz, wartość i typ danych.

przykład:

// zapytanie
$query = "SELECT `costam` FROM `tabelka` WHERE `userID` =:user_id and cache_name =:cache_name";

// tablica z parametrami zapytania oraz typem danych
$param_array = array (
	user_id' => array(
		'value' => 1456,
        'data_type' => 'integer',
    ),
	cache_name' => array(
		'value' => 'Skrzynka przykladowa',
        'data_type' => 'string',
    ),
);

// tworzymy obiekt
$dbConWpt = New dataBase;

// wykonujemy zapytanie do bazy
$dbConWpt->paramQuery($query, $param_array)


// pobieramy ilość zwróconych wierszy
$rowsReturned = $dbConWpt->rowCount()

// pobieramy wynik (można też pobierać w tym miejscu iteracyjnie)
$result = $dbConWpt->dbResultFetch();

// niszczymy obiekt (zwalniamy pamięć)
unset($dbConWpt)

w odpowiedzi ($result) otrzymamy tablicę (array). zawierającą pierwszy wiersz z wyników zapytania, w postaci tablicy. Jeśli chcemy otrzymać od razu tablicę z wszystkimi wierszami (pełną odpowiedź) zamiast $dbConWpt->dbResultFetch(); używamy $dbConWpt->dbResultFetchAll();

$result = $dbConWpt->dbResultFetchAll();

przykład zwracanej tablicy $dbConWpt->dbResultFetch()

Array
   (
     [=> 12
   )

przykład zwracanej tablicy $dbConWpt->dbResultFetchAll:

 Array (
   [0](costam]) => Array (
                 [=> 12
         )
   [1](something]) => Array (
             	 [=> 20
         )
   [2](something]) => Array (
             	 [=> 23
         )
   [3](something]) => Array (
             	 [=> 3
         )
)
  • multiVariableQuery()
multiVariableQuery($query, $param1, param2 ... param_n)

Zapytanie musi posiadać reprezentację zmiennych w postaci kolejnych liczb naturalnych (integer).

Przykład:

// zapytanie
$query: 'SELECT something FROM tabele WHERE field1=:1 AND field2:2'

// zmienne z parametrami zapytania
$param1 = 4568;
$param2 = 'cat is very lovelly animal';

// tworzymy obiekt
$DbConWpt = New dataBase;

// wykonujemy zapytanie
$DbConWpt->multiVariableQuery($query, $param1, $param2);


// pobieramy wynik, tu przykład iteracyjny
while ($row = $dbConWpt->dbResultFetch()) {
    // tu wykonaj swój kod ;)
}

// niszczymy obiekt (zwalniamy pamięć)
unset($dbConWpt)

Przykłady

Zbudujmy pierwszą prostą stronę w kodzie OC PL która nie będzie wymagała aby user był zalogowany i pobierze dane z bazy i wyświetli ją w html.

Przykład pliku example.php:

<?php
	//prepare the templates and include all neccessary
	require_once('./lib/common.inc.php');

	//Preprocessing
	if ($error == false)
	{

	// wskazanie pliku z kodem html ktory jest w tpl/stdstyle/
		$tplname = 'example';

		// zmienna zdefniowana
		$cache_wp="OP0001";

                // pobieramy dane z bazy
                $rs = sql("SELECT `caches`.`name`,`user`.`username` FROM `caches`,`user`

                            WHERE `caches`.`user_id` = `user`.`user_id` AND
                                  `caches`.`wp_oc`='&1'",$cache_wp);

			$record = mysql_fetch_array($rs);

		// przekaznie wynikow w postaci zmiennych do pliku z kodem html
		tpl_set_var("wp_oc",$cache_wp);
		tpl_set_var("owner",$record['username'](something]));
		tpl_set_var("cachename",$record[mysql_free_result($rs);
	}

	// budujemy kod html ktory zostaje wsylany do przegladraki
	tpl_BuildTemplate();
?>

Następnie tworzymy plik tpl/stdstyle/example.tpl.php w którym znajduje kod html i wyświetlane wyniki kodu php :

<div class="content2-pagetitle">

<img src="tpl/stdstyle/images/blue/cache.png" class="icon32" alt="geocache" title="geocache" align="middle" />

Geocache

<div class="searchdiv">

<br/>

<p>Nazwa wp: {wp_oc}</p>

<p>Nazwa: {cachename}</p>

<p>Właściciel: {owner}</p>

</br>
</div>

Wystarczy teraz napisać w przeglądarce http://local.opencaching.pl/example.php i zobaczymy wynik naszego kodu która jest dostępna dla niezalogowanego usera. Jeśli chcemy aby kod był dostepny tylko dla zalogowanego usera nasz example.php wyglada:

<?php
	//prepare the templates and include all neccessary
	require_once('./lib/common.inc.php');

	//Preprocessing
	if ($error == false)
	{
		// czy user zalogowany ?
		if ($usr == false)
		{
                    // nie zalogowany wiec przekierowanie na strone z logowaniem
		    $target = urlencode(tpl_get_current_page());
		    tpl_redirect('login.php?target='.$target);
		}
		else
		{

        	// wskazanie pliku z kodem html ktory jest w tpl/stdstyle/
		$tplname = 'example';

		// zmienna zdefniowana
		$cache_wp="OP0001";

                // pobieramy dane z bazy
                $rs = sql("SELECT `caches`.`name`,`user`.`username` FROM `caches`,`user`

                            WHERE `caches`.`user_id` = `user`.`user_id` AND
                                  `caches`.`wp_oc`='&1'",$cache_wp);

			$record = mysql_fetch_array($rs);

		// przekaznie wynikow w postaci zmiennych do pliku z kodem html
		tpl_set_var("wp_oc",$cache_wp);
		tpl_set_var("owner",$record['username']('name']);));
		tpl_set_var("cachename",$record['name']);

             mysql_free_result($rs);
	 }

       }

	// budujemy kod html ktory zostaje wsylany do przegladraki
	tpl_BuildTemplate();
?>

Plik tpl/stdstyle/example.tpl.php nie zmienia się. Traz aby naszą przykładową stronę zobaczyć użytkownik musi być zalogowan w przeciwnym razie zostanie przekierowany na stronę do logowania.

Jeśli chcesz umieścić javascript w kodzie to umieszczamy go na początku pliku example.tpl.php :

<script type="text/javascript">

zawartość javascript ....

</script>

zawartość kod html ...

Kod OC PL nie używa np smarty systemu (choć pewnie byłoby to fajne wdrożyć - czesc kodu mobile korzysta z smarty) używamy prostej formy wielojęzykowych opisów. Pliki z tłumaczeniami znajdują się w katalogu /lib/languages/ Aby Twój kod był widziany dla kogoś kto wybierze interfejs w języku angielskim robisz wpisy w pliku /lib/languages/pl i /lib/languages/en. Składnia jest prosta:

zdanie_użyte_w_kodzie Tłumaczenie

w kodzie html zdania które są w różnych językach używamy w postaci:

{{zdanie_uzyte_w_kodzie}}

proszę zwrócić uwagę że zmienne z kodu php są umieszczane w pojedynczych nawiasach {} w odróżnieniu do tłumaczeń {{}}

np zawartość pliku example.tpl.php wygląda wtedy

<div class="content2-pagetitle">

<img src="tpl/stdstyle/images/blue/cache.png" class="icon32" alt="geocache" title="geocache" align="middle" />

Geocache

</div>

<div class="searchdiv">

<br/>

<p>{{name_wp}}: {wp_oc}</p>

<p>{{name_cache}}: {cachename}</p>

<p>{{owner_cache}}: {owner}</p>

</br>
</div>

gdzie zmienne "name_cache", "name_wp", "owner_cache" muszą znaleźć się w plikach językowych pl i en

Jeśli używamy tłumaczeń w kodzie php wtedy używamy składni

tr('zdanie_do_tłumaczenie')

Przykład:

$octeam_info ="".tr('tresc_tlumaczona')."
";

Start page

Virtual Machine (VM):

(EN) Installation and usage - brief description
(PL) Przygotowanie środowiska dev.
(EN) The "Making of"
(EN) Requests for new VM version?
(PL) Wskazówki dla Windowsowców

Setup instructions without VM:

(EN+PL) Linux
(PL) Windows

Tips for developers:

(EN) Coding style
(EN) People and their duties
(PL) Praca z repozytorium
(PL) Wprowadzenie do kodu OCPL

Clone this wiki locally