Opencaching-Wiki

Entwicklung/Codedoku: Unterschied zwischen den Versionen

Seite Diskussion

Entwicklung/Codedoku (Quelltext anzeigen)

Version vom 15. September 2015, 09:53 Uhr

3.859 Bytes hinzugefügt ,  15. September 2015
→‎Funktionsweise
 
(34 dazwischenliegende Versionen von 3 Benutzern werden nicht angezeigt)
Zeile 3: Zeile 3:
Weitere Dokumentationen gibt es auch in den Codeverzeichnissen {{Codepath|doc}} und {{Codepath|htdocs/doc}}. Die Datei {{Codepath|doc/directories.txt}} enthält eine Übersicht der Repository-Verzeichnisstruktur. ''(Grüne Pfad- und Dateinamen sind anklickbar.)''
Weitere Dokumentationen gibt es auch in den Codeverzeichnissen {{Codepath|doc}} und {{Codepath|htdocs/doc}}. Die Datei {{Codepath|doc/directories.txt}} enthält eine Übersicht der Repository-Verzeichnisstruktur. ''(Grüne Pfad- und Dateinamen sind anklickbar.)''


Alle die bereits an Opencaching mitprogrammiert haben sind eingeladen, ihr Wissen beizusteuern! Wenn du dir zusätzliche Erläuterungen wünschst, kannst du sie auf der Diskussionsseite anfragen – vielleicht findet sich jemand, der den Artikel ergänzt.
Alle die bereits an Opencaching mitprogrammiert haben, sind eingeladen, ihr Wissen beizusteuern! Wenn du dir zusätzliche Erläuterungen wünschst, kannst du sie auf der Diskussionsseite anfragen – vielleicht findet sich jemand, der den Artikel ergänzt.


Formale Richtlinien für OC-Code (''style guidelines'') sind noch nicht niedergeschrieben. → [[Entwicklung/Stil]]
Siehe auch: [[Entwicklung/Stil|Style Guidelines]]


== Dateiformat ==
== Dateiformat ==


Alle OC-Quelltextdateien haben [[wikipedia:UTF-8|UTF-8]]-Format. Im Kopf der Quelltextdateien befindet sich ein japanisches Wort, mit dem geprüft werden kann ob die Zeichencodierung intakt ist. Sollte versehentlich nach ISO-8859-1 o.ä. umcodiert werden sein, erscheinen dort z.B. zwei Fragezeichen oder gar nichts.
Alle OC-Quelltextdateien haben [[wikipedia:UTF-8|UTF-8]]-Format. Im Kopf der Quelltextdateien befindet sich ein japanisches Wort ("Unicode Reminder"), mit dem geprüft werden kann ob die Zeichencodierung intakt ist. Sollte versehentlich nach ISO-8859-1 o.ä. umcodiert worden sein, erscheinen dort z.B. zwei Fragezeichen oder gar nichts.
 
{{Codepath|local/tools/find_bad_encodings.php}} prüft alle Quelltexte auf fehlende oder beschädigte Unicode Reminder.


Die Zeilenenden der Quelltexte bestehen grundsätzlich aus einem einfachen LF (line feed). Ausnahmen gibt es z.B. bei [[#Email-Templates|Email-Templates]]; hier ist CR/LF vorgeschrieben.
Die Zeilenenden der Quelltexte bestehen grundsätzlich aus einem einfachen LF (line feed). Ausnahmen gibt es z.B. bei [[#Email-Templates|Email-Templates]]; hier ist CR/LF vorgeschrieben.
Zeile 28: Zeile 30:


* '''APIs''', also Schnittstellen für Datenabruf oder -upload durch Dritte:
* '''APIs''', also Schnittstellen für Datenabruf oder -upload durch Dritte:
** diverse APIS in {{Codepath|htdocs/api}}
** diverse APIs in {{Codepath|htdocs/api}}
** die [[OKAPI]] in {{Codepath|htdocs/okapi}}, repliziert aus dem [http://code.google.com/p/opencaching-api/source/browse/trunk/#trunk%2Fokapi OKAPI-Repository]
** die [[OKAPI]] in {{Codepath|htdocs/okapi}}, repliziert aus dem [http://code.google.com/p/opencaching-api/source/browse/trunk/#trunk%2Fokapi OKAPI-Repository]
** die [[XML-Schnittstelle]] in {{Codepath|htdocs/xml}}
** die [[XML-Schnittstelle]] in {{Codepath|htdocs/xml}}
Zeile 46: Zeile 48:
Die alte selbstgeschriebene Bibliothek von OC-Codeversion 1.0, in {{Codepath|htdocs/lib}}. Sie enthält z.B. Funktionen für Datenbankzugriff, Login, Menüs, geographische Berechnungen und ein einfaches Template-System.
Die alte selbstgeschriebene Bibliothek von OC-Codeversion 1.0, in {{Codepath|htdocs/lib}}. Sie enthält z.B. Funktionen für Datenbankzugriff, Login, Menüs, geographische Berechnungen und ein einfaches Template-System.


lib1 ist veraltet und wird auf OC.de nur noch für das Bearbeiten von Logs und Cachebeschschreibungen, für Benachrichtigungen über beobachtete und neue Caches und für die XML-Schnittstelle verwendet. Mittelfristig soll sie ganz durch lib2 ersetzt werden. (Alle auf OC.pl-code basierenden [[Opencaching]]-Seiten verwenden weiterhin ausschließlich die lib1).
lib1 ist veraltet und wird auf OC.de nur noch für das Bearbeiten von Logs und Cachebeschschreibungen, für Benachrichtigungen über beobachtete und neue Caches und für die XML-Schnittstelle verwendet. Mittelfristig soll sie ganz durch lib2 ersetzt werden. (Alle auf OC.pl-Code basierenden [[Opencaching]]-Seiten verwenden weiterhin ausschließlich die lib1).


lib1 wird eingebunden mit
lib1 wird eingebunden mit
Zeile 63: Zeile 65:


==== libse ====
==== libse ====
Eine Klassebibliothek von Opencaching.se, in {{Codepath|htdocs/libse}}. Im Zuge der Codezusammenführung von OC.de und OC.se wurde sie 2011 mit in den OC.de-Code übernommen. Sie wird für zusätzliche Wegpunkte und persönliche Notizen im Cachelisting verwendet.
Eine Klassenbibliothek von Opencaching.se, in {{Codepath|htdocs/libse}}. Im Zuge der Codezusammenführung von OC.de und OC.se wurde sie 2011 mit in den OC.de-Code übernommen. Sie wird für zusätzliche Wegpunkte und persönliche Notizen im Cachelisting verwendet.


==== Autoload ====
==== Autoload ====
Zeile 77: Zeile 79:
* [http://www.smarty.net/ '''Smarty'''] wird als "Template-Engine" für lib2 verwendet. OC-spezifische Erweiterungen befinden sich in der Klasse ''OcSmarty'' und in {{Codepath2|htdocs|lib2/smarty/ocplugins}}. Mehr dazu im Abschnitt [[#Templates|Templates]].
* [http://www.smarty.net/ '''Smarty'''] wird als "Template-Engine" für lib2 verwendet. OC-spezifische Erweiterungen befinden sich in der Klasse ''OcSmarty'' und in {{Codepath2|htdocs|lib2/smarty/ocplugins}}. Mehr dazu im Abschnitt [[#Templates|Templates]].


* '''[http://htmlpurifier.org/ HTML Purifier]''' dient zum "Säubern" von HTML-Code, den der Benutzer z.B. in Cachebeschreibungen eingeben kann. lib1 und lib2 verwenden getrennte HTML-Purifier-Installationen. In lib2 wird er über die Klasse ''OcHTMLPurifier'' eingebunden und kann dort auch angepasst werden.  
* '''[http://htmlpurifier.org/ HTML Purifier]''' dient zum "Säubern" von HTML-Code, den der Benutzer z.B. in Cachebeschreibungen eingeben kann.Er wird (auch in lib1) über die lib2-Klasse ''OcHTMLPurifier'' eingebunden und kann dort angepasst werden.  


* '''[http://www.tinymce.com/ TinyMCE]''' ist ein leistungsfähiger JavaScript-Wysiwyg-Texteditor. Er dient zum Bearbeiten von Cachebeschreibungen, Logs und Profiltexten. lib1 und lib2 verwenden beide die TincyMCE-Installation in {{Codepath|htdocs/resource2/tinymce}}. OC-spezifische Konfigurationsdaten gibt es in {{Codepath2|htdocs/resource2|tinymce/config}}.  
* '''[http://www.tinymce.com/ TinyMCE]''' ist ein leistungsfähiger JavaScript-Wysiwyg-Texteditor. Er dient zum Bearbeiten von Cachebeschreibungen, Logs, Profiltexten und Cachelisten-Beschreibungen. lib1 und lib2 verwenden beide die TinyMCE-Installation in {{Codepath|htdocs/resource2/tinymce}}. OC-spezifische Konfigurationsdaten gibt es in {{Codepath2|htdocs/resource2|tinymce/config}}; außerdem wurden die Einstellunge in {{Codepath2|htdocs/resource2|tinymce/themes/advanced/langs}} angepasst. Damit Änderungen am TinyMCE-Source-Code wirksam werden, müssen u.U. die .gz-Cachedateien im tinymce-Verzeichnis gelöscht werden.
</div>


Von lib2-Code verwendete Bibliotheken sind in {{Codepath|htdocs/lib2}} (PHP) und {{Codepath|htdocs/resource2}} (JavaScript) angelegt. Bibliotheken für lib1 befinden sich an verschiedenen Stellen.
Von lib2-Code verwendete Bibliotheken sind in {{Codepath|htdocs/lib2}} (PHP) und {{Codepath|htdocs/resource2}} (JavaScript) abgelegt. Bibliotheken für lib1 befinden sich an verschiedenen Stellen.


</div>
OC-spezifische Anpassungen sind in {{Codepath|doc/customized-libs.txt}} dokumentiert.


== Konfigurationsdateien ==
== Konfigurationsdateien ==
Zeile 101: Zeile 104:
==== lib2-Konfiguration ====
==== lib2-Konfiguration ====


Die lib2-Einstellungen befinden sich alle in {{Codepath|htdocs/config2}}. Sie werden ''alle'' in folgender Reihenfolge eingebunden sobald man {{Codepath2|htdocs/lib2|web.inc.php}} oder {{Codepath2|htdocs/lib2|cli.inc.php}} einbindet:
Die lib2-Einstellungen befinden sich alle in {{Codepath|htdocs/config2}}. Sie werden ''alle'' in folgender Reihenfolge eingebunden, sobald man {{Codepath2|htdocs/lib2|web.inc.php}} oder {{Codepath2|htdocs/lib2|cli.inc.php}} einbindet:


* sprachabhängige Einstellungen: {{Codepath2|htdocs/config2|locale.inc.php}}
* sprachabhängige Einstellungen: {{Codepath2|htdocs/config2|locale.inc.php}}
Zeile 147: Zeile 150:
Hier wird die Größe eines Caches geändert. Variablen werden als fortlaufend numerierte Platzhalter &1, &2 etc. übergeben. Die Funktion ''sql'' ruft dann intern für jede Variable <code>mysql_real_escape_string()</code> auf, was spezielle Zeichen wie " codiert und gleichzeitig [[wikipedia:SQL-Injection|SQL-Injections]] verhindert.
Hier wird die Größe eines Caches geändert. Variablen werden als fortlaufend numerierte Platzhalter &1, &2 etc. übergeben. Die Funktion ''sql'' ruft dann intern für jede Variable <code>mysql_real_escape_string()</code> auf, was spezielle Zeichen wie " codiert und gleichzeitig [[wikipedia:SQL-Injection|SQL-Injections]] verhindert.


'''Niemals dürfte Variablen direkt in SQL-Statements eingebaut werden!''' Entweder sind Platzhalter zu verwenden, oder man muss sie einzeln mit <code>sql_escape()</code> absichern.
'''Niemals dürfen Variablen direkt in SQL-Statements eingebaut werden!''' Wann immer möglich sind Platzhalter zu verwenden. Notfalls kann auch direkt mit <code>sql_escape()</code> codiert werden, was allerdings Probleme verursacht, wenn ein "&" in den Daten enthalten ist: Die Funktion <code>sql()</code> interpretiert es anschließend als Startzeichen eines Platzhalters.


  $cachesize = sql_value("
  $cachesize = sql_value("
Zeile 177: Zeile 180:
=== Slave-Server ===
=== Slave-Server ===


Beide OC-Libraries sehen eine Lastverteilung auf einen Haupt-Datebankserver (Master) und einen oder mehrere "Slaves" vor, die replizierte Daten des Masters enthalten; siehe {{Codepath|doc/replication.txt}}. Dazu gibt es SQL-Funktionen mit dem Zusatz "_slave", z.B. <code>sql_slave()</code>, die von "datenbankintensiven" Programmmodulen wie z.B. der Suche (search.php) anstatt der Basisfunktionen verwendet werden.
Beide OC-Libraries sehen eine Lastverteilung auf einen Haupt-Datenbankserver (Master) und einen oder mehrere "Slaves" vor, die replizierte Daten des Masters enthalten; siehe {{Codepath|doc/replication.txt}}. Dazu gibt es SQL-Funktionen mit dem Zusatz "_slave", z.B. <code>sql_slave()</code>, die von "datenbankintensiven" Programmmodulen wie z.B. der Suche ({{Codepath2|htdocs|search.php}}) anstatt der Basisfunktionen verwendet werden.


Wenn per ''settings.inc.php'' keine Slave-Server konfiguriert sind, laufen alle Zugriffe über den Master. Zurzeit betriebt kein Opencaching-Knoten Slave-Server; die Kapazität des Masters reicht überall aus.
Wenn per ''settings.inc.php'' keine Slave-Server konfiguriert sind, laufen alle Zugriffe über den Master. Zurzeit betreibt kein Opencaching-Knoten Slave-Server; die Kapazität des Masters reicht überall aus.


=== Temporärtabellen ===
=== Temporärtabellen ===
Zeile 210: Zeile 213:


* Tabellen, Felder und Indizes in {{Codepath2|htdocs/doc/sql|tables}}
* Tabellen, Felder und Indizes in {{Codepath2|htdocs/doc/sql|tables}}
* Stored Functions, Procedures und Triger in {{Codepath2|htdocs/doc/sql|stored-proc}}
* Stored Functions, Procedures und Trigger in {{Codepath2|htdocs/doc/sql|stored-proc}}
* statische Daten wie z.B. Menüs, Cachetypen und sprachabhängige Texte in {{Codepath2|htdocs/doc/sql|static-data/data.sql}}.
* statische Daten wie z.B. Menüs, Cachetypen und sprachabhängige Texte in {{Codepath2|htdocs/doc/sql|static-data/data.sql}}.


Zeile 221: Zeile 224:
==== OKAPI ====
==== OKAPI ====


Die [[OKAPI]]-Tabellen werden zwar in der gleichen Datenbank abgelegt, sind unabhängig von den OC-Tabellen und daher ''nicht'' in {{Codepath|htdocs/doc/sql}} definiert. Bei [http://code.google.com/p/opencaching-api/#Installation_/_Update_Instructions Installation der OKAPI] werden sie automatisch angelegt und bei OKAPI-Updates automatisch aktualisiert. {{Codepath2|bin|dbupdate.php}} führt auch OKAPI-Updates durch, falls die OKAPI installiert ist.
Die [[OKAPI]]-Tabellen werden zwar in der gleichen Datenbank abgelegt, sind aber unabhängig von den OC-Tabellen und daher ''nicht'' in {{Codepath|htdocs/doc/sql}} definiert. Bei [http://code.google.com/p/opencaching-api/#Installation_/_Update_Instructions Installation der OKAPI] werden sie automatisch angelegt und bei OKAPI-Updates automatisch aktualisiert. {{Codepath2|bin|dbupdate.php}} führt auch OKAPI-Updates durch, falls die OKAPI installiert ist.


Auch der OKAPI-''Code'' ist unabhängig vom OC-Code, d.h. sämtliche Datenbankzugriffe sind dort redundant implementiert. '''Bei Änderungen an Datenstrukturen oder -inhalten ist daher immer zu prüfen, ob eine Anpassung der OKAPI nötig ist!'''
Auch der OKAPI-''Code'' ist unabhängig vom OC-Code, d.h. sämtliche Datenbankzugriffe sind dort redundant implementiert. '''Bei Änderungen an Datenstrukturen oder -inhalten ist daher immer zu prüfen, ob eine Anpassung der OKAPI nötig ist!'''
Zeile 262: Zeile 265:
* Herunterzuladende, gepackte '''Ausgaben der [[XML-Schnittstelle]]''' werden in {{Codepath|htdocs/download/zip}} zwischengespeichert (ebenfalls konfigurierbar).
* Herunterzuladende, gepackte '''Ausgaben der [[XML-Schnittstelle]]''' werden in {{Codepath|htdocs/download/zip}} zwischengespeichert (ebenfalls konfigurierbar).
* {{Codepath|htdocs/cache2}} enthält zwischengespeicherte [[#Templates|Templates]], [[#Übersetzung|Übersetzungsdateien]] für gettext und verschiedene Temporärdaten. Ein guter Teil dieser Daten wird von {{Codepath|bin/clear-webcache.php}} neu generiert.
* {{Codepath|htdocs/cache2}} enthält zwischengespeicherte [[#Templates|Templates]], [[#Übersetzung|Übersetzungsdateien]] für gettext und verschiedene Temporärdaten. Ein guter Teil dieser Daten wird von {{Codepath|bin/clear-webcache.php}} neu generiert.
* {{Codepath|htdocs/var}} enthält zwischengespeicherte OKAPI-Daten (die OKAPI legt allerdings auch eine Menge "gecachete" in der Datenbank ab) und Fehlerprotokolle.
* {{Codepath|htdocs/var}} enthält zwischengespeicherte OKAPI-Daten (die OKAPI legt allerdings auch eine Menge "gecachte" Daten in der Datenbank ab) und Fehlerprotokolle.
* {{Codepath|htdocs/cache}} enthält vermutlich nur noch temporäre Prozess-Synchronisationsdateien (.pid-Dateien) der lib1-cronjobs für Log- und Cache-Benachrichtigungen.
* {{Codepath|htdocs/cache}} enthält vermutlich nur noch temporäre Prozess-Synchronisationsdateien (.pid-Dateien) der lib1-cronjobs für Log- und Cache-Benachrichtigungen.
</div>
</div>
Zeile 268: Zeile 271:
== Templates ==
== Templates ==


[[wikipedia:Template (Programmierung)|Templates]] dienen in Webanwendungen dazu, die Generierung von aus- und einzugebenden Daten von deren HTML-Darstellung zu trennen. HTML- und JavaScript-Code wird komplett in den Templates untergebracht, PHP-Code soweit wie irgend möglich in PHP-Scripten.
[[wikipedia:Template (Programmierung)|Templates]] dienen in Webanwendungen dazu, die Generierung von aus- und einzugebenden Daten von deren HTML-Darstellung zu trennen. HTML- und JavaScript-Code wird komplett in den Template-Dateien untergebracht, PHP-Code soweit wie irgend möglich in PHP-Scripten.
 
Die Einbindung der Templates in den PHP-Programmablauf geschieht wie folgt:
# Festlegung, welche Templatedatei verwendet wird
# Zuweisung von variablen Inhalten an das Template
# Darstellung des Templates
Für alle drei Punkte gibt es entsprechende Bibliotheksfunktionen.


=== lib1-Templates ===
=== lib1-Templates ===


Die alte Library enthält ein eigenes, simples Templatesystem. Die Templatedateien befinden sich in {{Codepath|htdocs/lang/de/ocstyle}} und enthalten den auszugebenden HTML- und JavaScript-Code. Für alle variablen Inhalte werden Platzhalter wie z.B. <code>{cachename}</code> eingesetzt; die PHP-Variable wird dann übergeben mit
Die alte Library enthält ein selbstgemachtes, simples Templatesystem. Die Templatedateien befinden sich in {{Codepath|htdocs/lang/de/ocstyle}} und enthalten den auszugebenden HTML- und JavaScript-Code. Der Name der Template-Datei wird im PHP-Code über die globale Variable <code>$tplname</code> festgelegt, z.B.
:<code>$tplname = 'newcache';</code>
 
Für alle variablen Inhalte werden im Template Platzhalter wie z.B. <code>{cachename}</code> verwendet; die PHP-Variable wird dann übergeben mit


tpl_set_var('cachename', $cachename);
:<code>tpl_set_var('cachename', $cachename);</code>


Sofern der variable Teil auch HTML-Code oder etwas zu Übersetzendes enthält, wird dies in speziellen Include-Dateien abgelegt, z.B.
Sofern der variable Teil auch HTML-Code oder etwas zu Übersetzendes enthält, wird dies in speziellen Include-Dateien abgelegt, z.B.
Zeile 283: Zeile 295:
Die Include-Datei wird im PHP-Hauptmodul eingebunden und die Variablen per <code>mb_ereg_replace</code> ersetzt, bevor das Ganze per <code>tpl_set_var()</code> ans Template übergeben wird.
Die Include-Datei wird im PHP-Hauptmodul eingebunden und die Variablen per <code>mb_ereg_replace</code> ersetzt, bevor das Ganze per <code>tpl_set_var()</code> ans Template übergeben wird.


Alle [[Opencaching]]-Seiten außer OC.de und OC.se/no verwenden noch das lib1-Templatesystem.
:<code>tpl_BuildTemplate();</code>
stellt schließlich das Template dar und beendet das PHP-Script.
 
Alle [[Opencaching]]-Seiten außer OC.de und OC.se/no verwenden nur das lib1-Templatesystem.


=== lib2-Templates (Smarty) ===
=== lib2-Templates (Smarty) ===
Zeile 300: Zeile 315:


Der ''caching''-Parameter legt fest, ob das Ergebnis der Templateausgabe zwischengespeichert wird; die Dauer der Zwischenspeicherung ist dann ggf. per
Der ''caching''-Parameter legt fest, ob das Ergebnis der Templateausgabe zwischengespeichert wird; die Dauer der Zwischenspeicherung ist dann ggf. per
  $tpl->cachling_lifetime = 1800;  // halbe Stunde Caching
  $tpl->caching_lifetime = 1800;  // halbe Stunde Caching
festzulegen. Dies empfiehlt sich bei häufig aufgerufenen, rechenintensiven Seiten. Seiten mit ständig wechselndem bzw. benutzerabhängigem Inhalt dürfen '''nicht''' "gecacht" werden!
festzulegen. Dies empfiehlt sich bei häufig aufgerufenen, rechenintensiven Seiten. Seiten mit ständig wechselndem bzw. benutzerabhängigem Inhalt dürfen '''nicht''' "gecacht" werden!


Zeile 309: Zeile 324:


Die zwischengespeicherten Templates werden in <code>htdocs/cache2/smarty</code> abgelegt.
Die zwischengespeicherten Templates werden in <code>htdocs/cache2/smarty</code> abgelegt.
Auf die Initialisierung des Templates folgen Variablen-Zuweisungen (s.u.) und schließlich die Darstellung mit
:<code>$tpl->display();</code>
die das PHP-Script beendet.




Zeile 336: Zeile 356:
Auch simple Berechnung sind möglich, z.B. <code>{$waylength*2}</code>.
Auch simple Berechnung sind möglich, z.B. <code>{$waylength*2}</code>.


Zusätzlich zu dem vom PHP-Code übergebenen Variablen kann man auch eigene definieren, z.B.
Zusätzlich zu dem vom PHP-Code übergebenen Variablen kann man auch Variablen direkt im Template definieren, z.B.
:<code>{assign var=counter value=1}</code>
:<code>{assign var=counter value=1}</code>
Mit <code>{capture}</code> lassen sich u.U. auch komplexere Ausdrücke in einer Variable unterbringen.
Mit <code>{capture}</code> lassen sich u.U. auch komplexere Ausdrücke in einer Variable unterbringen.
Zeile 358: Zeile 378:
<code>|escape</code> ist ein ''Modifizierer'', der den Variableninhalt weiterverarbeitet. In diesem Fall werden HTML-Entitäten "escaped".
<code>|escape</code> ist ein ''Modifizierer'', der den Variableninhalt weiterverarbeitet. In diesem Fall werden HTML-Entitäten "escaped".


Mit <code>{strip}...{/strip}</code> lassen sich alle Whitespaces (Leerzeichen, Tabs, Zeilenumbrüche) in einem Abschnitt herausfiltern, was die auszugebende Datenbank reduziert. Aber Vorsicht, falls Whitespaces als Trennzeichen in Ausgaben benötigt werden!
Mit <code>{strip}...{/strip}</code> lassen sich alle Whitespaces (Leerzeichen, Tabs, Zeilenumbrüche) in einem Abschnitt herausfiltern, was die auszugebende Datenmenge reduziert. Aber Vorsicht, falls Whitespaces als Trennzeichen in Ausgaben benötigt werden!


==== Benutzerdefinierte Erweiterungen ====
==== Benutzerdefinierte Erweiterungen ====
Zeile 389: Zeile 409:
Auch der Inhalt (''body'') von Emails wird über Templates erzeugt.
Auch der Inhalt (''body'') von Emails wird über Templates erzeugt.


lib1-Email-Templates befinden sich in {{Codepath|htdocs/util/notification}} und {{Codepath|htdocs/util/watchlist}} und werden von den entsprechenden PHP-Modulen direkt per <code>mb_ereg_replace()</code> aufgelöst.
lib1-Email-Templates befinden sich in {{Codepath|htdocs/lang/de/ocstyle/email}}, {{Codepath|htdocs/util/notification}} und {{Codepath|htdocs/util/watchlist}} und werden von den entsprechenden PHP-Modulen direkt per <code>mb_ereg_replace()</code> aufgelöst.


lib2-Email-Templates liegen in {{Codepath|htdocs/templates2/mail}} und werden von <code>mail.class.php</code> per Smarty verarbeitet.
lib2-Email-Templates liegen in {{Codepath|htdocs/templates2/mail}} und werden von <code>mail.class.php</code> per Smarty verarbeitet.
Zeile 395: Zeile 415:
=== OKAPI ===
=== OKAPI ===
Die OKAPI hat ein eigenes Templatesystem; mehr dazu im Abschnitt [[#OKAPI|OKAPI]].
Die OKAPI hat ein eigenes Templatesystem; mehr dazu im Abschnitt [[#OKAPI|OKAPI]].
 
== CSS Style Sheets ==
== CSS Style Sheets ==
Die Style Sheets befinden sich in
Die Style Sheets befinden sich in {{Codepath|htdocs/resource2/ocstyle/css}}.
:{{Codepath|htdocs/resource2/ocstyle/css}}
und müssten mal aufgeräumt werden. Das Druck-Stylesheet bedarf einer [http://redmine.opencaching.de/issues/95 Komplettüberarbeitung].


== Grafiken ==
== Grafiken ==
Zeile 405: Zeile 423:
Grafiken für Icons und andere Dinge verteilen sich – soweit es keine Drittbibliotheken betrifft – über drei Verzeichnisse:
Grafiken für Icons und andere Dinge verteilen sich – soweit es keine Drittbibliotheken betrifft – über drei Verzeichnisse:


* {{Codepath|htdocs/images}} (lib1 und lib2)
* {{Codepath|htdocs/lang/de/ocstyle/images}} (lib1)
* {{Codepath|htdocs/lang/de/ocstyle/images}} (lib1)
* {{Codepath|htdocs/images}} (lib2 und lib2)
* {{Codepath|htdocs/resource2/ocstyle/images}} (lib2)
* {{Codepath|htdocs/resource2/ocstyle/images}} (lib2)


Hier herrscht etwas Chaos. Manches ist mehrfach vorhanden - auch innerhalb ''einer'' Library - oder inkonsistent abgelegt, die Dateitypen wechseln zwischen GIF und PNG. Glattziehen lässt sich das kaum, weil Grafiken auch gerne von anderer Stelle aus verlinkt werden, z.B. aus Cachelistings - teils sogar von anderen Plattformen aus. Schiebt man die Grafiken einfach weg oder ändert das Format, zerstört es unbemerkt Cachebeschreibungen.
Hier herrscht etwas Chaos. Manches ist mehrfach vorhanden - auch innerhalb ''einer'' Library - oder inkonsistent abgelegt, manche der Grafiken werden nicht verwendet; die Dateitypen wechseln zwischen GIF und PNG. Wenn dies glattgezogen werden soll, müssen die alten Versionen der Grafiken stehenbleibem weil sie auch gerne von anderer Stelle aus verlinkt werden, z.B. aus Cachelistings - teils sogar von anderen Plattformen aus. Schiebt man die Grafiken einfach weg oder ändert das Format, zerstört es unbemerkt Cachebeschreibungen.
 
Zur Kompatibilität mit alten Cachebeschreibungen und Logs liegen in folgenden Verzeichnissen Grafiken, die anderweitig nicht mehr verwendet werden:
 
* {{Codepath|htdocs/lang/de/stdstyle/images}}
* {{Codepath|htdocs/lib/tinymce/plugins/emotions/images}}
* {{Codepath|htdocs/resource2/stdstyle/images}}
 
Siehe auch: [[Übersicht der Opencaching.de-Icons]]


== Übersetzung ==
== Übersetzung ==
=== Funktionsweise ===


Der OC-Code ist mehrsprachig und frei übersetzbar, mit Ausnahme
Der OC-Code ist mehrsprachig und vollständig übersetzbar, mit Ausnahme des Garmin-Download-Dialogs ({{Codepath2|htdocs|garmin.php}}), dessen untere Hälfte es teils nur in Englisch und teils in Deutsch und Englisch gibt (siehe {{Codepath|htdocs/resource2/ocstyle/js/GarminDisplay.js}}).
* der Benachrichtigungs-Emails, die es bislang nur in Deutsch gibt (-> http://redmine.opencaching.de/issues/141)
* des Garmin-Download-Dialogs ({{Codepath2|htdocs|garmin.php}}), dessen untere Hälfte es nur in Deutsch und Englisch gibt (siehe {{Codepath|htdocs/resource2/ocstyle/js/GarminDisplay.js}})
(weitere noch nicht lokalisierbare Module bitte ergänzen!)


Übersetzungen und Lokalisierungen befinden sich an folgender Stelle:
* {{Codepath|htdocs/doc/sql/static-data/data.sql}}: Tabellen countries_list_default, helppages, languages, languages_list_default, search_ignore (z.Zt. nur Deutsch), <u>sys_trans_text</u>
* {{Codepath|htdocs/templates2/ocstyle/articles}}
* {{Codepath|htdocs/config2/locale.inc.php}}
* ''htdocs/config2/settings.inc.php'': Städteauswahl für die kleine Cachekarte, domainabhängige Einstellungen
* {{Codepath|htdocs/lang/de/ocstyle/email}}
* {{Codepath|htdocs/resource2/ocstyle/images/thumb}}


Die Lokalisierung je nach gewählte Sprache erfolgt grundsätzlich mit folgenden Mechanismen:
 
Die Übersetzung je nach gewählter Sprache erfolgt grundsätzlich mit folgenden Mechanismen:
* In Templates über die Smarty-Tags <code>{t}English Text{/t}</code>. Hierbei können auch Variablen eingesetzt werden, z.B.
* In Templates über die Smarty-Tags <code>{t}English Text{/t}</code>. Hierbei können auch Variablen eingesetzt werden, z.B.
*:<code>{t 1=$cachename 2=$username}The geocache %1 has been found by %2{/t}</code>
*:<code>{t 1=$cachename 2=$username}The geocache %1 has been found by %2{/t}</code>
Zeile 431: Zeile 463:
Achtung: '''Auch für die englische Seitendarstellung läuft nochmal alles durch den Übersetzer''', Artikel ausgenommen. Die englischen Originaltexte in den Templates oder im PHP-Code sind also nur eine Basis für die weitere Übersetzung. Kleinere Fehler dort müssen nicht korrigiert werden, solange die Texte verständlich sind. ''Wenn'' dort etwas korrigiert wird, muss es gleichzeitig auch in der Tabelle ''sys_trans'' in {{Codepath2|htdocs/doc/sql/static-data|data.sql}} geändert werden!
Achtung: '''Auch für die englische Seitendarstellung läuft nochmal alles durch den Übersetzer''', Artikel ausgenommen. Die englischen Originaltexte in den Templates oder im PHP-Code sind also nur eine Basis für die weitere Übersetzung. Kleinere Fehler dort müssen nicht korrigiert werden, solange die Texte verständlich sind. ''Wenn'' dort etwas korrigiert wird, muss es gleichzeitig auch in der Tabelle ''sys_trans'' in {{Codepath2|htdocs/doc/sql/static-data|data.sql}} geändert werden!


Opencaching.de gibt es zurzeit in Deutsch, Englisch, Italienisch und Spanisch. Die Übersetzungen werden durch den von Opencaching Deutschland eingesetzten Code Maintainer organisiert.
Opencaching.de gibt es zurzeit in Deutsch, Englisch, Italienisch und Spanisch; Französisch ist in Arbeit. Eine niederländische Übersetzung ist ansatzweise vorhanden (wer mag sie fertigstellen?). Die Übersetzungen werden durch den von Opencaching Deutschland eingesetzten Code Maintainer organisiert.
 
=== Stolperfallen ===
Vorsicht bei der Korrektur englischer Originaltexte, siehe oben.
 
Die Text-Exportfunktionen im Übersetzungsinterface geben zurzeit die englischen Originale aus der Tabelle ''sys_trans'' aus, die teilweise veraltet sind. '''Dies sollte vor der nächsten Neuübersetzung unbedingt geändert werden.'''
 
Die Funktionen "Quelltext durchsuchen" und "IDs neu sortieren" im Übersetzungsinterface (translate.php) mit anschließendem Datenexport können umfangreichen Merge-Konflikten zur Folge haben. Nur verwenden wenn nötig und möglichst in Abstimmung mit anderen Entwicklern.
 
Satzzeichen sollten wann immer möglich in den übersetzten Texten enthalten sein. Beispielsweise müssen bei Französisch Leerzeichen von :;?! eingefügt werden. (Für Letzteres kann man alternativ auch <code>{t}#colonspace#{/t}</code> (in HTML) oder <code>{$opt.format.colonspace}</code> (in plain text) verwenden.)
 
Bei der Einbettung in JavaScript sind Texte zu escapen; dies geht mit dem Smarty-Modifizierer <code>escape=js</code>. Es gibt jedoch Spezialfälle in denen dies nicht im Template möglich ist; in dem Fall sind HTML-Entities (' " &) in data.sql ''doppelt'' zu escapen, z.B. ''Didn\\\'t find'' für den String ''Didn't find''. Das erste Escaping wird beim SQL-Import von data.sql aufgelöst, das zweite verhindet Kollissionen mit der JavaScript-Stringsyntax.
 
Beim Aufruf von <code>$translate->t(...)</code> muss der zu übersetzend String in ''einfachen'' Kochkommata (<nowiki>''</nowiki>) stehen. Doppelte Hochkommata würden von ''translate.php -> Quelltexte durchsuchen'' nicht erkannt.


== Fehlerbehandlung ==
== Fehlerbehandlung ==
Zeile 466: Zeile 511:
==== unerkanntes Problem ====
==== unerkanntes Problem ====


{{Codepath2|htdocs|lib2/errorhandler.inc.php}} enthält ein noch in der Testphase befindlichen Handler für PHP-Fehler, der auch in lib1 eingebunden ist. Er wird bei PHP-Fehlern aktiv, die (abhängig von der ''error_reporting''-Einstellung in der PHP-Konfiguration) zu einem Abbruch des Scripts führen. Es wird dann eine Fehlermeldung anzeigt und ggf. eine Admin-Mail erzeugt. Es wird die gleiche Emailkonfiguration wie für bei SQL-Problemen (s.o.) verwendet.
{{Codepath2|htdocs|lib2/errorhandler.inc.php}} enthält ein noch in der Testphase befindlichen Handler für PHP-Fehler, der auch in lib1 eingebunden ist. Er wird bei PHP-Fehlern aktiv, die (abhängig von der ''error_reporting''-Einstellung in der PHP-Konfiguration) zu einem Abbruch des Scripts führen. Es wird dann eine Fehlermeldung anzeigt und ggf. eine Admin-Mail erzeugt. Es wird die gleiche Emailkonfiguration wie bei SQL-Problemen (s.o.) verwendet.


Dieser PHP-Errorhandler ist derzeit nur aktiviert, wenn in der Konfiguration der Debug-Modus eingeschaltet ist. Ansonsten erscheint bei Fehlern eine leere Seite.
Dieser PHP-Errorhandler ist derzeit nur aktiviert, wenn in der Konfiguration der Debug-Modus eingeschaltet ist. Ansonsten erscheint bei Fehlern eine leere Seite.
Zeile 486: Zeile 531:
Für die Dokumentation verwendet die OKAPI ein eigenes XML-Format, das von einem Parser aufbereitet wird.
Für die Dokumentation verwendet die OKAPI ein eigenes XML-Format, das von einem Parser aufbereitet wird.


Templates für Methoden, die HTML- oder sonstiges XML-Output liefern, sind in .tpl.php-Dateien zusammen mit den PHP-Quelltexten abgelegt. Variablen werden per PHP-Code eingebunden, meist per "short open tags", z.B.
Templates für Methoden, die HTML- oder sonstiges XML-Output liefern, sind in .tpl.php-Dateien zusammen mit den PHP-Quelltexten abgelegt. Variablen werden per PHP-Code eingebunden, z.B.


  <? if (($vars['my_notes'] == 'desc:text') && ($c['my_notes'] != null)) { /* Does user want us to include personal notes? */ ?>
  <?php if (($vars['my_notes'] == 'desc:text') && ($c['my_notes'] != null)) { /* Does user want us to include personal notes? */ ?>
   &lt;p&gt;&lt;b&gt;<?= _("Personal notes") ?>:&lt;/b&gt; <?= Okapi::xmlescape($c['my_notes']) ?>&lt;/p&gt;
   &lt;p&gt;&lt;b&gt;<?= _("Personal notes") ?>:&lt;/b&gt; <?= Okapi::xmlescape($c['my_notes']) ?>&lt;/p&gt;
  <? } ?>
  <?php } ?>


[[Kategorie:Entwicklung|Codedoku]]
[[Kategorie:Entwicklung|Codedoku]]
Following
Administratoren
2.505

Bearbeitungen

Abgerufen von „https://wiki.opencaching.de/index.php/Spezial:Mobiler_Unterschied/5143...6609“