WebToDate/XML export - import/Reference

WebToDate XML formát

Úvod

Příklad jedné zprávy uložené ve formátu XML WebToDate 4.1 s využitím většiny dostupných elementů je následující:

<?xml version="1.0" encoding="UTF-8"?>
<wtd:collection xmlns:wtd="http://www.webtodate.cz/schemas/2.0/SimpleSchema" xmlns:wtdvar="http://www.webtodate.cz/schemas/2.0/VarSchema">
	<wtd:importsettings>
		<!-- co delat pri chybe-->
		<wtd:continueonerror>no</wtd:continueonerror>
		<!-- zpusob prace s jiz existujicimi zpravami-->
		<wtd:updateregime>newitemsonly</wtd:updateregime>
		<!-- stav importovanych zprav -->
		<wtd:status>entered</wtd:status>
		<!-- uzamceni importovanych zprav -->
		<wtd:locked>no</wtd:locked>
		<!-- URL importovanych zprav -->
		<wtd:newsurl>idrelated</wtd:newsurl>
		<!-- kategorie, do ktere se importuje -->
		<wtd:categories>
			<wtd:category name="Úvodní">
				<wtd:category name="Politika">
					<wtd:category name="Parlament" default="yes"/>
				</wtd:category>
			</wtd:category>
			<wtd:category name="Osobnosti">
				<wtd:category name="Politici"/>
			</wtd:category>
               </wtd:categories>
		<!-- publikace, do ktere se importuje -->
		<wtd:publication>Deník</wtd:publication>
		<!-- téma, do kterého se importuje -->
		<wtd:group>Domácí zprávy</wtd:group>
		<!-- nastaveni pro prideleni predlohy -->
		<wtd:pattern>publicationrelated</wtd:pattern>
		<!-- Uzivatel -->
		<wtd:user id="5">
			<wtd:firstname>Jiří</wtd:firstname>
			<wtd:lastname>Vopršálek</wtd:lastname>
		</wtd:user>
		<!--tym -->
		<wtd:team id="2">Domácí redakce</wtd:team>
		<!--importovat i jeste neexistujici klicova slova -->
		<wtd:addnewkeywords>yes</wtd:addnewkeywords>
		<!-- zdroj -->
		<wtd:origin name="CTK"/>
	</wtd:importsettings>
	<wtd:exported>
		< wtd:date>2003-08-13</ wtd:date>
		< wtd:time>12:30:44</ wtd:time>
	</wtd:exported>
	<wtd:news>
		<!-- zdroj a jeho jednoznacny identifikator -->
		<wtd:origin name="CTK" id="az80-3532"/>
		<!-- stav importovanych zprav -->
		<wtd:status>entered</wtd:status>
		<!-- uzamceni importovanych zprav -->
		<wtd:locked>no</wtd:locked>
		<!-- priznak o jaky typ objektu se jedna -->
		<wtd:newstype >news</wtd:newstype >
		<!-- Nadpis -->
		<wtd:title>Nadpis zprávy</wtd:title>
		<!-- popis -->
		<wtd:description><![CDATA[Popis zprávy (anotace)]]></wtd:description>
		<!-- telo -->
		<wtd:body><![CDATA[Tělo zprávy, tj. vlastní textový obsah]]></wtd:body>
		<!-- Automaticky formatovat -->
		<wtd:dynamic_br>yes</wtd:dynamic_br>
		<!-- Autor -->
		<wtd:source>Josef Novák</wtd:source>
		<!-- nazev kategorie -->
		<wtd:categories>
			<wtd:category name="Úvodní">
				<wtd:category name="Politika">
					<wtd:category name="Parlament" default="yes"/>
				</wtd:category>
			</wtd:category>
               </wtd:categories>
		<!-- nazev publikace -->
		<wtd:publication>Deník</wtd:publication>
		<!-- jazyk -->
		<wtd:language locale="CS">čeština</wtd:language>
		<!-- téma -->
		<wtd:group>Domácí zprávy</wtd:group>
		<!-- Rubrika -->
		<wtd:section>oddíl novin (rubrika)</wtd:section>
		<!-- Predloha -->
		<wtd:pattern>Předloha pro články</wtd:pattern>
		<!-- Tym -->
		<wtd:team id="2">Domácí redakce</wtd:team>
		<!-- Uzivatel -->
		<wtd:user id="5">
			<wtd:firstname>Jiří</wtd:firstname>
			<wtd:lastname>Vopršálek</wtd:lastname>
		</wtd:user>
		<!-- klicova slova oddelena strednikem -->
		<wtd:keywords>WebToDate;zpráva;xml</wtd:keywords>
		<!-- priorita -->
		<wtd:priority>1</wtd:priority>
		<!-- datum zpravy -->
		<wtd:datenews>
			< wtd:date>2003-05-13</ wtd:date>
			< wtd:time>18:30:44</ wtd:time>
		</wtd:datenews>
		<!-- datum publikace -->
		<wtd:datepublished>
			< wtd:date>2003-05-13</ wtd:date>
			< wtd:time>18:30:44</ wtd:time>
		</wtd:datepublished>
		<!-- datum expirace -->
		<wtd:dateexpired>
			< wtd:date>2004-05-13</ wtd:date>
			< wtd:time>00:30:00</ wtd:time>
		</wtd:dateexpired>
		<!-- link nadpisu -->
		<wtd:url>/scripts/detail.asp?id=50646</wtd:url>
		<!-- link popisu -->
		<wtd:descriptionlink>http://www.ctk.cz</wtd:descriptionlink>
		<!--podtext -->
		<wtd:underline>podtext</wtd:underline>
		<!-- link podtextu -->
		<wtd:underlinelink>odkaz podtextu</wtd:underlinelink>
		<!--zkratka -->
		<wtd:abbrev>mojedom</wtd:abbrev>
		<!-- vydani -->
		<wtd:issue id="13">Název vydání novin (textový řetězec)</wtd:issue>
		<!-- číslo stránky -->
		<wtd:pageid>3</wtd:pageid>
		<!-- obrazek -->
		<wtd:image>/images/foto/obrazek..jpg</wtd:image>
		<!-- alt.obrazku -->
		<wtd:altimage>Obrazek</wtd:altimage>
	</wtd:news>
</wtd:collection>

Kořenovým elementem XML dokumentu je element collection. Pod ním mohou následovat tři elementy:

• importsettings – hlavička definující parametry importu. Element je nepovinný, používá se pouze při importu, při exportu se nevytváří.
• exported – nepovinný element obsahující údaj o tom, kdy byl soubor exportován. Vždy se zapíše při exportu, import jej ignoruje.
• news – povinný alespoň jednou, tyto elementy obsahují vlastní data exportovaných nebo importovaných zpráv.

Znaková sada dokumentu musí být UTF-8, jiné znakové sady nejsou podporovány.

Elementy pro zprávy

Následující tabulka obsahuje podrobný popis všech elementů, které se mohou vyskytovat pod elementem news. Výchozí hodnoty jsou hodnoty použité při importu, pokud hodnotu daného elementu nelze zjistit jinak, tj. pokud není element uveden v datech a nelze jeho hodnotu dosadit z parametrů definovaných v hlavičce souboru nebo v parametrech zadaných z formuláře.

Pokud je při importu element vyplněn nesprávně (např. hodnota definovaná výčtem je mimo interval přípustných hodnot, text elementu je příliš dlouhý atd.), je to považováno za chybu a další zpracování se řídí parametrem importu (buď se jde na další zprávu, nebo import končí). Pokud je hodnota elementu prázdná, daný element se při importu ignoruje. Naopak export ukládá jenom ty elementy, pro které má obsah – není-li tedy např. pole Rubrika pro danou zprávu vyplněno, pro tuto zprávu se příslušný XML element neexportuje.

Element	Význam	Popis a poznámky
origin	Zdroj (myšleno původ) a jednoznačný identifikátor	Atribut name definuje název zdroje, atribut id definuje identifikátor zdroje (textový řetězec). Pokud je element uveden, je id atribut povinný, name nepovinný, název zdroje může být uveden i v hlavičce importsettings. Při exportu se vyplňuje vždy id, name v případě, že je zadáno jako parametr exportu. Speciální hodnotou atributu name pro import je hodnota self. Tato hodnota vyznačuje, že data byla exportována ze stejné instalace WebToDate, jako budou importována. Pokud totiž data byla pořízena přímo ve WebToDate, nemají v tabulce pro sledování importů záznam, a tudíž není možná jejich aktualizace přes import běžným způsobem. Hodnotou self se vyznačí, že jde o tento případ a import pak aktualizuje zprávy dle ID zpráv tak jak se v importovaném souboru vyskytují.
status	Stav zprávy	Hodnota je definována výčtem: entered – vloženo pending - ke schválení approved – schváleno published – publikováno archived - archivováno scheduled – odloženo expired – vypršelo Při exportu se vyplňuje vždy, při importu je výchozí hodnota entered, která se použije, pokud není element uveden a pokud není nastavená výchozí hodnota.
locked	Příznak uzamčení zpráv	Hodnota je definovaná výčtem yes / no. Při exportu se vyplňuje vždy. Při importu je výchozí hodnota no, tj. zprávu nemá nikdo uzamčenou.
newstype	Příznak zda se jedná o zprávu, fragment či zdroj	Hodnota je definovaná výčtem news / fragment / asset. Při exportu se vyplňuje vždy. Při importu je výchozí hodnota news, čili jedná se o běžnou zprávu.
title	Nadpis	Povinná hodnota při exportu i importu. Při importu se kontroluje maximální délka.
description	Popis	Při exportu se vkládá do sekce CDATA.
body	Tělo	Při exportu se vkládá do sekce CDATA.
dynamic_br	Autom.řádkování	Hodnota je definovaná výčtem yes / no. Při exportu se vyplňuje vždy. Výchozí hodnota pro import je yes.
source	Autor	Při importu se kontroluje maximální délka.
categories	Zařazení do kategorie	Vyznačuje blok, ve kterém se definuje zařazení do kategorií
category	Kategorie	Pod elementem categories se vyskytují elementy category ve struktuře odpovídající vnoření kategorií, první je vždy kategorie, která v databázi nemá nadřazenou kategorii. Název kategorie se ukládá do atributu, pro element category existují atributy name – systémový název kategorie locname - lokalizovaný název kategorie default – možná hodnota yes vyznačuje, že se jedná o výchozí kategorii zprávy Elementy nemají vlastní obsah, pouze atributy a podřízené kategorie. Při exportu se vyplňuje vždy. Při importu je výchozí hodnota kategorie s nejnižším ID v databázi. Pokud je při importu uveden systémový název neexistující kategorie, jedná se o chybu. Při exportu se vždy vyplňuje lokalizovaný název kategorie (pokud je vyplněn v databázi), při importu se lokalizovaný název kategorie ignoruje.
publication	Publikace	Obsahuje název publikace. Při exportu se vyplňuje vždy. Při importu je výchozí hodnota publikace s nejnižším ID v databázi. Pokud je uveden název neexistující publikace, jedná se o chybu.
language	Jazyk	Je definován názvem jazyka jako hodnotou elementu a zkratkou jako hodnotou atributu locale. Při exportu se vyplňuje vždy, a to jak název, tak zkratka. Při importu je výchozí hodnotou jazyk s nejnižším ID v databázi. Pokud je element při importu uveden, přednost má jeho hodnota, tj.: pokud je hodnota uvedena a je v databázi, přiřadí se zpráva k uvedenému jazyku a zkratka se ignoruje pokud není uvedena hodnota nebo není v databázi nalezena, použije se zkratka Pokud ani zkratka není uvedena nebo není nalezena v databázi, vyvolá se chyba.
group	Témata	Obsahuje názvy témat. Pokud je uveden při importu název neexistujícího tématu, jedná se o chybu. Lze uvést více témat, jednotlivá témata se oddělují středníkem.
section	Rubrika	Při importu se kontroluje maximální délka.
pattern	Předloha	Může nabývat hodnot: nopattern – žádná publicationrelated – podle publikace Konkrétní název předlohy Pokud je element uveden a konkrétní název není nalezen, dochází k chybě. Výchozí hodnota pro import je podle publikace.
team	Tým	Je definován hodnotou elementu a atributem id. Při exportu se vyplňuje vždy, a to jak název, tak id. Při importu je výchozí hodnotou tým, který má uživatel spouštějící import nastaven jako výchozí, pokud výchozí tým nastaven nemá nebo se importuje přes plánovanou úlohu, vybere se výchozí tým uživatele provádějícího import, případně pak tým s nejnižším ID (tedy v podstatě vždy Administrátoři). Pokud je element při importu uveden, přednost má jeho hodnota, při vyhodnocování se postupuje totožně jako u jazyka.
user	Uživatel	Je definován obsahem elementu a atributem id, přičemž obsah elementu je rozdělen na elementy firstname a lastname. Při exportu se vyplňuje vždy, a to jak jméno, tak id. Při importu je výchozí hodnotou uživatel s nejnižším ID, který je členem týmu Administrátoři. Pokud je element při importu uveden, přednost má jeho hodnota, při vyhodnocování se postupuje totožně jako u jazyka.
keywords	Klíčová slova	Klíčová slova se zapisují v XML souboru jako jeden řetězec, slova jsou oddělená středníkem. Při importu se kontroluje na maximální délku každé klíčové slovo zvlášť. Při importu se dále zohledňuje nastavení pro automatické zakládání nových klíčových slov v globálních předvolbách. Pokud je nastaveno přiřazování pouze existujících klíčových slov a je nalezeno neexistující slovo, nepovažuje se toto za chybu a pouze se událost zapíše do logu.
priority	Priorita	Při importu se kontroluje, že je zadáno celé číslo, údaj je nepovinný.
datenews	Datum zprávy	Všechny datumy se ve formátu WebToDate 3.8 zapisují s odděleným datumem a časem do zvláštních elementů, takže pod elementem pro datum existují vždy elementy date a time. Přitom time má výchozí hodnotu 0:00:00, date je povinný, pokud je uveden jeho nadřazený element. Při exportu se datum exportuje vždy, při importu má výchozí hodnotu aktuální datum a čas.
datepublished	Datum publikace	Analogicky jako datenews, není při importu povinné.
dateexpired	Datum vypršení	Analogicky jako datenews, není při importu povinné.
url	Odkaz nadpisu	Při importu se kontroluje maximální délka, v praxi se ale toto pole typicky přepisuje pomocí nastavení příslušného parametru v objektu pro import, tedy URL odpovídá zpravidla číslování zpráv v databázi, do které se importuje.
descriptionlink	Odkaz popisu	Při importu se kontroluje maximální délka.
underline	Podtext	Při importu se kontroluje maximální délka.
underlinelink	Odkaz podtextu	Při importu se kontroluje maximální délka.
abbrev	Zkratka	Při importu se kontroluje maximální délka a unikátnost zkratky. Pokud je maximální délka překročena, jedná se o chybu, pokud není dodržena unikátnost, nejedná se o chybu, událost se zapíše do protokolu a zkratka se do zprávy nezapíše.
issue	Vydání	Element pro vydání obsahuje název vydání a atribut s ID vydání. Při exportu se vyplňují oba údaje, pokud je zpráva součástí nějakého vydání. Při importu se atribut s ID vydání vždy ignoruje. Při importu se postupuje následovně: Hledá se vydání podle názvu vydání v importované zprávě. Pokud je nalezeno víc než jedno vydání s daným názvem (jednoznačnost názvu vydání není v databázi zaručena) vyvolá se chyba. Pokud je nalezeno právě jedno vydání, kontroluje se, jestli vydání v databázi patří do publikace, do které se daná zpráva aktuálně importuje. Pokud tomu tak není, opět se vyvolá chyba. Pokud tomu tak je, zpráva se zařadí do tohoto existujícího vydání. Pokud vydání podle názvu není nalezeno, zakládá se nové. Název publikace zakládaného vydání se odvodí od publikace aktuálně zpracovávané zprávy, za datum vydání se dosadí datum aktuálně zpracovávané zprávy, případně aktuální datum, pokud datum zprávy v XML není. Stav takto nově založených vydání je vždy Vloženo. ID vydání se přidělí analogickým způsobem jako při ručním zakládání vydání.
pageid	Číslo stránky	Při importu se kontroluje, zda se jedná o celé kladné číslo.
image	Obrázek	Při importu se kontroluje maximální délka.
altimage	Alt. obrázku	Při importu se kontroluje maximální délka.
attachments	Soubory ve zdrojích	Používá se, jen pokud se jedná o zdroje, nikoli o zprávy. Viz podkapitola Import zdrojů.
instances	Seznam instancí z databáze zdrojů	Seznam instancí položek ze zdrojů připojených ke zprávě, viz kapitola Instance zdrojů ve zprávách.

Komplikovanější je při importu práce s kategoriemi. Z hlediska stromu kategorií může dojít k následujícím stavům:

• Některá z kategorií neexistuje – toto se nepovažuje za chybu, zpráva se zařadí do těch kategorií, které existují, a pouze se tato skutečnost zapíše do protokolu importu.
• Žádná z kategorií neexistuje – jedná se o chybu, zpráva se do databáze nezapíše a dál se pokračuje podle nastavení continueonerror (tedy buď se pokračuje na další zprávu, nebo import končí).
• Kategorie není označená pro vkládání dat – do těchto kategorií nelze vkládat data ani importem. S takovou kategorií se nakládá stejně, jako kdyby nebyla nalezena.

Zpráva musí být v právě jedné výchozí kategorii. Přednost má kategorie označená atributem default, ale mohou nastat následující případy:

• Kategorie označená atributem není nalezena
• Kategorie označená atributem není určena pro vkládání dat
• Atribut je chybně uveden v jiné než poslední úrovni vnoření elementu category

Ve všech těchto případech se pak atribut default ignoruje (zapíše se do protokolu) a jako výchozí kategorie je označena první v pořadí jak se nachází v XML datech, do které lze zprávu uložit.

Pokud je uživatel a tým explicitně uveden (v datech či nastavení z formuláře), řadí se zpráva podle toho stejně jako v aktuální verzi, a to bez ohledu na to, jaký tým vlastní kategorii.

Pokud není uživatel či tým uveden, využívá se toho, že každá kategorie má tým, který ji vlastní:

• Zpráva se přiřadí týmu vlastnícímu kategorii, která byla vybrána importem jako výchozí.
• Zpráva je přiřazena uživateli s nejnižším ID, a který je zároveň v týmu, do kterého byla zařazena. Pokud tým nemá žádné uživatele, postupuje se jako doposud (uživatel s nejnižším ID, který je členem týmu Administrátoři). To platí i v případě, že je uveden jen tým a nikoliv uživatel.

Elementy pro rozšířenou strukturu databáze zpráv

Od verze WebToDate 4.1 lze definovat rozšířenou ("přizpůsobitelnou") strukturu databáze zpráv (pomocí nabídky Administrace - Struktura zpráv ve WebToDate, viz referenční příručka WebToDate). Obsah této struktury lze rovněž pomocí tohoto modulu exportovat a importovat. Rozšíření formátu obsahujícího pouze pevně daná pole struktury zpráv naznačuje následující příklad:

<?xml version="1.0" encoding="UTF-8"?>
<wtd:collection xmlns:wtd="http://www.webtodate.cz/schemas/2.0/SimpleSchema" xmlns:wtdvar="http://www.webtodate.cz/schemas/2.0/VarSchema">
	<wtd:news>
		<wtd:title>Nadpis zprávy s var.strukturou</wtd:title>
		<wtd:var doctype="enhanced_news">
			<wtdvar:PEREX_SECT>Americká zpěvačka Beyoncé Knowlesová se dostala pod palbu kritiky australských skupin bojujících proti kouření.</wtdvar:PEREX_SECT>
			<wtdvar:PLACE>Austrálie</wtdvar:PLACE>
			<wtdvar:RELATED_URL>http://www.allmusic.com/</wtdvar:RELATED_URL>
			<wtdvar:REVISIONDATE>13.3.2008</wtdvar:REVISIONDATE>
			<wtdvar:RATING/>
			<wtdvar:SECTIONIMG/>
		</wtd:var>
	</wtd:news>
</wtd:collection>

Jako dceřinný element elementu <wtd:news> se používá element <wtd:var>, který obsahuje jednotlivá pole variabilní struktury. Atributem elementu <wtd:var> je název typu dokumentu, v této verzi vždy hodnota enhanced_news. Uvnitř tohoto elementu jsou pole přizpůsobitelné struktury jako jednotlivé elementy ve jmenném prostoru wtdvar. Názvy elementů jsou dány názvy polí přizpůsobitelné struktury tak, jak je definoval administrátor při zakládání této struktury. U těchto elementů nejsou povinné žádné atributy, obsahem elementu je hodnota daného pole variabilní struktury.

Pro export platí, že element <wtd:var> je přítomen v exportované položce za následujících podmínek:

1. Jedná se o zprávu, nikoli o zdroj či fragment
2. Zpráva má pole přizpůsobitelné struktury
3. Alespoň jedno pole této struktury je vyplněno nějakou hodnotou.

Při importu lze element uvádět jako

<wtd:var doctype="enhanced_news">

nebo pouze

<wtd:var>

Jiná hodnota atributu doctype je považována za chybu.

Obsah přizpůsobitelné struktury uvnitř elementu <wtd:var> se při importu kontroluje stejně jako při zadávání do formuláře pro zprávy. Za chybu se tedy považují následující skutečnosti:

• Ve jmenném prostoru wtdvar je uveden element, který není ve WebToDate definován jako pole přizpůsobitelné struktury zpráv.
• Obsah elementu jsou data nesprávného datového typu (tak jak jsou ukládána do databáze, čili datum je v tomto případě datum formátu 13.3.2008 apod.).
• Element, který je v definici struktury označen jako povinný, není vyplněn nebo není vůbec uveden.
• Je překročena maximální délka textu tam, kde je v definici pole tato délka omezena.
• Přizpůsobitelná struktura je vložena do importované položky, která má v elementu <wtd:newstype> jinou hodnotu než news (jedná se tedy např. o zdroj a nikoli o zprávu)
• Je konflikt se nějakým jiným omezením z definice pole ve WebToDate, např. pole, u kterého není povoleno formátování, obsahuje nějaké formátovací značky.

Všechny tyto případy jsou chyba, zpráva s takovou chybou se neimportuje a dál se pokračuje dle nastavení continueonerror pro chyby (čili buď se import ukončí, nebo se pokračuje na další zprávě).

Naopak za chybu se nepovažuje chybějící element z definice dokumentu, který není v definici označen jako povinný – takový element není povinné v XML formátu uvádět.

Hlavička pro import

Hlavička pro import je obsažena v elementu importsettings např. takto:

	<wtd:importsettings>
		<!-- co delat pri chybe-->
		<wtd:continueonerror>no</wtd:continueonerror>
		<!-- zpusob prace s jiz existujicimi zpravami-->
		<wtd:updateregime>newitemsonly</wtd:updateregime>
		<!-- stav importovanych zprav -->
		<wtd:status>entered</wtd:status>
		<!-- uzamceni importovanych zprav -->
		<wtd:locked>no</wtd:locked>
		<!-- URL importovanych zprav -->
		<wtd:newsurl>idrelated</wtd:newsurl>
		<!-- kategorie, do ktere se importuje -->
		<wtd:categories>
			<wtd:category name="Úvodní">
				<wtd:category name="Politika">
					<wtd:category name="Parlament" default="yes"/>
				</wtd:category>
			</wtd:category>
               </wtd:categories>
		<!-- publikace, do ktere se importuje -->
		<wtd:publication>Deník</wtd:publication>
		<!-- tema, do ktereho se importuje -->
		<wtd:group>Domácí zprávy</wtd:group>
		<!-- nastaveni pro prideleni predlohy -->
		<wtd:pattern>publicationrelated</wtd:pattern>
		<!-- Uzivatel -->
		<wtd:user id="5">
			<wtd:firstname>Jiří</wtd:firstname>
			<wtd:lastname>Vopršálek</wtd:lastname>
		</wtd:user>
		<!--tym -->
		<wtd:team id="2">Domácí redakce</wtd:team>
		<!--importovat i jeste neexistujici klicova slova -->
		<wtd:addnewkeywords>yes</wtd:addnewkeywords>
		<!-- zdroj -->
		<wtd:origin name="CTK"/>
	</wtd:importsettings>

Celý element importsettings je pro import nepovinný, všechny elementy v něm jsou rovněž nepovinné. Význam hlavičky je takový, že lze pomocí ní předefinovat obsah jednotlivých elementů ve zprávách a definovat další parametry importu, které nejsou součástí dat importovaných zpráv (např. způsob práce s již existujícími zprávami). Pokud je tedy některý element v importsettings uveden, jeho hodnota hromadně předefinovává tuto hodnotu v jednotlivých zprávách. Např. pokud je uveden element category, všechny importované zprávy budou importovány do této kategorie nezávisle na tom, co je uvedeno v elementu category u jednotlivých zpráv.

Seznam elementů použitelných v elementu importsettings

Následující tabulka udává seznam elementů použitelných v importsettings a jejich význam:

Element	Význam	Popis a poznámky
continueonerror	Způsob zpracování chybových stavů	Hodnota je definovaná výčtem yes / no. Pokud je uvedeno yes, chyba při zpracování dané zprávy způsobí, že daná zpráva se nenaimportuje a pokračuje se na další zprávě, v opačném případě se ukončí celý import.
updateregime	Způsob práce s již existujícími zprávami	Hodnota je definovaná výčtem: newitemsonly – nové zprávy se importují, již naimportované zprávy se nemodifikují standard – nové zprávy přidat, existující aktualizovat addallitems – všechny zprávy přidat znovu
status	Stav zpráv	Platí to samé jako pro element status ve zprávách
locked	Příznak uzamčení zpráv	Platí to samé jako pro element locked ve zprávách
newsurl	Způsob vyplňování pole Odkaz nadpisu	Hodnota je definovaná výčtem: idrelated – podle přidělených ID original – podle elementu url ve zprávách; v tomto případě se automaticky ve WebToDate nastaví příznak uzamčení URL pro automatické změny
categories	Kategorie	Platí to samé jako pro element categories ve zprávách
publication	Publikace	Platí to samé jako pro element publication ve zprávách
group	Témata	Platí to samé jako pro element group ve zprávách
pattern	Způsob vyplňování pole Předloha	Platí to samé jako pro element pattern ve zprávách
user	Uživatel	Platí to samé jako pro element user ve zprávách
team	Tým	Platí to samé jako pro element team ve zprávách
addnewkeywords	Přidávat nová klíčová slova	Hodnota je definovaná výčtem yes / no. Pokud je uvedeno yes, nová klíčová slova se automaticky přidávají do seznamu klíčových slov. Výchozí nastavení je v globálních předvolbách. Pokud je možnost automaticky přidávat nová klíčová slova zakázána v těchto předvolbách, tato slova se nikdy nepřidávají ať je obsah importovaného XML souboru jakýkoliv.
origin	Označení zdroje dat	Označuje zdroj dat. Pokud chceme importovaný soubor označit daným zdrojem dat, je nejjednodušší zde zadat název zdroje dat a pouze zajistit, že v elementech origin v atributu id je uveden nějaký identifikátor ze systému, ze kterého se exportuje.
createinstances	Import instancí položek ze zdrojů	Pokud má element hodnotu yes, importují se instance, viz kapitola Instance zdrojů ve zprávách.

Pokud je element importsettings v souboru přítomen, platí nastavení v něm uvedená pro všechny zprávy následující za tímto elementem. Z toho vyplývá, že

• Pokud chceme, aby tato nastavení platila pro všechny zprávy, musí být tento element uveden v souboru jako první za kořenovým elementem.
• Element importsettings se může v souboru vyskytovat i několikrát, nastavení daná tímto elementem jsou pak platná pro zprávy následující za tímto elementem.

Pokud je nějaká hodnota elementu (např. kategorie) nastavena nekorektně v elementu importsettings, jedná se o fatální chybu a import končí okamžitě.

Instance zdrojů ve zprávách

Export instancí

Je-li v nastavení exportu zvoleno Exportovat seznam příloh, vkládá se do exportovaných dat dovnitř elementu <wtd:news> element <wtd:instances>, který tento seznam příloh obsahuje. Pokud je zároveň zvoleno Nahradit instance HTML kódem, jedná se jen o seznam instancí, které jsou přílohami (připojeny k nějakému druhu seznamu jako Přílohy ke stažení apod.), v opačném případě i individuálně připojené položky pod nějakým stylem.

Příklad takového XML kódu uvnitř jedné zprávy je následující:

<wtd:instances>
		<wtd:assetsfolder>assets</wtd:assetsfolder>
		<wtd:urlprefix>http://www.mujserver.cz</wtd:urlprefix>
		<wtd:instance id="57734" assetid="29370" style="Ilustrační obrázek" default="yes">
			<wtd:status>published</wtd:status>
			<wtd:locked>no</wtd:locked>
			<wtd:title>Jiří Paroubek přichází na jednání vlády</wtd:title>
			<wtd:description><![CDATA[Premiér Jiří Paroubek přichází na jednání vlády 10.9.2006 ve Strakově akademii]]></wtd:description>
			<wtd:source>Martin Dorazil</wtd:source>
			<wtd:categories>
				<wtd:category name="Home">
					<wtd:category name="Zprávy">
						<wtd:category name="Domácí" default="yes"/>
					</wtd:category>
				</wtd:category>
			</wtd:categories>
			<wtd:publication>Deník</wtd:publication>
			<wtd:language locale="CS">čeština</wtd:language>
			<wtd:keywords>čr;paroubek;čssd;politici</wtd:keywords>
			<wtd:datenews>
				<wtd:date>2006-09-11</wtd:date>
				<wtd:time>13:10:55</wtd:time>
			</wtd:datenews>
			<wtd:url>/scripts/detail.php?id=117411</wtd:url>
			<wtd:attachments>
				<wtd:attachment id="6816">
				<wtd:filename>1156334663_200608230285_BYDEEE_3.jpg</wtd:filename>
					<wtd:filepath>/zpravy/domaci/politika/</wtd:filepath>
					<wtd:targetlocation>public</wtd:targetlocation>
					<wtd:filetype>jpg</wtd:filetype>
					<wtd:filesize>5302</wtd:filesize>
					<wtd:filewidth>160</wtd:filewidth>
					<wtd:fileheight>114</wtd:fileheight>
				</wtd:attachment>
			</wtd:attachments>
		</wtd:instance>
	</wtd:instances>

<wtd:instances> je tedy element na stejné úrovni vnoření jako např. <wtd:title>. Za <wtd:instances> následují:

<wtd:assetsfolder> - obsahuje hodnotu konfigurační konstanty ASSETS_PUBLICFILES resp. ASSETS_PRIVATEFILES, a to podle toho, zda se soubor nachází ve veřejné nebo privátní zóně

<wtd:urlprefix> - vkládá se, jen pokud je v nastavení exportu vyplněno Prefix pro URL souborů ze zdrojů, v tom případě obsahuje tuto zadanou hodnotu

Kompletní URL souboru tak lze sestavit pomocí <wtd:urlprefix>, <wtd:assetsfolder>, <wtd:filepath> a <wtd:filename>.

Následují elementy <wtd:instance>, každý element reprezentuje jednu instanci položek z databáze zdrojů připojených ke zprávě.

<wtd:instance> obsahuje následující atributy:

• id - ID instance
• assetid - ID zdroje, do kterého soubor patří
• style - název stylu, pod kterým je položka připojena
• list - název druhu seznamu, ke kterému je položka připojena, vždy je existuje buď style, nebo list, nikdy oboje najednou
• default - výchozí příloha má default="yes", ostatní bez tohoto atributu

Následují vybraná metadata zdroje, do kterého soubor patří, syntaxe je stejná jako u formátu pro vlastní zprávy resp. zdroje. Neboli:

<wtd:status> - stav

<wtd:locked> - uzamčeno

<wtd:title> - nadpis zdroje

<wtd:description> - popis zdroje

<wtd:source> - autor

<wtd:categories> - kategorie

<wtd:publication> - publikace

<wtd:language> - jazyk

<wtd:keywords> - klíčová slova

<wtd:datenews> - datum a čas

<wtd:url> - odkaz nadpisu

Následuje element <wtd:attachments>, který v tomto případě obsahuje vždy právě jeden element <wtd:attachment>, který již má v sobě údaje o souboru resp. položce. <wtd:attachment> má atribut id, což je ID souboru ve WebToDate.

<wtd:attachment> obsahuje následující elementy:

<wtd:filename> - název souboru

<wtd:filepath> - cesta

<wtd:targetlocation> - zóna resp. externalurl

<wtd:filetype> - typ souboru

<wtd:filesize> - velikost

<wtd:filewidth>- šířka

<wtd:fileheight> - výška

<wtd:fileurl> - URL v případě, že jde o externalurl

Import instancí

Import instancí je podporován v omezené formě. Podmínkou toho, aby se instance importovaly, jsou následující skutečnosti:

• Zdroje a soubory v nich, na které se mají instance odkazovat, již v databázi existují
• V XML se používají skutečná ID relevantních objektů

Import instancí je třeba explicitně zapnout. Ve formulářích pro import je za tímto účelem zaškrtávací okénko Pro zprávy importovat instance, druhou možností je v importovaném XML uvést

<wtd:createinstances>yes</wtd:createinstances>

a to buď v elementu importsettings nebo v elementu news. Pokud element není uveden nebo má jinou hodnotu než yes, instance se nemají zpracovávat.

Pro import instancí je relevantní pouze element

<wtd:instance id="57734" assetid="29370" style="Ilustrační obrázek" default="yes">

a ID souboru z daného zdroje (vyjádřeno v XPath //wtd:news/wtd:instances/wtd:instance/wtd:attachments/wtd:attachment/@id). Ostatní obsah elementu <wtd:instances> a všech vnořených elementů je importem vždy ignorován.

Zakládá-li se nová zpráva, postupuje algoritmus následovně:

• Zjistí se, zda existuje zdroj s ID wtd:instance/@assetid a položka v něm s ID wtd:attachment/@id; pokud neexistují, daná instance se neimportuje
• Zjistí se, zda existuje styl wtd:instance/@style nebo druh příloh wtd:instance/@list; pokud tomu tak není, instance se neimportuje
• Pokud má nějaká instance atribut default="yes", označí se jako výchozí, ale jen v případě, že žádná výchozí již neexistuje. Pokud není ani jedna instance označená jako výchozí, bude výchozí první importovaná.

Pokud k importu instance dochází, nahrazují se v importované zprávě odpovídající ID v klíčových slovech typu WTD_I. Tj. např. pokud je v těle zprávy <!--WTD_I(62285)--> a importuje se <wtd:instance id="62285">, mění se v těle <!--WTD_I(62285)--> na <!--WTD_I(xxx)-->, kde xxx je přidělené ID založené instance. To platí např. i pro klíčová slova v poli Obrázek apod., kde mohou být tato klíčová slova ve tvaru <!--WTD_I(xxx)-->.

Pokud se aktualizuje existující zpráva, postupuje se podobně jako u nové zprávy, ale porovnávají se i ID instancí z XML (<wtd:instance id="yyy">). Tj:

• Pokud v dané zprávě instance s ID yyy existuje, pouze se aktualizuje, a to jen v případě, že kontrola zjistila, že ostatní importované parametry jsou v pořádku (tj. soubor, zdroj i styl resp. seznam příloh existují). Pokud kontrola zjistí, že nějaký parametr neodpovídá (styl neexistuje apod.), instance v databázi se ponechá a v XML se ignoruje.
• Pokud v dané zprávě instance s ID yyy neexistuje, zakládá se nová jako u existující zprávy
• Je-li nějaká instance v XML označená jako default, označí se jako výchozí i ve zprávě, ale jen v případě, že je v XML takto označena právě jedna; v opačném případě se buď ponechá výchozí z aktuálního stavu v databázi (pokud již zpráva před importem nějakou instanci má) nebo první importovaná (pokud zpráva před importem žádnou instanci neměla).

Import zdrojů

Import lze používat rovněž k importu do databáze zdrojů. Význam importu zdrojů spočívá v tom, že v nějakém systému může být množina souborů určených k použití na www serveru, importem do WebToDate lze takto naplnit databázi zdrojů, kterou pak lze při publikaci obsahu využívat.

Soubory jsou obsaženy v elementu attachments, který je potomkem elementu news. Soubory jsou zde zakódována pomocí kódování Base64, XML soubor se zdrojem vypadá např. takto:

<?xml version="1.0" encoding="UTF-8"?>
<!-- soubor k importu do verze 4.0 - zdroje -->
<wtd:collection xmlns:wtd="http://www.webtodate.cz/schemas/2.1/SimpleSchema">
	<wtd:news>
		<!-- zdroj informaci a jeho jednoznacny identifikator -->
		<wtd:origin name="jinysystem" id="az80-3532"/>
		<!-- stav importovanych zprav -->
		<wtd:status>entered</wtd:status>
		<!-- uzamceni importovanych zprav -->
		<wtd:locked>no</wtd:locked>
		<!-- o jaky typ dat jde (news - fragment - asset) -->
		<wtd:newstype>asset</wtd:newstype>
		<!-- Nadpis -->
		<wtd:title>Nadpis zdroje</wtd:title>
		<!-- popis -->
		<wtd:description><![CDATA[Popis zdroje (anotace)]]></wtd:description>
		<!-- Autor -->
		<wtd:source>Josef Novák</wtd:source>
		<!-- kategorie, do kterych se importuje -->
		<wtd:categories>
			<wtd:category name="Úvodní">
				<wtd:category name="Politika">
					<wtd:category name="Parlament" default="yes"/>
				</wtd:category>
			</wtd:category>
		</wtd:categories>
		<!-- nazev publikace -->
		<wtd:publication>Deník</wtd:publication>
		<!-- jazyk -->
		<wtd:language locale="CS">čeština</wtd:language>
		<!-- Téma -->
		<wtd:group>Domácí zprávy;Politické zprávy</wtd:group>
		<!-- Predloha -->
		<wtd:pattern>Předloha pro zdroje</wtd:pattern>
		<!-- Tym -->
		<wtd:team id="2">Domácí redakce</wtd:team>
		<!-- Uzivatel -->
		<wtd:user id="5">
			<wtd:firstname>Jiří</wtd:firstname>
			<wtd:lastname>Vopršálek</wtd:lastname>
		</wtd:user>
		<!-- klicova slova oddelena strednikem -->
		<wtd:keywords>WebToDate;zdroj;xml</wtd:keywords>
		<!-- priorita -->
		<wtd:priority>1</wtd:priority>
		<!-- datum zdroje -->
		<wtd:datenews>
			<wtd:date>2003-05-13</wtd:date>
			<wtd:time>18:30:44</wtd:time>
		</wtd:datenews>
		<!-- datum publikace -->
		<wtd:datepublished>
			<wtd:date>2003-05-13</wtd:date>
			<wtd:time>18:30:44</wtd:time>
		</wtd:datepublished>
		<!-- datum expirace -->
		<wtd:dateexpired>
			<wtd:date>2004-05-13</wtd:date>
			<wtd:time>00:30:00</wtd:time>
		</wtd:dateexpired>
		<!-- link nadpisu -->
		<wtd:url>/scripts/file.php?id=50646</wtd:url>
		<wtd:attachments>
			<wtd:attachment defaultattachment="yes">
				<wtd:filename>skromachfoto1.jpg</wtd:filename>
				<wtd:filepath>/uvodni/politika/parlament/</wtd:filepath>
				<wtd:targetlocation>public</wtd:targetlocation>
			<wtd:filetype>jpg</wtd:filetype>
				<wtd:filesize>41698</wtd:filesize>
				<wtd:filewidth>369</wtd:filewidth>
				<wtd:fileheight>271</wtd:fileheight>
				<wtd:attachmentvalue>...kód v Base64...</wtd:attachmentvalue>
			</wtd:attachment>
		</wtd:attachments>
	</wtd:news>
</wtd:collection>

Seznam elementů použitelných v elementu attachments

Následující tabulka uvádí seznam elementů používaných pod elementem attachments a jejich význam.

Element	Význam	Popis a poznámky
attachment	Element pro soubor ve zdroji	Definuje soubor ve zdroji, má atribut defaultattachment, který definuje, zda se jedná o soubor master, ostatní elementy uvedené v této tabulce jsou pak potomky tohoto elementu. Při importu se s tímto atributem zachází takto: Pokud není uveden ani u jednoho souboru, označí se jako master první Pokud je uveden víc než jednou, ponechá se nastavení master u prvního souboru u které to bylo nastaveno. Nepovažuje se to za chybu, pouze se zapíše do protokolu.
filename	Název souboru	Název souboru včetně koncovky (nikoliv cesta). Hodnota je povinná.
filepath	Cesta	Zadaná požadovaná adresářová cesta na serveru. Hodnota není povinná. Pokud není při importu uvedena, vytvoří se automaticky, jako kdyby byl soubor vkládán ručně (tedy pomocí nastavení v konstantě ASSETS_NEW_FILE_PATH), pokud je uvedena, použije se, ale jen v případě, že se jedná o validní cestu. V opačném případě se jedná o fatální chybu, celý zdroj nelze naimportovat a dál se postupuje podle nastavení continueonerror. Pokud je položka typu externí odkaz, tento element se neexportuje.
targetlocation	Cíl uložení	Hodnota je daná výčtem možností public / private / externalurl. Při exportu se exportuje vždy, při importu není povinná – není-li uvedena, dosazuje se zde hodnota podle konfigurační konstanty ASSETS_PRIVATEFILES_REGIME z konfiguračního souboru WebToDate.
attachmentvalue	Base64 kód souboru	Neexportuje se, pokud je v parametrech exportu zvoleno, že se vlastní soubory nemají exportovat, nebo v případě, že jde o položku typu externí odkaz.
fileurl	Externí URL vloženého odkazu	Pokud je položka ve zdroji typu externí odkaz, nachází se zde URL tohoto odkazu, jinak se neexportuje
filetype	Typ souboru	Udává formát souboru (koncovku souboru)
filesize	Velikost v bytech cílové stránky / dokumentu	Pokud má v databázi zdrojů nenulovou hodnotu, exportuje se. Při importu se použije, pokud se importuje položka typu externí odkaz, pokud se importuje soubor, ignoruje se (WebToDate si velikost zjistí sám).
filewidth	Šířka v obrazových bodech (jedná-li se o obrázek nebo Flash)	Pokud má v databázi zdrojů nenulovou hodnotu, exportuje se. Při importu se použije, pokud se importuje položka typu externí odkaz, pokud se importuje soubor, ignoruje se (WebToDate si rozměr zjistí sám).
fileheight	Výška v pixelech	Pokud má v databázi zdrojů nenulovou hodnotu, exportuje se. Při importu se použije, pokud se importuje položka typu externí odkaz, pokud se importuje soubor, ignoruje se (WebToDate si rozměr zjistí sám).

Pro import zdrojů platí:

• Pokud je element attachments uveden u jiného typu než <newstype>asset</newstype>, jedná se o chybu, daný element news se ignoruje a postupuje se dál podle continueonerror.
• Při aktualizaci se porovnávají již existující soubory ve zdroji a podle potřeby se buď mění, nebo ponechávají.

Položky zdrojů typu externí odkaz

Pro položky v databázi zdrojů typu externí odkaz se používá následující formát:

<?xml version="1.0" encoding="UTF-8"?>
<wtd:collection xmlns:wtd="http://www.webtodate.cz/schemas/2.0/SimpleSchema">
	<wtd:news>
		<wtd:newstype>asset</wtd:newstype>
		<wtd:title>Nadpis zdroje</wtd:title>
		<wtd:description><![CDATA[Popis zdroje (anotace)]]></wtd:description>
		<wtd:source>Josef Novák</wtd:source>
		<wtd:attachments>
			<wtd:attachment defaultattachment="yes">
				<wtd:targetlocation>externalurl</wtd:targetlocation>
				<wtd:filename>knihkup.htm</wtd:filename>
				<wtd:fileurl>http://www.portal.cz/knihkup.htm</wtd:fileurl>
				<wtd:filetype>htm</wtd:filetype>
				<wtd:filesize>18652</wtd:filesize>
				<wtd:filewidth>0</wtd:filewidth>
				<wtd:fileheight>0</wtd:fileheight>
			</wtd:attachment>
		</wtd:attachments>
	</wtd:news>
</wtd:collection>

Rozdíl v XML kódu je tedy až uvnitř elementu <wtd:attachment>, mimo tento element rozdíly oproti exportu zdrojů obsahujících běžné soubory nejsou.

Pomocí <wtd:targetlocation>externalurl</wtd:targetlocation> se vyznačuje, že jde o typ externí odkaz, v takovém případě tedy musí mít element hodnotu externalurl. Význam jednotlivých elementů je uveden v tabulce v předcházející kapitole.

Pro úspěšný import položky typu externí odkaz musí být v elementu <wtd:attachment> uvedeno minimálně

<wtd:targetlocation>externalurl</wtd:targetlocation>
<wtd:fileurl>http://www.portal.cz/knihkup.htm</wtd:fileurl>

Ostatní elementy jsou v takovém případě nepovinné.

Další pravidla pro importovaný soubor

Všechny elementy kromě nadpisu zprávy mají výchozí hodnoty pro import. Minimální data, která lze tudíž importovat, tvoří XML soubor, který obsahuje pouze nadpisy zpráv.

Při vyhodnocování toho, jaká hodnota se přiřazuje danému typu metadat se postupuje podle následujícího pořadí:

• hodnota nastavená v importovaném souboru v elementu importsettings
• hodnota nastavená v importním formuláři
• hodnota podle dat, tedy v příslušném elementu pod elementem news
• výchozí automaticky zvolená hodnota (tyto hodnoty jsou uvedeny ve výše uvedených přehledových tabulkách).

Příkladem může být to, do jaké kategorie se importovaná zpráva zařadí. Postupuje se následovně:

• Pokud je v rámci elementu importsettings v importovaných datech uveden element <wtd:category>, řadí se importovaná zpráva do kategorie zde uvedené. Je-li zde uveden název v databázi neexistující kategorie, jedná se o fatální chybu a import okamžitě končí.
• Pokud tento element v hlavičce importsettings uveden není, zjišťuje se, zda nebyla nastavená konkrétní kategorie ve formuláři pro spuštění importu (tj. volba Vybraná pro položku Kategorie).
• Pokud není kategorie nastavena v hlavičce importsettings ani v importním formuláři, načítá se podle elementu <wtd:category> u každé zprávy. V případě, že je uveden neexistující název kategorie, zpráva není importována a následující postup se řídí nastavením pro ošetření chyb – buď se pokračuje na import další zprávy, nebo celý import končí.
• Pokud není kategorie dána ani jednou z výše uvedených možností, použije se výchozí hodnota, v tomto případě tedy kategorie v databázi, která má nejnižší ID.

Co se týče nastavení parametrů importu, tak opět jediným povinným parametrem je cesta k souboru, který se importuje. Všechny ostatní parametry mají své výchozí hodnoty.

Jednoznačná identifikace importovaných zpráv

Možnost uchovávat identifikátory zdrojů dat zpráv je velmi výhodná ve chvíli, kdy chceme opakovaně importovat data z určitého zdroje a zajistit jejich automatickou aktualizaci.

Importovaná zpráva je v systému identifikovaná pomocí dvojice název zdroje dat – jednoznačný identifikátor v rámci zdroje. Pokud tedy je k dispozici např. databáze, ze které chceme importovat a která obsahuje jednoznačné číslování či jiný způsob jednoznačné identifikace každé položky, stačí zvolit název zdroje a import WebToDate si automaticky zaznamená, odkud zpráva pochází a jaký byl její jednoznačný identifikátor, při opakovaném importu pak může aktualizovat to, co se změnilo, importovat pouze nové zprávy z tohoto zdroje a původní nechat beze změny apod.

V elementech zpráv news tuto identifikaci vyznačujeme elementem

<wtd:origin name="muj_zdroj" id="az80-3532"/>

Tento element může mít dva atributy, atribut name udává název zdroje, atribut id původní identifikaci dané položky ve zdroji.

Pro hodnoty těchto atributů platí omezení:

• name – libovolný řetězec s délkou max. 40 znaků
• id – libovolný řetězec s délkou max. 100 znaků

Druhou variantou použití v importovaných datech je ta možnost, že se název zdroje zadává pouze jednou v hlavičce importsettings, v jednotlivých zprávách se pak uvádějí pouze id z daného zdroje. Název zdroje lze taktéž vyplnit v importním formuláři.

Identifikace zdroje není povinná, ale v případě jejího využití lze následně využít funkce podporující aktualizaci dat.

Volby importu pro způsob aktualizace dat jsou následující:

• Vkládat pouze nové zprávy, již importované ignorovat
• Nové zprávy přidat, existující aktualizovat (výchozí možnost)
• Všechny zprávy přidat jako nové.

Tyto možnosti jsou ovšem funkční pouze v případě, že importovaná data jsou opatřena identifikátory zdroje. V opačném případě import nerozezná, co již bylo importováno a co ne a vždy importuje všechny zprávy z daného XML souboru jako nové.

Speciální hodnotou atributu name elementu origin pro import je hodnota self. Tato hodnota vyznačuje, že data byla exportována ze stejné instalace WebToDate, jako budou importována. Pokud totiž data byla pořízena přímo ve WebToDate, nemají v tabulce pro sledování importů záznam, a tudíž není možná jejich aktualizace přes import běžným způsobem. Hodnotou self se vyznačí, že jde o tento případ a import pak aktualizuje zprávy dle ID zpráv tak, jak se v importovaném souboru vyskytují.

V administračním rozhraní modulu v nabídce Administrace / Zdroje dat je k dispozici nástroj, který umožňuje jednoduchou správu těchto zdrojů. Je zde možné:

• Zobrazit seznam zdrojů a počty zpráv, které byly z jednotlivých zdrojů importovány
• Smazat údaje o importu zpráv z daného zdroje, které již byly ze serveru smazány
• Smazat všechny údaje o importu zpráv z daného zdroje.

Pokud importovaná data nebyla opatřena identifikátorem zdroje, jsou v těchto funkcích opatřena označením neznámý zdroj.

Poznámky k exportu

Exportovat lze zprávy odpovídající danému filtru, přičemž možnosti nastavení filtru jsou téměř identické jako při běžné práci se zprávami v redakčním rozhraní. Navíc je zde možnost omezit export na kritérium Mladší než x hodin, toto kritérium se vztahuje na položku Datum aktualizace.

Co se exportuje ve smyslu, které elementy XML souboru jsou vyplněny, nelze ovlivnit jinak než následnou XSLT transformací.

Na rozdíl od importu není nutné přesně specifikovat cestu k exportovanému souboru, platná je i možnost zadat pouze exportní adresář. V tom případě se automaticky vytváření soubory s názvem ve formátu timestamp.xml, tedy např. 20040825043925.xml. Tuto možnost lze využít např. v případě, že chceme v pravidelných (např. několikahodinových) intervalech exportovat do vybraného adresáře zprávy, které byly vytvořeny či změněny v těchto posledních několika hodinách.

Pro export zpráv je k dispozici volba Nahradit instance HTML kódem. Pokud je toto zvoleno, nahrazují se v exportu ve všech polích (v těle zprávy, v poli obrázek, v polích variabilní struktury atd.) klíčová slova typu <!--WTD_I(xxx)--> identickým způsobem, jako když se zobrazuje např. detail zprávy. Pokud je tedy např. v těle text

Šokovaní instruktoři policisty okamžitě odvolali ze všech úkolů a nahlásili je vedení policie. Tamní šéf jim dal padáka. 
<!--WTD_I(62285)-->
Tvrdili, že to měl být jen vtip, že si chtěli vystřelit z instruktorů.

a WebToDate styl pro zdroje pro danou instanci je

<div class="img_cont"><div class="img_in_news">
<img src="<!--WTD_ASSET(FILEURL)-->" alt="<!--WTD_ASSET(TITLE)-->" width="<!--WTD_ASSET(FILEWIDTH)-->" height="<!--WTD_ASSET(FILEHEIGHT)-->" border="0" class="img_inn"></div>
<!--WTD_ASSET(TITLE)--><!--WTD_IF(ASSET_SOURCENOTNULL,", autor: <!--WTD_ASSET(SOURCE)-->")-->
</div>

je výsledkem exportu např. kód

Šokovaní instruktoři policisty okamžitě odvolali ze všech úkolů a nahlásili je vedení policie. Tamní šéf jim dal padáka. 
<div class="img_cont"><div class="img_in_news">
<img src="/assets/zpravy/police589.jpg" alt="Ilustrační foto - policista" width="517" height="612" border="0" class="img_inn"></div>
Ilustrační foto - policista
</div>
Tvrdili, že to měl být jen vtip, že si chtěli vystřelit z instruktorů.

Je-li navíc v nastavení exportu vyplněn Prefix pro URL souborů ze zdrojů např. hodnotou http://www.mujserver.cz, výsledek z předchozího příkladu je

Šokovaní instruktoři policisty okamžitě odvolali ze všech úkolů a nahlásili je vedení policie. Tamní šéf jim dal padáka. 
<div class="img_cont"><div class="img_in_news">
<img src="http://www.mujserver.cz/assets/zpravy/police589.jpg" alt="Ilustrační foto - policista" width="517" height="612" border="0" class="img_inn"></div>
Ilustrační foto - policista
</div>
Tvrdili, že to měl být jen vtip, že si chtěli vystřelit z instruktorů.

Administrační rozhraní

Administrace

Práva

Ve formuláři Administrace / Práva lze nastavit, které týmy mají přístup k funkcím sekce Data tohoto modulu. Členové týmu Administrátoři mají přístup k těmto funkcím vždy. Nastavení se provádí stejně jako u všech ostatních modulů WebToDate.

Zdroje dat

Funkce nemá nic společného s databází zdrojů WebToDate, jedná se o zdroj (původ) dat.

Tento formulář je přístupný pouze administrátorům a slouží k jednoduché správě zdrojů importovaných dat. Zdroje nelze přidat ručně, zakládají se automaticky při importu. V databázi se uchovávají informace jako:

• Název zdroje
• Původní identifikátor položky v daném zdroji
• ID zprávy přidělené WebToDate při importu
• Datum a čas posledního importu dané zprávy z daného zdroje.

Formulář slouží jednak k zobrazení seznamu zdrojů, které byly při importu použity, jednak k možnosti případně smazat údaje o importu ze zdroje uchovávané v databázi.

Klepnutím na název zdroje se zobrazí formulář, ve kterém je údaj o počtu zpráv, které byly z daného zdroje importovány. K dispozici jsou následující tlačítka:

• Odstranit neexistující – smaže ty záznamy o importu z daného zdroje, pro které již neexistují v databázi WebToDate zprávy.
• Odstranit všechny – smaže všechny informace o importu z daného zdroje.

V každém případě se tedy mažou jen informace o importu, nikoliv sám naimportovaný obsah. Znamená to, že vložené zprávy "zapomenou", z kterého zdroje byly importovány, a pak již nelze případně použít algoritmus na aktualizaci již importovaných zpráv.

Data

Soubory

Funkce Data / Soubory otevírá nové okno prohlížeče, ve kterém lze spravovat importované a exportované soubory. Po výchozí instalaci existují následující složky:

• /xml/export/ - složka, která se používá jako výchozí pro export XML souborů
• /xml/import/ - složka, která se používá jako výchozí pro import XML souborů

Funkce je velmi podobná funkci Obrázky z hlavní nabídky WebToDate. K dispozici jsou následující tlačítka:

• Přidat soubor – zobrazí ve spodním rámci formulář pro upload souboru na server
• Zobrazit soubor – klepnutí na soubor v horním rámci tento soubor pouze vybírá, pokud si jej chceme prohlédnout, je třeba použít toto tlačítko
• Smazat – maže vybraný soubor z adresáře serveru
• Kopírovat URL – kopíruje URL vybraného souboru do schránky

Pro ručně spouštěný export a import platí, že exportovat lze do kteréhokoliv existujícího adresáře na serveru (kam má aplikace právo zápisu), export je pouze výchozí adresář. Pro import ručně nelze importovat z jiného adresáře než je import. V úlohách pro Plánovač úloh lze volit libovolně cesty pro export i import.

Import

Funkce slouží k manuálnímu spouštění importu. V horním rámci se zobrazuje seznam souborů k importu, tedy obsah adresáře /xml/import/. Jsou zde vidět názvy souborů, jejich velikost a datum modifikace, pomocí ikony s lupou v řádku lze v novém okně prohlížeče otevřít přímo XML kód příslušného souboru. Klepnutím na název souboru se ve spodním rámci otevírá formulář pro import, kde v poli Název XML souboru je vyplněno URL souboru, na který se kleplo.

S formulářem se pracuje tak, že se zde navolí příslušné parametry importu, import se spustí, následně se zobrazí formulář ukazující proběh importu a na závěr upozornění informující o výsledku importu.

Základní údaje v tomto formuláři jsou Název XML souboru (vyplní se automaticky při vyvolání tohoto formuláře) a Formát XML dat. Pokud nejsou na server instalovány žádné transformace, zobrazí se zde pouze WebToDate XML formát, další případné položky odpovídají instalovaným transformacím. Volbu (a tedy formát) WebToDate XML formát se doporučuje používat vždy, když je to možné.

Další nastavení ovlivňují metadata importovaných zpráv, způsob zpracování a parametry z hlediska workflow (stav zpráv apod.). Tyto vlastnosti lze nastavovat globálně pro všechny importované zprávy, tedy vždy existuje volba Podle dat (tj. použít údaj v elementu news v importovaném souboru), nebo možnost vybrat jednu konkrétní hodnotu pro všechny importované zprávy.

Vždy je ovšem třeba si uvědomit, že všechna tato nastavení mají ekvivalent ve volitelné hlavičce importsettings v importovaném souboru a nastavení v této hlavičce mají přednost před volbami zadanými do formuláře.

Význam většiny těchto nastavení ve formuláři je zřejmý, je třeba zmínit pouze:

• Režim ukládání – volí se možnosti ohledně aktualizace již importovaných zpráv. Volba má smysl jen, pokud jsou data importována z pojmenovaného zdroje dat a opatřená identifikátory příslušnými ke zdroji dat. Jinak systém není schopen rozeznat, které zprávy již importoval a které ne a importuje celý soubor jako nové zprávy.
• Odkaz nadpisu – nastavení ovlivňuje vyplnění podle Odkaz nadpisu u importovaných zpráv. Pokud není jasný důvod proč toto měnit, je vhodné ponechat výchozí nastavení Podle přidělených ID. Pak bude pole nabývat korektních hodnot ve tvaru /scripts/detail.php?id=přidělené_id resp. v tom tvaru, jaký je nastaven v konfiguračním souboru WebToDate (viz referenční příručka WebToDate, kapitola o možnostech generování URL zpráv). Pokud bychom např. importovali z jiné instalace WebToDate a toto nastavení změnily, URL pro zobrazení celé zprávy by bylo ponecháno tak, jak bylo přiděleno na původním serveru, což by mělo za následek nefunkčnost zobrazování celých zpráv na veřejné části.
• Pro zprávy importovat instance - pro zprávy se mají v XML i importovat instance, viz kapitola Instance zdrojů ve zprávách.

Export

Pomocí tohoto formuláře se manuálně spouští export dané selekce z databáze zpráv.

V horní části formuláře se definuje tato selekce. Funkčnost filtru je stejná jako při běžném prohledávání zpráv při práci se zprávami WebToDate. Navíc jsou zde tři pole, pomocí kterých lze jednoduše vyfiltrovat nejnovější zprávy:

• Datum aktualizace mladší než x hodin - zadává se přirozené číslo, pokud je vyplněno, exportují se zprávy, jejichž čas aktualizace není starší než zadaný počet hodin
• Datum položky mladší než x hodin - zadává se přirozené číslo, pokud je vyplněno, exportují se zprávy, jejichž čas (pole Datum a čas ve formuláři pro zprávy) není starší než zadaný počet hodin
• Datum "Publikovat dne" mladší než x hodin - zadává se přirozené číslo, pokud je vyplněno, exportují se zprávy, jejichž čas Publikovat dne není starší než zadaný počet hodin

Zadaná kritéria se kombinují logickým "a zároveň". V poli Vybrat lze určit, že kromě (nebo namísto) zpráv se mají exportovat i fragmenty.

Volba Export zdrojů včetně souborů ovlivňuje, zda se do exportovaného XML kódu vkládají i vlastní soubory (tj. element <wtd:attachmentvalue>, kde se nachází souboru v Base64).

Tuto volbu má smysl vypnout např. v případě generování podcastu - XML kód tohoto druhu potřebuje jen odkazy na soubory, nikoli vlastní soubory. Možnost vypnutí této volby pak šetří nároky na výkon serveru - XML formát pro podcast je třeba vytvořit spuštěním odpovídající XSLT transformace, která bude provedena rychleji a s menšími nároky na paměť či výkon v případě, že vlastní soubory nebudou do XML vůbec vloženy.

Jsou k dispozici následující volby ovlivňující export informací o instancích položek z databáze zdrojů ve zprávách:

• Nahradit instance HTML kódem - pokud je zvoleno, nahrazují se ve zprávě klíčová slova typu WTD_I HTML kódem, tj. na příslušný soubor ve zdroji se aplikuje styl zvolený v instanci, výsledkem je statický HTML kód, který se dosadí do XML kódu místo klíčového slova WTD_I
• Exportovat seznam příloh - pokud je zaškrtnuto, exportuje se ve zprávě seznam všech instancí jako samostatný blok XML kódu. Je-li zároveň zvoleno Nahradit instance HTML kódem, exportují se pouze zdroje připojené k nějakému seznamu příloh, v opačném případě i zdroje připojené pod nějakým stylem.
• Prefix pro URL souborů ze zdrojů - pokud je zadáno, připojuje se před hodnotu reprezentovanou klíčovými slovy <!--WTD_ASSET(FILEURL)--> a <!--WTD_ASSET(MASTERFILEURL)-->, ale pouze v případě, že tento obsah začíná lomítkem. V exportovaném kódu pak je např. místo /assets/zpravy/zahranicni/evropa/112343.jpg absolutní URL http://www.mujserver.cz/assets/zpravy/zahranicni/evropa/112343.jpg.

Do exportovaného souboru se pro každou zprávu vždy doplňuje originální ID z daného zdroje (v tomto případě WebToDate). Pokud chceme doplnit kromě ID i název zdroje, je tento název třeba vložit do příslušného pole formuláře. Dále zde ještě můžeme zvolit, zda se bude exportovat jen vybraný typ objektu (zprávy, fragmenty, zdroje) nebo všechny. Další obsah v tom smyslu, které XML elementy v exportovaném souboru budou, nelze ovlivnit.

Důležitými volbami je opět adresa výstupního XML souboru a formát dat. Pokud nejsou na server instalovány žádné transformace, zobrazí se zde pouze WebToDate XML formát, další případné položky odpovídají instalovaným transformacím.

Po spuštění exportu se zobrazí průběh exportu a následně hlášení o ukončení exportu a stavu tohoto ukončení.

Protokoly

Všechno důležité ohledně XML exportů a importu se protokoluje. Základní informace (tedy např. zahájení a ukončení importu, počet importovaných zpráv apod.) jsou přítomny přímo v hlavním protokolu WebToDate. Kromě toho má modul svoje vlastní protokoly, které lze zobrazit pomocí funkce Data / Protokoly.

Ovládání tohoto okna je stejné jako u hlavních protokolů WebToDate. Lze zde nalézt především informace o zakládání / aktualizaci zpráv a dále podrobné popisy chyb (pokud při importu nastanou) včetně např. čísel řádků v importovaných XML souborech, na kterých nastala nějaká chyba.

Nastavení v globálních předvolbách

V konfiguračním souboru config/global.php na serveru je jedna volba týkající se XML importu, která je ve tvaru

define("ENABLE_KW_ADDING_FROM_XML_IMPORT", true);

Pokud je tato konstanta nastavená na hodnotu true (výchozí hodnota po instalaci), je povoleno přidávat do slovníku klíčových slov automaticky při importu nová klíčová slova která v tomto slovníku ještě nejsou. Pokud je tato hodnota nastavena na false, nová klíčová slova se nepřidávají.

Pro hlavičku importsettings existuje element <wtd:addnewkeywords>, který specifikuje v datech, zda nová klíčová slova přidávat či nikoliv. Platí následující pravidla:

• Pokud je tato volba v global.php nastavena na hodnotu false, je uvedení nastavení v XML souboru irelevantní a nová klíčová slova se nikdy automaticky nepřidávají.
• Pokud je tato volba v global.php nastavena na hodnotu true, bere se v potaz nastavení v XML souboru, pokud toto nastavení není v importovaném souboru přítomno, nová klíčová slova se přidávají.

Plánované úlohy

Použití plánovaných úloh

Součástí tohoto modulu jsou i dvě plánované úlohy pro export a import, pomocí kterých lze spouštět import či export buď jako součást nějaké sekvence úloh nebo v naplánovaném čase. Funkčnost je stejná jako při manuálním spouštění, interně tyto funkce využívají stejný programový kód jako manuální spouštění. S těmito plánovanými úlohami se pracuje stejně jako s jinými úlohami pro Plánovač úloh. Všechny důležité informace se protokolují stejně jako při manuálním spouštění exportu či importu.

Export

Funkci je vhodné využít, pokud periodicky exportujeme nějakou selekci z databáze zpráv do souborů. Může jit o jeden soubor s pevným názvem nebo o více souborů – pokud nevyplníme název souboru, ale jen adresář, generují se názvy souborů ve formátu timestamp.xml.

Import

Úlohu použijeme v případě, že chceme periodicky importovat z daného XML souboru (který je např. v čase měněn jinou aplikací) s použitím stejných nastavení.

Úloha má oproti možnostem importu přes interaktivní rozhraní modulu následující rozšíření:

• Pokud cesta v nastaveních úlohy v poli Název XML souboru končí lomítkem, importují se všechny soubory ze zadaného adresáře.
• Je k dispozici volba Mazat importované soubory - pokud je zvoleno a soubor je úspěšně importován, automaticky se smaže.
• Pokud je zvoleno Mazat importované soubory a při importu dojde k chybě, místo smazání souboru dojde k jeho přesunu do adresáře nastaveném v poli Chybový adresář.

Adresářová struktura

Export a import

Po výchozí instalaci existují na serveru následující složky:

• /xml/export/ - složka, která se používá jako výchozí pro export XML souborů
• /xml/import/ - složka, která se používá jako výchozí pro import XML souborů

Lze vybrat i jiné složky i podsložky, do kterých má aplikace právo na čtení resp. zápis. Výjimkou je manuální spouštění importu, kde nelze vybrat jinou složku než výchozí.

XSLT transformace

XSLT transformace, které může modul automaticky spouštět před importem nebo po exportu se na server instalují formou kopírování XSLT souboru do příslušné složky. Tyto složky jsou:

/rdata/resources/modules/xml\application/stylesheets/import/

pro transformace spouštěné před importem, resp.

/rdata/resources/modules/xml/application/stylesheets/export/

pro transformace spouštěné po exportu.

Součástí XSLT souboru musí být hned za hlavičkou <xsl:stylesheet> XML komentář ve tvaru

<!-- w2d_xslt_name: název transformace -->

Řetězec název transformace se pak použije v redakčním rozhraní pro zobrazení názvu formátu – transformace v exportních a importních formulářích.

Před kopírováním vlastních transformací na server je velmi doporučeno tyto transformace připravit a otestovat s využitím vhodného vývojového prostředí.

Vzorová XSLT transformace pro export zpráv do RSS formátu

Po instalaci je ve složce /rdata/resources/modules/xml/application/stylesheets/export/ obsažen soubor wtd38torss2.xslt.release se vzorovou transformací do RSS formátu. Aby tuto transformaci bylo možné využít, je nutné soubor přejmenovat na wtd38torss2.xslt. (odstranit příponu .release, a ponechat příponu .xslt)

Ve výsledném souboru je dále potřeba upravit obsah elementu <channel> :

- vyplnit elementy <title>, <link>, <description>, <language>, <ttl>, <managingEditor> a <webmaster>

- v elementu <link> pod elementem <item> nahradit vzorovou adresu http://wwwmujserver.cz za reálnou adresu serveru.

Tato transformace se pak bude zobrazovat jako další možný formát XML dat ve formuláři pro export.

Protokoly modulu

Protokoly exportu a importu se ukládají do adresáře /offlinedata/logs/xml/ na serveru. Jedná se o běžné textové soubory, které lze následně zpracovat v aplikacích typu MS Excel apod.