GeoGet

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== CsvUniImport ======
Plugin slouží k importu bodů, zejména tzv. waypointů, ze souboru ve formátu CSV (Comma Separated Values). Plugin převede zadaný CSV soubor do GPX souboru, který pak importuje do databáze.

{{:flag-english.jpg}} Plugin to import points, especially waypoints, from a CSV file (Comma Separated Values). Plugin converts the specified CSV file to GPX file and then imports it into the database.

===== Autor =====
|**[[http://www.geocaching.com/profile/?u=gordici|Gord]]**, **[[mailto:gord@atlas.cz|Gord]]**| ~~PAYPAL business="gord@atlas.cz" message="Prispevek na skript: Spoiler"~~|

Pokud se Vám doplněk líbí, kliknutím na tlačítko **Donate** můžete přispět na jeho vývoj.

//Nekamarádíte se s PayPalem? Napište mi [[mailto:gord@atlas.cz|email]] a domluvíme se na jiném způsobu, třeba převodu na účet.//

===== Automatická instalace =====
~~GEOGET_INSTALL~~

===== Diskuze =====
Diskuze o tomto skriptu je k dispozici na [[http://www.geocaching.cz/forum/viewthread.php?forum_id=20&thread_id=22635&pid=351093#post_351093|Geocaching.cz]].

===== Popis funkce =====
Plugin vstupní CSV soubor zpracovává v několika krocích:

  - analýza vstupního CSV souboru pro odhad obsahu sloupců a režimu pro zpracování jednotlivých řádků, případná korekce automatického odhadu uživatelem
  - převod vstupního CSV souboru do souboru ve formátu GPX
  - zobrazení protokolu o úspěšnosti převodu, aby bylo možné GPX soubor ručně upravit nebo jinak reagovat na případné chyby
  - import vytvořeného GPX souboru

Plugin automaticky rozeznává

  * typ kódování UTF-8 nebo ANSI
  * konce řádků podle zvyklostí tří operačních systémů (Win - CRLF, Mac - CR, Unix - LF)
  * použití uvozovek k obalení hodnot v jednotlivých sloupcích
  * pokouší se zjistit, zda v jednom řádku vstupního souboru jsou informace o keši i waypointu nebo jsou informace v samostatných řádcích

  * <WRAP round info>
Poznámky:
    * protože informace o keši celkem běžně obsahují v textu čárku ve větě, plugin má jako implicitní oddělovač sloupců středník
    * při automatickém rozeznávání parametrů souborů jde vždy jen o odhad. Je lépe, když uživatel ví, jaká data a v jakém formátu importuje a může odhad zkontrolovat a případně parametry upravit
    * Aby byl soubor úspěšně zpracovatelný, musí obsahovat sloupce obsahující ID keše a zeměpisné souřadnice.
</WRAP>


Plugin dokáže ze souboru importovat následující hodnoty:

  * kód keše (rodičovský bod waypointu)
  * zeměpisné souřadnice waypointu; povoleno a automaticky rozeznáno je mnoho formátů
  * typ waypointu <sup>1)</sup>
  * prefix waypointu <sup>1)</sup>
  * jméno waypointu
  * komentář k waypointu
  * popis waypointu
  * příznak přepisovatelnosti waypointu při dalším importu <sup>1)</sup>

<sup>1)</sup> Pokud nejsou hodnoty načteny ze souboru, plugin použije implicitní hodnoty, které může uživatel nastavit v konfiguraci.

<WRAP round important>
Jestliže při importu není rodičovský bod v databázi nalezen a je konfigurací nastaveno, aby byl vytvořen pomocí GPX, pak mohou být importovány také některé další hodnoty náležející k rodičovskému bodu:

  * souřadnice
  * typ
  * jméno
  * obtížnost
  * terén
  * stát
  * kraj
  * jméno (nick) autora, vlastníka
  * velikost
  * krátký popis
  * dlouhý popis
  * uživatelský komentář
  * hint (nápověda)

Uvedený výčet je maximum, co může být importováno. V CSV souboru nemusí být žádná z uvedených hodnot, pak budou použity hodnoty implicitní, bude-li to potřeba.

Pokud již rodičovský bod v databázi je nebo není nastaveno, aby byl bod přidán pomocí GPX, není možné importovat informace, které patří ke keši a ne k waypointu - viz [[#todo|ToDo část]].

</WRAP>

===== Postup při importu =====
V souladu s kroky, z kterých se zpracování CSV souboru skládá, uživatel:

  - vybere CSV soubor pro zpracování a nastaví jeho správné **kódování**
  - spustí analýzu souboru. Výsledkem bude **odhad typu kódování UTF/ANSI**, **odhad režimu** a **seznam sloupců** v souboru
    * režim i seznam uživatel zkontroluje a pokud to bude potřeba, upraví
    * ke kontrole sloupců by měl napomoci pod seznamem vypsaný první řádek souboru
    * seznam sloupců je možné doplňovat ze seznamu importovatelných hodnot - seznam vpravo
  - spustí převod CSV souboru do formátu GPX. Výsledkem je seznam problémů a informací o převodu. Pokud je to potřeba, může se uživatel vrátit o krok zpět, upravit CSV soubor nebo změnit režim či seznam použitých sloupců
  - spustí import vytvořeného GPX souboru. Po importu bude zobrazen přehled počtu importovaných bodů (keší a waypointů) ve standardním importním dialogu.

<WRAP round important>
Důsledkem chybně nastaveného kódování vstupního souboru může být až nemožnost uložit keše do GPS, věnujte mu tedy pozornost.
</WRAP>

===== Ukázky =====
Po analýze prvního řádku je možné změnit výsledek automatické analýzy a pak pustit **Převod**. Rovněž je možné korigovat automatické použití uvozovek a pak třeba spustit automatickou analýzu znovu nebo změnit režim.

{{ :user:skript:csvuniimport:csvanalyza.png |Po analýze}}

Výsledek převodu z CSV souboru do GPX. Chybný řádek s keškou GC18YCX opravit nedokážeme, takže můžeme kliknout na **Import**. Vše kromě této keše bude importováno. Chyba zobrazená na posledních třech řádcích je způsobena tím, že soubor obsahoval na konci prázdný řádek.

{{ :user:skript:csvuniimport:csvprevod.png |Po převodu do GPX}}

===== Podrobnosti ke zpracování =====

==== Analýza ====
Bývá obvyklé, že obsah sloupců v CSV souboru je obalen uvozovkami, ale pro práci pluginu to není nezbytné. Plugin se pokusí sám zjistit přítomnost tohoto obalení podle prvního znaku souboru. Je tedy potřeba, aby všechny řádky používaly nebo nepoužívaly uvozovky stejně.

=== Rozpoznávání obsahu sloupců ===
Pro správný import není potřeba pevné pořadí sloupců ve vstupním CSV souboru. Plugin se pokusí sám najít importovatelné sloupce a ostatní bude ignorovat. Obsah sloupců je rozlišován pomocí jména sloupce (první řádek CSV souboru). Možná pojmenování jednotlivých sloupců jsou v konfiguračním souboru (položky COL_xxx=…) a uživatel si je může snadno doplnit.

Jestliže soubor neobsahuje v prvním řádku jména sloupců, pokusí se plugin podle obsahu sloupců vyhledat alespoň sloupec s ID keše, který je nezbytný k analýze režimu, a sloupce se souřadnicemi.

Sloupce s nerozpoznaným pojmenováním bude plugin při převodu do GPX ignorovat. Obsahují-li důležité informace, musí uživatel ručně doplnit obsah sloupců ve správném pořadí, jak jsou v řádku použity.

=== Režim řádků v CSV souboru ===
CSV soubor může obsahovat informace organizované dvěma způsoby. Podle toho jsou rozlišovány dva režimy zpracovaní řádků:

  * **smíšený** - na jednom řádku souboru jsou informace o keši i waypointu, vždy v samostatných sloupcích. Typickým představitelem souboru zpracovávaném v tomto režimu může být výstup z Excelu, kde si uživatel uchovával vypočtené finálové souřadnice, než k tomu začal používat **GeoGet**. Sloupec s ID obsahuje kód rodičovského bodu (keše) a v řádku může být případně i sloupec s prefixem pro waypoint
  * **samostatný** - informace o keši jsou na jiném řádku než informace o waypointu. Typickým představitelem souboru zpracovávaného v tomto režimu je výstup z pluginu [[user:skript:csvconfigurable|CsvConfigurable]]. Sloupce s hodnotami pro rodičovský bod nebo pro waypoint jsou pojmenované kteroukoli z těchto možností, ale podle hodnoty v ID jsou příslušné hodnoty chápany správně. To se týká všech hodnot, které mohou být uvedeny jak u rodičovského bodu tak u waypointu (ID, souřadnice, jméno, typ, komentář, uživatelský popis)

Plugin se pokouší během analýzy souboru zjistit, jak je vstupní soubor organizován. Výsledek odhadu pochopitelně nemusí být stoprocentní. Uživatel by měl vědět, co vlastně chce importovat, proto má možnost režim po analýze změnit. Při odhadu režimu se plugin rozhoduje podle

  * seznamu sloupců - pokud existují sloupce pro waypointy (podle jména sloupce) i pro keše, předpokládá //smíšený režim//
  * obsahu sloupce s ID keše - pokud v prvních 100 řádcích souboru je nalezeno ID keše, jehož první dva znaky neodpovídají [[user:databaze#prefix|prefixu]] pro rodičovský bod (PARENT_PREFIX v konfiguraci), pak předpokládá //samostatný režim//

<WRAP round important>
Pozor na nastavení souřadnic. Pokud z analýzy vyjde //Souřadnice WP//, plugin nastaví ''smíšený'' režim a pak musíte režim přepnout na ''samostatný''. Pokud nastavení nezměníte, budou keše bez souřadnic a každé keši bude přidán Final WP s příslušnými souřadnicemi.
</WRAP>


==== Kontroly při převodu do GPX ====
Při vlastním převodu je kontrolován **kód keše**. Ten musí být formálně platný a navíc pro import waypointu musí být keš v databázi. Pokud kód keše platný není, je hlášena chyba. Jestliže keš v databázi není, může být v závislosti na konfiguraci hlášena chyba, keš **vytvořena** nebo **importována** pomocí GClive (import přes GeoJarry není podporován). Vytvořená keš bude mít vlastnosti zadané v CSV souboru nebo, pokud v něm nejsou uvedeny, budou použity přednastavené vlastnosti a ostatní informace o ní nebudou. O neplatnosti kódu keše, vytvoření keše v databázi a případném importu keše je uživatel informován v protokolu. 

**Prefix waypointu** musí být v rámci keše (rodičovského bodu) jedinečný. Plugin se pokusí prefix načíst z importovaného souboru. Pokud jej v souboru nezíská, použije implicitní hodnotu. Jestliže již waypoint s takto získaným prefixem existuje, plugin automaticky najde jedinečný prefix a o jeho změně informuje v protokolu.

Z výše uvedeného popisu kontrol vyplývá, že pluginem **nelze měnit** hodnoty uložené v databázi. Waypoint je vždy vytvořen nový a přidán, keš je přidávána jen v případě, že v databázi ještě neexistuje. (Od verze 1.2.4 je sice možné importem přepisovat v databázi existující WP, ale parametry rodičovských bodů měnit stále nelze.)

===== Nastavení a konfigurace =====
V nastavení je možné definovat:

  * jména sloupců, podle kterých plugin rozeznává obsah
  * implicitní hodnoty některých importovatelných vlastností waypointů a rodičovských bodů
  * způsob zacházení s waypointy rodičovského bodu, který ještě není v databázi

Vysvětlení některých položek v konfiguraci

^ Konstant ^ Význam ^
| SHOW_MESSAGE_LEVEL | Nastavuje nejnižší úroveň zobrazovaných zpráv. Možnosti jsou ''INFO, WARN, ERR''. |
| PARENT_PREFIX | Obsahuje prefix pro rodičovský bod k vytvářeným waypointům a pro kontrolu jeho existence v databázi. Hodnota ''GC'' znamená kešku z geocaching.com. |
| MISSING_GCCODE | Definuje akci, která se provede v případě, kdy ID keše v databázi není. Možnosti jsou **ERR** (bude hlášena chyba, k importu nedojde), **CREATE** (vytvoří rodičovský bod (kešku) v GPX souboru, importem pak dojde k vytvoření rodičovského bodu v databázi), **IMPORT** (napřed importuje kešku pomocí GC.Live funkce Aktualizace stavu keše)|
| DEFAULT_CSVFILE | Obsahuje cestu a jméno vstupního souboru. Normálně je hodnota prázdná a uživatel si soubor vybírá interaktivně ve formuláři. |
| DEFAULT_ID_TYPE | Obsahuje předdefinovaný typ keše, který bude použit při jejím doplnění, pokud je ''MISSING_GCCODE=CREATE'' a ve vstupním souboru není typ keše zadán. |
| DEFAULT_WP_TYPE | Obsahuje předdefinovanou hodnotu typu importovaného waypointu použitou v případě, kdy typ není zadán ve vstupním souboru. Možnosti jsou ''Final Location'', ''Parking Area'', ''Question to Answer'', ''Stage of Multicache''. |
| DEFAULT_WP_PREFIX | Obsahuje předdefinovanou hodnotu prefixu importovaného waypointu, pokud není prefix zadán ve vstupním souboru. V každém případě se při konverzi CSV do GPX kontroluje, zda prefix je jedinečný a pokud ne, plugin se automaticky pokusí najít jedinečný prefix. |
| DEFAULT_WP_FLAG | Definuje předdefinovanou hodnotu Flagu; tj. příznaku ručně upraveného waypointu. Hodnota určuje jak bude s waypointem zacházeno při následujícím případném importu z GC.com a jak bude waypoint obsluhován filtry a exportními makry, resp. funkcí wpt.IsUserWaypoint(). Možné hodnoty jsou **0** (WP se chová jako ručně upravený uživatelem, je chráněn proti přepsání importem a IsUserWaypoint() jej podle toho indikuje), **1** (WP bude importem z gc.com přepsán a wpt.IsUserWaypoint() jej nerozpozná), **2** (WP se chová jako ručně upravený na GC.com, bude importem z GC.com přepsán, tedy je možné jej takto aktualizovat, funkce IsUserWaypoint() jej indikuje)|
| WAYPOINTS_OVERWRITE | Řídí možnost přepisu existujícího WP. Pokud je ve zdrojovém souboru zadán prefix WP a v databázi již takový existuje, bude tento bod přepsán ('1') nebo bude vytvořen nový WP ('0') s jedinečným prefixem|
| COL_* | Obsahuje čárkou oddělené texty, podle kterých plugin v prvním řádku vstupního souboru rozpoznává obsah příslušného sloupce. |

===== Ukázky nastavení a CSV souborů pro některé případy importu =====

==== Import s přepisem WP ====
<code>
ID; Jmeno; Coord; WP type ;     WP prefix; WP comment
GC38GN3; Prazske legendy – O studance Puca; N50°4.555' E014°25.999'; Final Location; FC; komentar;
</code>
  * v konfiguračním souboru musí být nastaveno WAYPOINTS_OVERWRITE='1';
  * v souboru musí být uveden prefix WP, jinak bude vždy vytvořen nový, protože nebude zřejmé, který WP přepsat

==== Keše s azbukou ====
  * CSV - v první řadě je třeba se poprat s azbukou, čemuž musí odpovídat zdrojové CSV. Musí být vytvořeno v kódování **utf-8** a pokud bude mít na začátku BOM (identifikační znaky UTF-8 kódování), bude to lepší. Soubor by měl v prvním řádku obsahovat také identifikace sloupců
  * pokud soubor neobsahuje BOM a analýzou nebude typ kódování správně identifikován, nastavíme zdrojové kódování na UTF-8 ručně. Pokud soubor BOM obsahuje, plugin zdrojový typ kódování nastaví správně sám
  * spustíme ''Analýzu'' a zkontrolujeme jestli správně vyhodnotil hodnoty ve sloupcích

===== Poznámky, známé problémy =====

<WRAP round important>
Prozatím není možné importovat informace, které jsou součástí keše, v případě, kdy keš je již v databázi nebo když tam sice není, ale není nastaveno její doplnění přes GPX - viz [[#todo|ToDo část]].
</WRAP>

  * plugin předpokládá správné nastavení prefixu rodičovského bodu, ke kterým mají být WP přidány. To umožňuje kromě WP ke keším (prefix ''GC'') doplňování k jiným rodičovským bodům (např. Opencaching=''OC'')
  * pokud je z CSV importována keš, pro kterou je v souboru uveden hint, ale ne listing (krátký a dlouhý popis), GeoGet ve sloupci status stejně označí přítomnost listingu. Rozumně totiž předpokládá, že hint, který je součástí listingu, se jinak než importem listingu do databáze dostat nemohl. (Existují keše, které skutečný listing opravdu nemají.)
  * keška, která už v databázi je, nebude importovaná ani v případě, že je použit //samostatný režim//. V případě importování keší by mohlo dojít k tomu, že informace o keši, které v CSV souboru nejsou uvedeny, budou z databáze odstraněny. To rozhodně není to, co by bylo žádoucí. Možná v některé z budoucích verzí doplním možnost importu keší v databázi. Uvidíme
  * pro případnou kontrolu zůstává zůstává na disku soubor ''CsvUniImport.gpx'', který obsahuje data importovaná GeoGetem
  * při zapnutém přepisu WP plugin napřed zruší v databázi u příslušného WP příznak, který přepis při importu zakazuje. Pokud uživatel import přeruší aniž by k přepisu bodu došlo, příznak zákazu přepisu WP již neexistuje a bod bude přepsán i při jiném importu než tímto pluginem.

===== ToDo =====
<WRAP round todo>
  * Možnost importovat z CSV i keše, které již v databázi jsou, je ovšem třeba se poprat s informacemi, které v CSV souboru nejsou, aby nebyly z databáze odstraněny a případně rozhodnout, zda v CSV nechybějí právě proto, že už tam být nemají.
</WRAP>

===== Stažení =====
<WRAP round download>
Stáhnout aktuální verzi: ~~DOWNLOAD csvuniimport-*.gip highest~~
</WRAP>

==== Seznam dostupných verzí ====
{{filelist>csvuniimport:*.[zg]ip&style=table&tableheader=1&tableshowdate=1&sort=mtime}}

===== Seznam změn =====
** 1.2.5 (4.2.2014) do resetu poctu staženi 29.8.2014 staženo 259 x **
  * oprava: při výběru souboru analýza nebrala v úvahu možnou změnu režimu "uvozovek"
  * oprava: pokud není definován datum vytvoření, nenuluje se hodnota a hlásí chybu
  * změna: chyba GC kódu se vypisuje jen když Parent prefix je 'GC'
  * změna: úprava zpracování jednotlivých sloupců, i v případě, kdy nejsou všechny sloupce v uvozovkách, kontroluje možnost uvozovek v jednotlivých sloupcích a případné uvozovky pro import odstraní
  * změna: po výběru souboru se automaticky spustí analýza
  * změna: prefix a typ rodičovského bodu je možné změnit ve formuláři (typ lze vybrat ze seznamu typu bodů v aktuální databázi nebo napsat nový typ, implicitně je zvolen typ definovaný v konfiguraci)
  * změna: implicitní prefix, typ a flag waypointu je možné změnit ve formuláři (typ lze vybrat ze seznamu typů WP v aktuální databázi nebo napsat nový typ, implicitně je zvolen typ definovaný v konfiguraci)
  * změna: import rodičovského bodu (přes API) je logicky možný jen pro keše (parent prefix GC)
  * nový: (Arne1) doplněn sloupec pro Status s hodnotami Active, (Disabled|Disable|Inactive|Unavailable), Archived
  * nový: (Arne1) doplněn sloupec pro datum vytvoření rodičovského bodu (keše)

<hidden onHidden=":!: **Zobrazit změny ve starších verzích**" onVisible="Skrýt změny ve starších verzích">
** 1.2.4 (15.7.2013, počet stažení: 231) **
  * nové: doplněna možnost přepisu existujícího WP místo přidání nového
  * nové: doplněn výpis statistiky převodu CSV do GPX
  * oprava: pokud řádek vstupního souboru neobsahuje kód keše, plugin havaroval
  * oprava: pokud není co importovat, smaže se starý soubor
  * oprava: chybné zpracování prvního řádku s prázdnými položkami mezi oddělovači
  * oprava: pokud není třeba přidávat kešku a není přidáván WP, už nehlásí chybný řádek
  * změna: nepřidá WP, pokud již existuje jiný se stejnými souřadnicemi
  * změna: při analýze se pokusí odhadnout kódování zdrojového souboru ANSI/UTF
  * změna: k popisu přidaného bodu je doplněno jméno zdrojového souboru

** 1.1.3 (30.8.2012, počet stažení: 289) **
  - oprava: úvodní ignorování implicitního INCODING
  - oprava: chybné zpracování prázdného textu v položce
  - nové: testování BOM pro zjištění typu kódování při UTF-8
  - nové: zpracování souboru UTF-8 s BOM (ostatní UTF zpracovat odmítne)

** 1.0.0.2 (15.5.2012, počet stažení: 77) **
  * oprava odinstalace pluginu
  * oprava jména instalačního adresáře
  * oprava zpracování souřadnic v oddělených sloupcích bez příznaku N/E (importovaly se opačně)
  * dvoje uvozovky chápany stejně jako \" (bylo i dřív, ale teď je to zpracováno důsledněji)
  * změna kontroly jedinečnosti prefixu, už se nestane, aby se druhý přidaný WP neimportoval, protože má stejný prefix jako dříve přidaný
  * změna kontroly povinných sloupců, při samostatném režimu již není potřeba sloupců se souřadnicemi WP, změna textu chybového hlášení do srozumitelna
  * informace o úspěšném převodu bez chyby je zobrazena i pokud je zakázáno zobrazování zpráv úrovně INFO, ale okno s protokolem o převodu je prázdné

** 1.0.0.1 (14.5.2012 staženo 19 x) **
  * generálský efekt - oprava požadované verze GeoGetu na veřejně dostupnou
  * oprava zdvojeného řádku v default.pas

** 1.0.0.0 (14.5.2012) **
  * úvodní veřejná verze
</hidden>

{{tag>author_Gord skript ggp gps csv import uses_reltoabspath}}