Entwicklung/Codedoku: Unterschied zwischen den Versionen
Zur Navigation springen
Zur Suche springen
Entwicklung/Codedoku (Quelltext anzeigen)
Version vom 15. September 2015, 09:53 Uhr
, 15. September 2015→Funktionsweise
K (→Grundlegende Datenbankfunktionen: typo) |
|||
| (22 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 79: | 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 | * '''[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 | * '''[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) | 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. | ||
OC-spezifische Anpassungen sind in {{Codepath|doc/customized-libs.txt}} dokumentiert. | |||
== Konfigurationsdateien == | == Konfigurationsdateien == | ||
| Zeile 179: | Zeile 180: | ||
=== Slave-Server === | === Slave-Server === | ||
Beide OC-Libraries sehen eine Lastverteilung auf einen Haupt- | 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 betreibt 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. | ||
| Zeile 212: | 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 | * 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 264: | 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 " | * {{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 297: | Zeile 298: | ||
stellt schließlich das Template dar und beendet das PHP-Script. | stellt schließlich das Template dar und beendet das PHP-Script. | ||
Alle [[Opencaching]]-Seiten außer OC.de und OC.se/no verwenden | Alle [[Opencaching]]-Seiten außer OC.de und OC.se/no verwenden nur das lib1-Templatesystem. | ||
=== lib2-Templates (Smarty) === | === lib2-Templates (Smarty) === | ||
| Zeile 314: | 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-> | $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 355: | 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 | 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 377: | 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 | 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 426: | Zeile 427: | ||
* {{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. | 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: | Zur Kompatibilität mit alten Cachebeschreibungen und Logs liegen in folgenden Verzeichnissen Grafiken, die anderweitig nicht mehr verwendet werden: | ||
| Zeile 433: | Zeile 434: | ||
* {{Codepath|htdocs/lib/tinymce/plugins/emotions/images}} | * {{Codepath|htdocs/lib/tinymce/plugins/emotions/images}} | ||
* {{Codepath|htdocs/resource2/stdstyle/images}} | * {{Codepath|htdocs/resource2/stdstyle/images}} | ||
Siehe auch: [[Übersicht der Opencaching.de-Icons]] | |||
== Übersetzung == | == Übersetzung == | ||
=== Funktionsweise === | |||
Der OC-Code ist mehrsprachig und | 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}}). | ||
Ü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 | |||
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 454: | 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 489: | 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 | {{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 509: | 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 | 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? */ ?> | ||
<p><b><?= _("Personal notes") ?>:</b> <?= Okapi::xmlescape($c['my_notes']) ?></p> | <p><b><?= _("Personal notes") ?>:</b> <?= Okapi::xmlescape($c['my_notes']) ?></p> | ||
<? } ?> | <?php } ?> | ||
[[Kategorie:Entwicklung|Codedoku]] | [[Kategorie:Entwicklung|Codedoku]] | ||