Opencaching-Wiki - Benutzerbeiträge [de]

Entwicklung/Codedoku

2014-02-02T18:23:56Z

Schwalbe: /* Grundlegende Datenbankfunktionen */ typo

Dies ist eine Materialsammlung zum [http://github.com/OpencachingDeutschland/oc-server3 Opencaching-Programmcode]. Sie soll neuen [[Entwicklung|Entwicklern]] einen Überblick über die Grundstruktur und wichtigsten Bestandteile des OC-Codes geben. Mit "OC-Code" ist alles gemeint, was sich im [[Entwicklung/Git|Git-Repository]] befindet.

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.

Siehe auch: [[Entwicklung/Stil|Style Guidelines]]

== Dateiformat ==

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.

== Hauptmodule ==

Mit "lib1" und "lib2" sind im Folgenden die OC-eigenen Codebibliotheken in {{Codepath|htdocs/lib}} und {{Codepath|htdocs/lib2}} gemeint. Alle Teile des OC-Codes bauen auf einer dieser beiden Bibliotheken auf.

<div class="widelist">
Der OC-Software besteht aus ...
* Den '''darstellbaren Seiten''' der OC-Website, z.B. Startseite (''index'') oder Cachelisting-Anzeige (''viewcache''). Diese bestehen jeweils aus einem PHP-Script im Verzeichnis {{Codepath|htdocs}} und einem [[#Templates|Template]] in {{Codepath|htdocs/templates2/ocstyle}} (lib1: {{Codepath|htdocs/lang/de/ocstyle}}). Das PHP-Script erzeugt die darzustellenden Inhalte, das Template stellt sie als HTML-Seite dar.

* '''Kommandozeilentools''' für verschiedene Zwecke, z.B. Wartungstools die per Crojob oder von Hand aufgerufen werden. Sie befinden sich in an verschiedenen Stellen:
** {{Codepath|bin}} (Update-Scripte)
** {{Codepath|htdocs/util}} (lib1, Tools für Produktivbetrieb)
** {{Codepath|htdocs/util2}} (lib2, Tools für Produktivbetrieb)
** {{Codepath|local}} (spezielle Tools für lokale Verwendung)

* '''APIs''', also Schnittstellen für Datenabruf oder -upload durch Dritte:
** 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 [[XML-Schnittstelle]] in {{Codepath|htdocs/xml}}
</div>

* '''Apache-Rewrites'''. Dies sind Konfigurationsdateien mit dem Name ''.htaccess'', die vom Apache-Webserver ausgelesen werden. Sie interpretieren die übergebene URL und leiten auf ein PHP-Script um. Apache-Rewrites kommen an zwei Stellen zum Einsatz:
** Statistikbilder: {{Codepath|htdocs/statpics/htaccess-dist|htdocs/statpics/.htaccess}}
** OC-Kurz-URLs, z.B. http://opencaching.de/OC1234: diese sind direkt im Produktiv-Webserver konfiguriert.

== Bibliotheken ==

Die einzelnen OC-Module verwenden verschiedene Code-Bibliotheken:

=== Eigene Bibliotheken ===

==== lib1 ====
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 wird eingebunden mit
:<code>require 'lib/common.inc.php'</code>

==== lib2 ====
Die Bibliothek der OC.de-Codversion 2.0 und höher in {{Codepath|htdocs/lib2}}, Nachfolger von lib1. Sie ist wesentlich umfangreicher. Der Code ist aufgeteilt in das "Framework" mit allgemeinen Dingen wie Datenbankzugriff, Authentifizierung, Lokalisierung, Templates etc. und die sogenannte "Business Logic" in {{Codepath|htdocs/lib2/logic}} mit allen Geocaching-spezifischen Klassen und Funktionen.

lib2 wird in Bestandteile der Website eingebunden mit
:<code>require 'lib2/web.inc.php'</code>
und in Kommandozeilentools mit
:<code>require 'lib2/cli.inc.php'</code>

;gemeinsamer lib1- und lib2-Code
Manche Bibliotheksmodule werden versionsübergreifend verwendet, z.B. für Übersetzungen und Sprachauswahl. Sie sind in {{Codepath|htdocs/lib2}} abgelegt.

==== libse ====
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 ====
Für die Klassen aller drei Bibliotheken sind Autoloader installiert. Das heißt wenn man z.B. ein Cache-Objekt benötigt, muss man dafür nicht {{Codepath2|htdocs|lib2/logic/cache.class.php}} einbinden sondern man erzeugt einfach direkt das Objekt:
:<code>$cache = new cache();</code>
{{Codepath2|htdocs/lib2/logic|cache.class.php}} wird dann automatisch geladen.

=== Fremdbibliotheken ===

Die OC-Software macht ausgiebig Gebrauch von fertigen PHP- und JavaScript-Codebibliotheken. Eine vollständige Aufstellung incl. Codepfade, Bezugsquellen etc. enthält {{Codepath|doc/license.txt}}. Hier seien nur die wichtigsten davon erwähnt:

<div class="widelist">
* [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://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 TinyMCE-Installation in {{Codepath|htdocs/resource2/tinymce}}. OC-spezifische Konfigurationsdaten gibt es in {{Codepath2|htdocs/resource2|tinymce/config}}.

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.

</div>

== Konfigurationsdateien ==

==== lib1-Konfiguration ====

Die Einstellungen für lib1-Code befinden sich überwiegend in
:''htdocs/lib/settings.inc.php''
Diese Datei ist nur lokal vorhanden. Als Vorlage für das Aufsetzen einer neuen Produktiv-Installation gibt es die Datei {{Codepath2|htdocs/lib|settings-dist.inc.php}}, die nach ''settings.inc.php'' zu kopieren und anzupassen ist.

Für [[Entwicklung/Entwicklersystem|Entwicklersysteme]] gibt es entsprechend die Vorlage {{Codepath2|htdocs/lib|settings-sample-dev.inc.php}}. Sie verwendet die Datei {{Codepath2|htdocs/lib|settings-dev.inc.php}}, in der die Grundeinstellungen für Entwicklersysteme zusammengefasst sind.

Daneben gibt es noch zwei Konfigurationsdateien ''settings.inc.php'' für die Benachrichtigungs-Cronjobs, in {{Codepath|htdocs/util/notification}} und {{Codepath|htdocs/util/watchlist}}.

Weiterhin verwendet lib1 auch Teile der lib2-Konfiguration, insbesondere {{Codepath2|htdocs/config2|locale.inc.php}}.

==== 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:

* sprachabhängige Einstellungen: {{Codepath2|htdocs/config2|locale.inc.php}}
* sonstige Default-Einstellungen: {{Codepath2|htdocs/config2|settings-dist.inc.php}}
* lokale Einstellungen: ''settings.inc.php''

Auch hier sind Vorlagen für Produktiv- ({{Codepath2|htdocs/config2|settings-sample.inc.php}}) und Entwicklersystem ({{Codepath2|htdocs/config2|settings-sample-dev.inc.php}}) vorhanden, die nach ''settings.inc.php'' zu kopieren und and die lokale Systeminstallation anzupassen sind.

==== Der Rootpath ====

Wenn man in PHP-Scripte mit <code>include</code> oder <code>require</code> weitere Dateien einbindet, geschieht dies relativ zum Verzeichnispfad des Hauptscripts. (Daneben kann man auch weitere Pfade festlegen, in denen PHP nach passenden Scripten sucht.)

Wie unter [[#Hauptmodule|Hauptmodule]] erläutert, befinden sich die Module der OC-Software auf verschiedenen Verzeichnisebenen Die Startseite liegt z.B. in {{Codepath|htdocs}}, das lib2-Cronjob-Modul dagegen in {{Codepath|htdocs/util2/cron}}. Alle diese Module binden lib1- oder lib2-Bibliothekscode ein, der weitere Unterscripte einbindet. Damit das alles funktioniert, wird im OC-Code ein ''Basispfad'' für alle Includes festgelegt. Dieser heißt
:<code>$opt['rootpath']</code>
in lib2 und
:<code>$rootpath</code>
in lib1.

Sofern man keine weiteren Vorkehrungen trifft, wird dieser Rootpath automatisch als Relativpfad "./" gesetzt. Scripte in Unterverzeichnissen müssen ihn dagegen selbst setzen, z.B. "../" wenn das Script eine Ebene tiefer liegt, oder absolut als <code>dirname(__FILE__).'../'</code>, wenn nicht bekannt ist, aus welchem aktuellen Verzeichnis ein Kommandozeilentool aufgerufen wird.

== Konstanten ==

Globale Konstanten sind an folgenden Stellen definiert:

* {{Codepath|htdocs/lib/consts.inc.php}}
* {{Codepath|htdocs/lib2/const.inc.php}}
* {{Codepath|htdocs/lib2/error.inc.php}}
* {{Codepath|htdocs/lib2/logic/const.inc.php}}

Die lib2-Konstanten werden auch teilweise auch in lib1-Code verwendet.

== Datenbank ==

Die OC-Software ist nur für die Verwendung von MySQL ausgelegt. Zwar werden in lib2 keine MySQL-Funktionen mehr direkt aufgerufen, aber zahlreiche SQL-Statements verlassen sich auf MySQL-Syntax.

=== Grundlegende Datenbankfunktionen ===

Für lib2 befinden sich alle Funktionen in {{Codepath2|htdocs|lib2/db.inc.php}} und sind dort kurz dokumentiert, für lib1 in {{Codepath2|htdocs|lib/clicompatbase.inc.php}}. Datenbankverbindungen werden automatisch entsprechend den Konfigurationseinstellungen hergestellt, sobald man eine Query absetzt.

Die wichtigsten Funktionen seien hier anhand von Beispielen erläutert:

sql("UPDATE `caches` SET `size`='&1' WHERE `cache_id`='&2'",
$newsize, $cacheid);

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ü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("
SELECT `size` FROM `caches`
WHERE `cache_id`='&1'",
null, $cacheid);

Hier wird die Größe eines Caches abgefragt. Falls die Cache-ID nicht gefunden wird, wird der Defaultwert ''null'' zurückgeliefert. Denke immer daran, den Defaultwert als ersten Parameter anzugeben! Ihn zu vergessen ist eine häufige Fehlerquelle.

In der lib1 heißt die Funktion anders und kann nicht mit Platzhaltern umgehen; der entsprechende Code lautet dann:

$cachesize = sqlValue("
SELECT `size` FROM `caches`
WHERE `cache_id`='" . sql_escape($cacheid) . "'",
null);

Das folgende Beispiel demonstriert, wie der Inhalt einer Tabelle ausgelesen wird:

$rs = sql("
SELECT `cache_id`, `name`, `type` `size` FROM `caches`
WHERE `cache_id`='&1'",
$cacheid);
while ($r = sql_fetch_assoc($rs))
{
// ... Weiterverarbeitung von $r['cache_id'], $r['name'] etc.
}
sql_free_result($rs);

=== 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 ({{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.

=== Temporärtabellen ===

Da Subqueries bei MySQL recht ineffizient sind, sind manchmal temporäre Tabellen für Zwischenergebnisse nötig.

lib2 sieht einen speziellen Mechanismus zur Verwaltung von Temporärtabellen vor. Sie werden in einer eigenen Datenbank abgelegt, für die erweiterte Zugriffsrechte (Tabellen anlegen/löschen) vergeben werden, und werden per Cronjob automatisch aufgeräumt, wenn sie nicht gleich wieder gelöscht wurden.

Ein (nicht unbedingt sinnvolles) Beispiel für die Verwendung von lib2-Temporärtabellen. Die temporäre Tabelle heißt "tmp_caches" und wird in SQL-Statements über einen Platzhalter referenziert:

sql_temp_table('tmp_caches'); // Tabelle registrieren
sql(" // Tabelle anlegen
CREATE TEMPORARY TABLE &tmp_caches ENGINE=MEMORY
SELECT `cache_id` FROM `caches`
WHERE `user`.`user_id` = `caches`.`user_id`
AND `user`.`country` = '&1'",
$country);

$rs = sql(" // Tabelle auslesen
SELECT * FROM `cache_desc`, &tmp_caches
WHERE `cache_desc`.`cache_id` = &tmp_caches.`cache_id`");
// ... Daten weiterverarbeiten
sql_free_result($rs);

sql_drop_temp_table('tmp_caches'); // Tabelle löschen

=== Datenbankstruktur; statische Daten ===

Datenbankstruktur und -inhalte werden an folgenden Stellen unter {{Codepath|htdocs/doc/sql}} definiert:

* Tabellen, Felder und Indizes in {{Codepath2|htdocs/doc/sql|tables}}
* Stored Functions, Procedures und Triger 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}}.

Es gibt weitere (geographische) "statische Daten", die aufgrund ihres Umfangs nicht im Git-Repository enthalten sind; siehe {{Codepath2|htdocs/doc/sql|static-data/static-data.txt}}. Für Entwickler steht auf Anfrage ein Datenbankdump zur Verfügung, der eine vollständig initialisierte OC-Datenbank enthält (Veröffentlichung ist geplant). Weitere Updates können dann per
:{{Codepath|bin/dbupdate.php}}
eingepflegt werden, also man muss die oben aufgelisteten Dateien nicht von Hand weiterverarbeiten.

Siehe auch: [[Entwicklung/Datenbankversionierung|Datenbankversionierung]]

==== OKAPI ====

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!'''

=== Trigger & Stored Procedures ===

Der Opencaching-Code macht reichlich Gebrauch von gespeicherten Datenbank-Funktionen und Triggern. Sie werden dazu eingesetzt, um die Konsistenz der Datenbankinhalte zu gewährleisten. Vor dem Hintergrund, dass drei unabhängige Frameworks parallel auf die Datenbank zugreifen – lib1, lib2 und OKAPI (und manchmal noch ein Administrator von Hand) – ist diese Vorgehensweise ratsam. Sie macht die OC.de-Datenbank ausgesprochen robust.

Alle Datenbankfunktionen sind in
:{{Codepath|htdocs/doc/sql/stored-proc}}
definiert. Der aktuelle Stand befinden sich in {{Codepath2|htdocs/doc/sql/stored-proc|maintain-current.inc.php}}; für die [[Entwicklung/Datenbankversionierung|Datenbankversionierung]] können zusätzliche ältere Stände bzw. Update-Scripte existieren.

Der Inhalt des ''maintain''-Scripts lässt sich grob untergliedern in
* allgemeine Funktionen für komplexe Berechnungen, z.B. <code>DECTOWP</code> für die Berechnung neuer OC-Wegpunkte
* Update-Funktionen für bestimmte Felder (<code>sp_update_*</code>) die entweder von verschiedenen Triggern aufgerufen werden oder zur Datenbankwartung aus {{Codepath2|htdocs|dbmaint.php}} (Menü Admin|Datenbankwartung)
* Trigger-Prozeduren

Eine Besonderheit sind '''globale Variablen''' die zur Parameterübergabe von PHP-Scripten an Datenbankfunktionen oder zwischen Datenbankfunktionen verwendet werden. Sie sind in {{Codepath2|htdocs/doc/sql/stored-proc|maintain-current.inc.php}} erläutert.

=== SQL-Debugger ===

lib1 und lib2 enthalten einen nützlichen SQL-Debugger ({{Codepath2|htdocs|lib/sqldebugger.inc.php}} bzw. {{Codepath2|htdocs|lib2/sqldebugger.class.php}}). Er zeigt für jedes ausgeführte SQL-Statment

* das Statement selbst,
* ein [http://dev.mysql.com/doc/refman/5.1-olh/de/using-explain.html EXPLAIN],
* die ersten zurückgelieferten Datensätze, falls vorhanden,
* die Ausführungszeit,
* eventuelle MySQL-Warnungen.

Der SQL-Debugger muss in den [[#Konfigurationsdateien|Settings]] aktiviert sein – für lib1 per <code>$sql_debug = true</code>, in lib2 durch Setzen des Flags <code>DEBUG_SQLDEBUGGER</code> in <code>$opt['debug']</code>. Wahlweise kann man diese Flags auch nur in einzelnen zu debuggenden PHP-Quelltexten setzen.

Anschließend ist die zu debuggende Seite mit dem URL-Parameter <code>sqldebug=1</code> aufzurufen.

== Temporärdaten und Inhalte im Dateisystem ==

Manche Dinge werden in Dateien statt in der Datenbank abgelegt.

<div class="mediumlist">
* '''Hochgeladene Bilder''' befinden sich üblicherweise in {{Codepath|htdocs/images/uploads}} (in den Settings änderbar), die Thumbnails darunter in {{Codepath2|htdocs/images/uploads|thumbs}}. Generierte Statistikbilder werden in {{Codepath|htdocs/images/statpics}} abgelegt.
* 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/var}} enthält zwischengespeicherte OKAPI-Daten (die OKAPI legt allerdings auch eine Menge "gecachete" 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.
</div>

== 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 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 ===

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

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

$cachelink = '<a href="viewcache.php?cacheid={cacheid}">{cachename}</a>';
$outputformat_notexist = t('The selected output format is unknown!');

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.

:<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 noch das lib1-Templatesystem.

=== lib2-Templates (Smarty) ===

==== Grundlagen ====

Die neue Bibliothek verwendet die leistungsfähige [[wikipedia:Smarty|Smarty]]-Engine. Smarty-Templates bestehen neben dem HTML/JavaScript-Code im Wesentlichen aus Kontrollstrukturen und Variableneinbindungen. Die Templates sind in {{Codepath|htdocs/templates2/ocstyle}} abgelegt.

Die lib2 definiert die globale Variable
:<code>$tpl</code>
über die alle Zugriffe auf Smarty und die Templates laufen. Am Beginn des PHP-Moduls wird jeweils das Template initialisiert:

$tpl->name = 'newemail'; // Name der Template-Datei
$tpl->menuitem = MNU_MYPROFILE_DATA; // Menü-ID, siehe doc/sql/static-data/data.sql
$tpl->caching = false; // nicht zwischenspeichern

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
festzulegen. Dies empfiehlt sich bei häufig aufgerufenen, rechenintensiven Seiten. Seiten mit ständig wechselndem bzw. benutzerabhängigem Inhalt dürfen '''nicht''' "gecacht" werden!

Neben Caching der Template-''Ausgaben'' gibt es auch eine ''Vorcompilierung'' der Templates selbst. Diese erfolgt
* einmalig für alle Templates per <code>bin/clear-webcache.php</code>,
* automatisch, wenn ein geändertes Template abgerufen wird,
* jedesmal bei jedem Template-Aufruf, falls in den Settings der Debug-Schalter <code>DEBUG_TEMPLATES</code> gesetzt ist.

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.

;Smarty-Syntax

Im Folgenden sind ein paar grundlegende Smarty-Elemente erklärt; ansonsten sei auf die [http://www.smarty.net/docsv2/de/ Smarty-Dokumentation] verwiesen und auf die vielen Bespiele in {{Codepath2|htdocs|templates2/ocstyle}}. (Achtung: Der OC-Code verwendet eine ältere Smarty-Version; nicht alles was in der Doku steht ist hier auch schon verfügbar!)

Alle Smarty-Elemente stehen in geschweiften Klammern {}. Wenn das Template solche Klammern für andere Zwecke verwendet, z.B. für JavaScript-Kontrollstrukturen, müssen diese von der Smarty-Interpretation ausgeklammert werden:

{literal}
function js_function()
{
...
}
{/literal}

==== Variablen ====

Variablen werden z.B. per
:<code>$tpl->assign('cachename', $cache['name']);</code>
an das Template übergeben und dort als
:<code>{$cachename}</code>
verwendet. Es können auch Arrays übergeben werden, deren Elemente statt [] mit einem Punkt referenziert werden.
:<code>{$cache.name}</code>
steht z.B. für <code>$caches['name']</code>, übergeben per <code>$tpl->assign('caches', ...)</code>. Dies funktioniert auch mit numerischen Indizes – z.B. <code>{$user.0}</code> für das erste Element eines $user-Arrays – und mit mehr als zwei Ebenen.

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.
:<code>{assign var=counter value=1}</code>
Mit <code>{capture}</code> lassen sich u.U. auch komplexere Ausdrücke in einer Variable unterbringen.

==== Kontrollstrukturen ====

Bedingte Einbindung von Template-Komponenten ist mit <code>{if} … {elseif} … {else} … {/if}</code>-Anweisungen möglich. Dabei können auch komplexere PHP-Ausdrucke verwendet werden, die als Boolean ausgewertet werden:

{if $show_statistics && ($statdata|@count > 0)}
... Statistik ausgeben ...
{/if}

(@count ist eine [[#Benutzerdefinierte Erweiterungen; Übersetzungen|benutzerdefinierte Funktion]])

Eine weiter häufig verwendete Struktur ist <code>{foreach}</code> zum iterieren von Arrayelementen:

{foreach from=$caches item=cache}
<td>{$cache.name|escape}</td>
{/foreach}

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

==== Benutzerdefinierte Erweiterungen ====

Smarty lässt sich um eigene
* Elemente ("Blocks"),
* Modifizierer und
* Funktionen
erweitern. Der Opencaching-Code enthält eine Reihe solcher eigener Erweiterungen in {{Codepath2|htdocs|lib2/smarty/ocplugins}}.

Die wichtigste Erweiterung ist das <code>{t}</code>-Element zum Übersetzen von Texten. Alle Texte in den Templates werden in Englisch geschrieben und in <code>{t} ... {/t}</code> eingeschlossen; sie werden dadurch automatisch dem Übersetzungssystem zugeführt. Mehr dazu im Kapitel [[#Übersetzungen|Übersetzungen]].

=== Systemtemplate und Menüsystem ===

Was oben über einzelne Templates geschrieben wurde betrifft nur den Teil der Seite, der im ''Content-Container'' dargestellt wird – also dem Teil unterhalb und rechts des Menüsystems und oberhalb der Fußzeile. Alles "drumherum" wird vom ''Systemtemplate'' erzeugt.

Folgende Codedateien sind daran in der lib1 beteiligt ...
* Systemtemplate: {{Codepath2|htdocs|lang/de/ocstyle/main.tpl.php}}
* Menüdefinitionen: {{Codepath2|htdocs|lang/de/ocstyle/lib/menu.php}}
* PHP-Framework: {{Codepath2|htdocs|lib/common.inc.php}} → tpl_BuildTemplate()
... und in der lib2:
* Systemtemplate: {{Codepath2|htdocs|templates2/ocstyle/sys_main.tpl}}
* Menüsystem: Tabelle 'sys_menu' per {{Codepath2|htdocs|doc/sql/static-data/data.sql}}, {{Codepath2|htdocs|lib2/menu.class.php}}
* PHP-Framework: {{Codepath2|htdocs|lib2/OcSmarty.class.php}}

Zusätzliche Hauptmenü-Punkte sind via [[#Konfigurationsdateien|Konfigurationsdateien]] erzeugbar.

=== Email-Templates ===

Auch der Inhalt (''body'') von Emails wird über Templates erzeugt.

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.

=== OKAPI ===
Die OKAPI hat ein eigenes Templatesystem; mehr dazu im Abschnitt [[#OKAPI|OKAPI]].

== CSS Style Sheets ==
Die Style Sheets befinden sich in {{Codepath|htdocs/resource2/ocstyle/css}}.

== Grafiken ==

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

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}}

== Übersetzung ==

Der OC-Code ist mehrsprachig und frei übersetzbar, mit Ausnahme
* 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!)

Die Lokalisierung je nach gewählte 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.
*:<code>{t 1=$cachename 2=$username}The geocache %1 has been found by %2{/t}</code>
* Notfalls direkt im PHP-Code durch Aufruf von <code>$translate->t()</code>, z.B.
*:<code>$text = $translate->t('New password code', <nowiki>''</nowiki>, basename(__FILE__), __LINE__)</code>
* Bei Artikelseiten, die via {{Codepath|htdocs/articles.php}} dargestellt werden, per Ablage der Templates in Unterverzeichnissen von {{Codepath|htdocs/templates2/ocstyle/articles}}.

Das Übersetzungssystem arbeitet intern mit <code>gettext()</code>. Die Strings dafür befinden sich in der Tabellen ''sys_trans'' und ''sys_trans_text''. Man kann sie direkt via {{Codepath2|htdocs/doc/sql/static-data|data.sql}} einpflegen, oder mit dem "Schnellübersetzungsmodus" + "SQL-Export" von {{Codepath2|htdocs|translate.php}} (Menü Admin|Übersetzung). Letzteres kann allerdings jede Menge Git-Merge-Konflikte beim Zusammenführen verschiedener Branches erzeugen, daher werden OC.de-Übersetzungen derzeit nur direkt in {{Codepath2|htdocs/doc/sql/static-data|data.sql}} eingepflegt.

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.

== Fehlerbehandlung ==

Der OC-Code verwendet kein Exception Handling (mit Ausnahme der OKAPI). Wenn etwas fehlschlägt, wird dies durch den Rückgabewert der betreffenden Funktion signalisiert und entsprechend reagiert. Würde man den betroffenen Funktionen noch einen Namenszusatz spendieren, der die mögliche Fehlerrückgabe kennzeichnet, wäre dieses System transparenter und in sich weniger fehleranfällig als ein strukturiertes Exception Handling.

==== fehlerhafte Benutzereingaben ====
Wenn es Probleme mit einer Benutzereingabe gibt, wird das betreffende Template nochmals angezeigt und an passender Stelle eine mit dem CSS-Stil <code>errormsg</code> formatierte Meldung eingeblendet. Dies ist jeweils entsprechend zu implementieren.

==== erkanntes Problem ====
Wenn anderweitig ein nicht handhhabbares Problem erkannt wird, wird das Fehlertemplate angezeigt. In '''lib1''' befindet sich dies in {{Codepath2|htdocs|lang/de/ocstyle/error.tpl.php}} und wird aufgerufen per
:<code>tpl_errorMsg('original_templatename', $fehlermeldung);</code>
z.B.
$error_desc_not_found = t('(internal error) The description is not available.');
...
tpl_errorMsg('editdesc', $error_desc_not_found);

Das '''lib2'''-Fehlertemplate befindet sich in bzw. {{Codepath2|htdocs|templates2/ocstyle/error.tpl}} und wird verwendet mit
:<code>$tpl->error(Fehlernummer)</code>
oder
:<code>$tpl->error($fehlermeldung);</code>
Die Fehlernummern sind in {{Codepath2|htdocs|lib2/error.inc.php}} definiert.

; SQL-Fehler

Bei MySQL-Fehlern wird ein Fehlertemplate anzeigt und eine Admin-Email versandt, sofern in den [[#Konfigurationsdateien|Settings]] eine Mailadresse hinterlegt ist. In der lib1 ist sie in
:<code>$sql_errormail</code>
einzutragen, in der lib2 in
:<code>$opt['db']['error']['mail']</code>.
Entwicklersysteme werden so konfiguriert, dass das komplette SQL-Statement auch direkt angezeigt wird.

Zusätzlich kann man per <code>$sql_warntime</code> (lib1) bzw. <code>$opt['db']['warn']['time']</code> (lib2) eine Warnschwelle für zu lange SQL-Ausführungszeiten festlegen. Bei Überschreitung werden dann Admin-Mails erzeugt.

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

Dieser PHP-Errorhandler ist derzeit nur aktiviert, wenn in der Konfiguration der Debug-Modus eingeschaltet ist. Ansonsten erscheint bei Fehlern eine leere Seite.

== OKAPI ==

Die Opencaching-API ist ein eigenständiges PHP-Projekt, dessen Code auf verschiedenen OC-Seiten zum Einsatz kommt. Die Projekt-Homepage ist http://code.google.com/p/opencaching-api/. Beiträge, die nicht vom Code-Maintainer selbst kommen, werden üblicherweise in Branches hochgeladen und laufen dann durch ein Code Review.

Die OKAPI wird – erfolgreich! – mit einem wesentlich höheren Anspruch an Codequalität und -Stil entwickelt als die OC-Länderseiten. Dokumentation und Codestruktur sind herausragend. Gleichzeitig steht sie bei einigen Details wie Template-Engine, Datenbank-Library und Konstanten-Definitionen hinter dem OC.de-Code zurück. Der OKAPI-Code ist nur für Webanwendungen geschrieben; Einbindung in Kommandozeilentools kann insbesondere am Exception-Handling scheitern.

Der OKAPI-Code wird aus dem OKAPI-Projekt in die lokalen OC-Code-Repositories (nach {{Codepath|htdocs/okapi}}) repliziert. Bei Opencaching.pl und .nl geschieht dies automatisch über einen SVN-"Commit-Hook", bei Opencaching.de manuell durch den Code-Maintainer nach einem Security Review.

OKAPI-Code kann über die "Facade"-Schnittstelle in OC-Code eingebunden werden ({{Codepath2|htdocs|okapi/facade.php}}). OC.pl macht davon insbesondere bei der Karte Gebrauch, die von der OKAPI generiert wird. OC.de verwendet die Facade bislang nur (experimentell) im Update-Script {{Codepath|bin/okapi-update.php}}, das von {{Codepath2|bin|dbupdate.php}} aufgerufen wird.

Sämtliche OKAPI-Seitenzugriffe laufen über eine Rewrite-Engine ({{Codepath2|htdocs|okapi/.htaccess}} → {{Codepath2|htdocs|okapi/controller.php}}). Man kann daher die PHP-Scripte nicht direkt über ihre URLs idenitifizieren sondern muss schonmal etwas suchen. Methoden befinden sich in {{Codepath2|htdocs|okapi/services}}, Seiten mit HTML-Output in {{Codepath2|htdocs|okapi/views}}.

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.

<? 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>
<? } ?>

[[Kategorie:Entwicklung|Codedoku]]

Multicache

2014-02-02T18:14:43Z

Schwalbe: kk

Ein '''Multicache''' oder kurz '''Multi''' ist ein [[Geocache]] mit mehreren '''Stationen''' (engl. ''stages''). Die Koordinaten des [[Listing|Cachelistings]] zeigen meist auf einen Startpunkt oder Parkplatz;<ref>Bei Opencaching.de müssen die Listingkoordinaten – im Gegensatz zu einigen anderen [[Geocaching-Plattformen]] – nicht unbedingt auf die erste Station zeigen, sondern es darf z.B. auch ein Parkplatz oder der Anfang eines Weges sein.</ref> alle weiteren Stationen sind in der Beschreibung aufgeführt. Letzte Station ist das '''Finale''' (engl. ''final''), an dem der Cachebehälter versteckt ist.

Während ein einfacher „[[Cachearten|Tradi]]“ nur zu einer bestimmten Stelle führt, lernt man durch einen Multicache ein weiträumigeres Gebiet kennen. Zum Beispiel einen schönen Wanderweg, oder verschiedene historische Bauwerke in einem Ort, oder interessante Punkte eines [[Lost Place]]s.

== Aufbau von Multicaches ==
Beim Legen eines eigenen Multicaches sind deiner Fantasie keine Grenzen gesetzt. Du kannst z.B. an jeder Station die Koordinaten der nächsten verstecken, oder jeweils ein Rätsel hinterlegen dessen Lösung zur nächsten Station führt. Oder du führst die Rätsel bereits in der Cachebeschreibung auf.

Du kannst auch die Koordinaten aller Stationen in der Cachebeschreibung auflisten und als zusätzliche [[Wegpunkte]] angeben, sodass man diese direkt auf sein [[GPS-Gerät]] übertragen kann. Die Koordinaten des Finales ergeben sich dann z.B. aus Zahlen, die an den Einzelstationen zu errätseln sind.

Grundsätzlich sind zwei Arten von Multicache-Stationen zu unterscheiden:

[[Datei:DSCN3330.JPG|thumb|200px|Beispiel einer physischen Station.]]
=== Physische Stationen ===

Unter einer physischen [[Fachjargon#Station / Stage|Station]] versteht man Dinge, die eigens an der Stelle für den Geocache versteckt worden sind. Diese Dinge können ganz unterschiedlicher Natur sein. Hier gibt es unzählige Möglichkeiten, die von einem beschrifteten Stein, über [[PETling]]e mit Koodinaten über [[Filmdose]]n mit kleinen Rätseln bis hin zu großen, technisch aufwändig gearbeiteten Dosen gehen. Alle diese Stationen haben jedoch eins gemeinsam: Man findet sie, weil sie jemand gezielt dort versteckt hat und meist führen sie direkt zur nächsten Station. Physische Stationen sind für den Sucher sicher die schönste Variante von Wegpunkten, haben jedoch den Nachteil, dass wie der Cache (das Finale) selbst auch jede Station dem gemeinen [[Fachjargon#Mugge|Muggel]] oder anderen äußeren Einflüssen zum Opfer fallen können. Daher bedeutet ein Multi mit physischen Stationen auf jeden Fall mehr [[Cachepflege|Wartungsaufwand]] als:

[[Datei:2012-05-22 12-24-42 861.jpg|thumb|200px|Beispiel für eine Ablese-Station]]
=== Ablese-Stationen ===

Diese Art von Stationen kommen häufig bei Multis in urbanen Gegenden vor. Hierfür bedient sich der Owner bereits vorhandener Gegenstände wie z.B. Verkehrsschilder, Brunnen, Statuen, Gedenktafeln, usw. Zu den gewählten Gegenständen werden im Listing Fragen gestellt, z.B. "Was ist laut dem Schild vor dem du stehst verboten? Anzahl der Buchstaben = X", oder "Wie viele Namen stehen auf der Gedenktafel? Anzahl = Y" Auch hier sind der Phantasie keine Grenzen gesetzt. Sehr gut geeignet sind Ablese-Stationen z.B. für Stadtführungscaches, bei denen dann zu jeder Station auch weiterführende Informationen im Listing stehen.
Ablese-Stationen haben den Vorteil, dass sie nahezu unkaputtbar sind und nicht gemuggelt werden können. Für den Sucher ist es allerdings oft ein wenig langweilig nur Ablese-Stationen zu finden und lediglich ein physisches Finale zu haben. Im urbanen Bereich ist es jedoch oft nicht anders möglich, einen Multi vor [[Fachjargon#Mugge|Muggeln]] zu schützen.

== Wartung des Cachelistings ==
Wenn du einen Multicache auf mehreren Geocaching-Seiten veröffenlichst ([[Mehrfachlisting]]) denke bitte daran, Änderungen an der Beschreibung einzelner Stationen auf ''allen'' Seiten durchzuführen!

== Anmerkungen ==
<references />

[[Kategorie:Geocaches]]

[[pl:Multicache]]

Wie erhalte ich eine GPX-Datei?

2014-02-02T18:07:40Z

Schwalbe: /* Variante 1: Das Suchformular */ typos

Auf Opencaching.de können [[GPX-Datei]]en eines einzelnen Caches oder einer ganzen Auswahl von Caches erzeugt werden, um sie anschließend auf ein [[GPS-Gerät]] oder [[Smartphone-Apps für Opencaching.de|Smartphone]] zu übertragen. Eine Datei kann die Daten von maximal 500 Caches enthalten.

== GPX-Datei eines Caches ==
Wenn du eine Cachebeschreibung abrufst, erscheint dort das Feld „Download als ...“:
[[Datei:Cachelisting Header.png|zentriert]]

Hier kannst du das Dateiformat [[Abkürzungen#GPX|GPX]] auswählen. Nach der Anwahl wird die GPX-Datei für diesen einen Cache erzeugt und heruntergeladen. Die GPX-Datei befindet sich nun auf dem Computer und kann mit einem Programm wie [[OpenCacheManager]] oder [[QLandkarte GT]] auf das GPS-Gerät bzw. Smartphone geladen werden.

Bei Garmin-Geräten geht es noch einfacher: Mit einem Klick auf „An GPS-Gerät senden“ wird die Cachebeschreibung direkt aufs [[Abkürzungen#GPSr|GPSr]] übertragen, ohne den Umweg über einen Dateidownload.

<div style="clear:both;"></div>

== GPX-Datei einer ganzen Auswahl von Caches ==
Um GPX-Dateien für eine Auswahl von Caches zu erstellen gibt es zwei Varianten:

=== Variante 1: Das [[Suchformular]] ===
;Von der [http://www.opencaching.de/index.php?id=63 Opencaching-Startseite] aus den Button ''Caches'' klicken.

Im Suchformular wählst du aus, welche Geocaches dich interessieren und in welcher Reihenfolge sie aufgelistet werden sollten – z. B. die nahegelegensten oder neuesten zuerst. Nach dem Absenden mit einem der „Suchen“-Knöpfe erscheint die gewünschte Liste:

[[Datei:Suchergebnisse.png|600px|thumb|zentriert|Suchergebnisse]]

Um diese Caches als GPX-Datei herunterzuladen, ist eines der beiden Auswahlfelder „Ergebnisse auf dieser Seite“ und „Ergebnis 1 bis 500 (als zip)“ und dann das Format GPX zu wählen. Ersteres liefert nur die Caches die gerade aufgelistet sind, Letzteres dagegen bis zu 500 Suchergebnisse.

==== Umgehen der Größenbegrenzung ====
Manchmal kann es sein, dass man Suchanfragen als GPX laden möchte, die mehr als 500 Caches beinhalten. Dies ist leider nicht ohne Weiteres möglich. Diese Begrenzung kann man allerdings umgehen:
:Man lädt nach der Suche die ersten 500 Ergebnisse und geht danach auf die zweite Ergebnisseite. Die Url ändert sich und endet mit 'startat=20'. Aus der 20 macht man nun eine 501, drückt auf Enter und gelangt so auf Seite 26 der Suchergebnisse und kann die Caches 501 bis 1000 als GPX herunterladen. Dies lässt sich mit 1001, 1501, usw. wiederholen.

Die [[Abkürzungen#GPX|GPX]]-Datei(en) befindet sich nun auf dem Rechner und kann auf das GPS-Gerät, bzw. Smartphone geladen werden.

=== Variante 2: Die [[Cachekarte|Cachekarte]] ===
;Von der [http://www.opencaching.de/index.php?id=63 Opencaching Startseite] aus den Button ''Karte'' klicken.

Wähle zuerst den gewünschten Kartenausschnitt, durch ziehen und Zoomen oder durch Eingabe des gesuchten Ortes. Die Auswahl von angezeigten Caches kann nun – wie in [[Cachekarte]] beschrieben – weiter eingeschränkt (''gefiltert'') werden, zum Beispiel auf bestimmte Cachetypen, Attribute etc.

[[Datei:Cachekarte_Maske.png|600px|thumb|zentriert|Cachekarte]]

Wenn maximal 500 Caches sichtbar sind, ist der GPX-Button über der Karte aktiv. Mit einem Klick auf den Button wird nun die GPX-Datei erzeugt und heruntergeladen.

Während auf der Karte maximal 180 Caches darstellbar sind, kann die GPX-Datei bis zu 500 Caches enthalten. Das bedeutet, dass man den Kartenausschnitt nach Auswahl der Filterkriterien auch über die darstellbaren Caches hinaus erweitern kann. Solange der GPX-Button aktiv bleibt, kann auch eine GPX-Datei heruntergeladen werden.

Die GPX-Datei befindet sich nun auf dem Rechner und kann auf das GPS-Gerät, bzw. Smartphone geladen werden.

== Opencaching-API ==
Über die [[OKAPI]] können ebenfalls GPX-Dateien abgerufen werden, mit der [http://www.opencaching.de/okapi/services/caches/formatters/gpx.html services/caches/formatters/gpx]-Methode. Auch hier gilt die Begrenzung von 500 Caches pro Download.

[[Attribute]] können von der OKAPI bislang nur als Liste in der Cachebeschreibung ausgegeben werden; GC-kompatible Attribute sind in Arbeit.

[[Kategorie:Opencaching]]

Mehrfachlisting

2014-02-02T18:04:07Z

Schwalbe: kk

[[Datei:Wegpunkt extern.png|thumb|hochkant=1.4|gelistet auf OC.de und GC.com]]
Ein '''Mehrfachlisting''' ist das Gegenteil eines [[OConly]]-Caches: Er ist nicht nur bei Opencaching.de, sondern auch auf anderen [[Geocaching-Plattformen]] veröffentlicht.

Durch Mehrfachlistings kann der Cache mehr [[Log]]s erhalten, allerdings muss man als Besitzer immer dafür sorgen, dass der Inhalt aller Listings gleich bleibt. Zudem besteht gegenüber einem OConly der Nachteil, dass der Cache je nach [[Location]] und Schwierigkeitsgrad von Cachern geradezu überrannt wird. Entprechend höher ist der [[Cachepflege|Wartungsaufwand]] durch Beschädigungen, [[Fachjargon#Umverstecken|Umverstecken]], volle Logbücher etc.

Bei Zweitlistings auf Geocaching.com oder Navicache.com sollten die entsprechenden [[Wegpunkte]] im Opencaching-Listing vermerkt sein.

Da die Wegpunkte im Listing manchmal vergessen werden, pflegt das Opencaching-Team intern eine Liste mit zusätzlichen GC-Wegpunkten. Diese werden bislang nicht direkt angezeigt, aber bei der Ausblendoption für "auf GC.com veröffentlichte" Caches in der [[Cachekarte|Karte]] und bei der [[Suchformular|Cachesuche]] berücksichtigt.

[[Kategorie:Opencaching]]
[[Kategorie:Listings und Logs]]

Benutzerprofil

2014-02-02T18:00:07Z

Schwalbe: /* Persönliche Daten löschen */

[[Datei:Profil.png|thumb|rechts|330px|Beispiel für ein Benutzerprofil]]
Das '''Benutzerprofil''' ist dein persönliches „Opencaching-Kontrollzentrum“. Hier kannst du sehen, welche Geocaches du [[Das Onlinelog|geloggt]], [[Wie verstecke ich einen Cache?|versteckt]] und [[Empfehlungen|empfohlen]] hast, und hier kannst du alle deine Benutzereinstellungen ändern.

Um ein Profil zu erhalten, musst du dich zunächst bei Opencaching.de [[Registrierung|registrieren]]. Sobald du dich [[Login auf Opencaching.de|eingeloggt]] hast, kannst du dein Profil mit dem Knopf MEIN PROFIL in der Menüleiste aufrufen.

Andere Benutzer können sich dein ''öffentliches Profil'' anschauen, indem sie in einem deiner Logs oder [[Listing|Cachelistings]] auf deinen Benutzername klicken, genauso wie du dir die Profile anderer Benutzer ansehen kannst. Sie sehen dort das Datum deiner Registrierung, eine grobe Angabe über den Zeitraum seit deinem letzten Login und eine Statistik deiner versteckten und gefundenen Caches. Weitere Informationen kannst du auf Wunsch eingeben bzw. einblenden – siehe „Details“ im nachfolgender Abschnitt.

Du kannst dir dein öffentliches Profil auch selbst anschauen, indem du links im Menü auf „Öffentliches Profil“ klickst.

== Statistik ==
Die Zahl der gefundenen Caches im ersten Abschnitt bezieht sich auf alle geloggten Funde und [[Event|Eventteilnahmen]] – einschließlich Caches, die zwischenzeitlich [[Cachestatus#Gesperrt + Versteckt|gesperrt/versteckt]] wurden. Wenn ein Cache mehrfach geloggt wurde – z.B. ein wiederkehrendes Event oder ein beweglicher Cache – zählt er mehrfach.

Wenn du auf „alle Funde anzeigen“ klickst, wird jeder Cache nur einmal aufgelistet, und versteckte Caches sind ausgeblendet. Daher kann die Zahl in dieser Liste geringer sein als die Gesamtzahl der Funde auf deiner Profilseite.

Bei der Versteckstatistik im dritten Abschnitt zählen die gesperrt/versteckten Caches ebenfalls mit. In deinem öffentlichen Profil und deinem [[Statistikbild]] werden sie dagegen nicht mitgezählt, da andere Benutzer sie nicht sehen können.

== Einstellungen ==
Folgende Einstellungen kannst du in deinem Profil vornehmen bzw. ändern; außer Benutzername und Email-Adresse sind diese alle freiwillig:

* „Profildaten“:
** '''[[Registrierung#Benutzername|Benutzername]]'''
** '''[[Registrierung#Nachname / Vorname|Vor- und Nachname]]'''
** das '''[[Registrierung#Land|Land]]''' in dem du gerade „geocachst“
** die '''[[Koordinaten]]''' deines Standortes
** [[Benachrichtigungen#Benachrichtigung über neue Caches|'''Benachrichtiungsradius''' für neue Caches]]
** '''Emailadresse''': Zum Ändern der Adresse erhältst du an die neue Adresse eine Mail mit einem Sicherheitscode, mit dem du sie aktivieren kannst. Die Adresse wird verwendet, um dir [[Benachrichtigungen]] und [[#Emailversand|Emails]] anderer Benutzer (inklusive von Opencaching-[[Support]]mitarbeitern) zuzustellen.

<div class="widelist">
* „Details“:
** '''Zoomstufe''' für die Mini-Karte, die in den [[Listing|Cachelistings]] angezeigt wird (''von–bis?'')
** '''Statistikdetails''': Dies bewirkt, dass andere Benutzer in deinem Profil zusätzlich eine Fund- und Versteckstatistik nach Cachetypen sehen sowie die Summe deiner Hinweis- und DNF-Logs. Bitte beachte, dass sich solche Statistiken unabhängig von dieser Einstellung auch über die [[Suchformular|Suchfunktion]] oder aus [[XML-Schnittstelle|heruntergeladenen]] Daten erstellen lassen; sie sind also nicht völlig verhinderbar.
** '''Bildstatistik''' und Galerie: Zeigt in deinem Profil die Anzahl deiner hochgeladenen Logbilder an, mit der Möglichkeit, sich eine Galerie aller deiner Logbilder anzusehen.
** '''[[OConly#OConly-81|OConly-81]]'''-Statistik
** '''Wohnort und Alter''': Wird für andere Benutzer angezeigt, falls angegeben
** '''Beschreibungstext''': ein belieber Text, der anderen Benutzern angezeigt wird.
* gewünschtes '''[[Statistikbild]]'''
* '''Passwort''': Änderung erfolgt wie bei der E-Mail-Adresse durch Zusendung eines Sicherheitscodes
* Einstellungen für [[Benachrichtigungen#Beobachten von Caches |'''beobachtete Caches''']]
</div>

== Weitere Funktionen ==
In deinem Profil findest du auch:
* eine Übersicht aller gespeicherten Suchen; siehe [[Suchformular]]
* eine Übersicht aller [[Benachrichtigungen#Beobachtung von Caches|beobachteten Caches]]
* eine Übersicht aller [[Caches ignorieren|ignorierten Caches]]
* eine Übersicht deiner abgegebenen [[Empfehlungen]]
* die Möglichkeit, [[Adoption#Cache adoptioeren|Adoptionsangebote]] anzunehmen

== Emailversand ==
Jeder registrierte Opencaching-Benutzer ist für andere registrierte Benutzer per Email erreichbar; dazu dient der Link „Email senden“ oben rechts im Profil. Wenn du eine Email verschickst kannst du wählen, ob die in deinem Profil hinterlegte Email-Adresse als Absender mitgeschicht wird oder nicht. Ohne Absenderadresse sieht der Empfänger nur deinen Benutzernamen und einen Link auf dein Opencaching-Profil. Dort kann er dir dann per „Email senden“ antworten. Mit Absenderadresse ist die Chance höher, dass du eine Antwort erhältst.

Hin und wieder kommt es vor, dass eine Email in einem Spamordner landet und übersehen wird. Wenn du den Besitzer eines Caches nicht per Mail erreichst, kannst du stattdessen auch ein [[Das Onlinelog#Hinweis|Hinweislog]] bei dem Cache hinterlassen. Vielleicht hast du hier mehr Glück, und die [[Benachrichtigungen|Benachrichtigungsmail]] über deinen Logeintrag kommt an.

== Persönliche Daten löschen ==
Mit Ausnahme der Email-Adresse kannst du alle persönlichen Daten selbst aus deinem Profil löschen. Wenn du auch die Emailadresse löschen lassen möchtest, geht dies nur durch eine [[Account deaktivieren|Deaktivierung]] deines Benutzerkontos. Dies lässt sich nicht mehr rückgängig machen, und alle deine eigenen Caches werden dadurch [[Cachestatus|gesperrt]]! Daher überlege dir, ob du stattdessen nicht lieber bei einem der vielen kostenlosen Email-Anbieter eine neue Adresse anlegen möchtest, die du im Profil angeben kannst.

Mehr zum Umgang mit persönlichen Daten findest du in der [http://www.opencaching.de/articles.php?page=dsb Datenschutzbelehrung].

[[Kategorie:Opencaching]]