flexideo

Požadavek save-files

Uložení více souborů.

Požadavek pro ukládání seznamů souborů soborů s textem, XML či HTML obsahem, jejich příp. ZIP komprimace či převod do PDF do dostupných složek serveru.

Uzel specifikující vlastnosti uložení souboru.

Základní typ(y) uzlu(ů): save-file;

Jde o uzel obsahující text

syntax 
<request>
<save-files
path="{string}"
name="{string}"
codepage="acp|utf8|utf16|{#no}"
file-type="txt|xml|pdf|base64|hex"
content-prefix="{string}"
not-replace="{boolean}"
pdf-source="text|xml"
title="{string}"
jsdelay="{string}"
attach="{boolean}"
zip="{boolean}"
zipped-file="{string}"
>
<file ... {string}</file> *
</save-files>
</request>

Atributy

path - podsložka - Volitelná podsložka nebo odkaz na virtuální složku, relativní cesta ke složce cílového souboru (bez jeho názvu); nenpovinná a není-li uvedena, použije se přednastavené uložiště.(typ: string)

name - Název ukládaného, tedy cílového souboru v konvenci *.*; Při vobě attach se ze jména používá pouze přípona. - popis neuveden(typ: string) TYP HODNOTY: string;

codepage - Určuje výstupní kódovou stránku pro ukládání obsahu do souboru;(typ: string)

TYP HODNOTY: string;

Možnosti obsahu:

» acp ~ výchozí hodnota - ActualCodePage - využití nastavení defaultní kódové stránky serveru, soubor je ukládán v aktuálním kódování;

» utf8 ~ obsah souboru bude uložen v kódování UTF-8; neplatí pro hex a base64 kódování;

» utf16 ~ obsah souboru bude uložen v kódování UTF-16; neplatí pro hex a base64 kódování;

» {#no} ~ uložení v kódování určeném číslem kódové stránky;

file-type - Typ souboru - Typ ukládaného souboru. Určuje způsob nakládání s daty, zejména převod escape sekvencí, ale také nabízí převod HTML obsahu do PDF souboru nastavením typu na hodnotu pdf; výchozí hodnotou při neuvedení je text.(typ: string)

TYP HODNOTY: string;

Možnosti obsahu:

» txt ~ Výchozí hodnota při neuvedení. Indikuje textový obsah určený k běžnému uložení do textového souboru.

» xml ~ Indikuje parsovaný xml obsah (nikoli serializovaný do textu s využitím escape seqvencí) určený k uložení do XML souboru.

» pdf ~ Toto nastavení říká, že se jedná o HTML určené ke konverzi do PDF (výchozí txt)

» base64 ~ Obsah uzlu je kódovaný v base64 sekvenci tisknutelných znaků a při uložení dojde k dekódování do původní, většinou binární struktury.

» hex ~ Obsah uzlu je kódovaný v hexadecimálním kódu tisknutelných znaků a při uložení dojde k dekódování do původní, většinou binární struktury.

content-prefix - Předřadit - Obsah atributu je vložen před samotná ukládaná data (na jejich začátek), může obsahovat například parsovací instrukce pro XML (tedy <?xml version='1.0' encoding='utf-8'?>) nebo názvy sloupců pro CSV, je-li to třeba apod.(typ: string) TYP HODNOTY: string;

not-replace - Udává, zda má soubor v případě existence původního tento nahradit, u volby attach je bezpředmětné. - popis neuveden(typ: boolean) TYP HODNOTY: boolean;

pdf-source - Zdroj pdf - Určuje, zda je zdrojem pro PDF text nebo XML; výchozí je text, který je tak při převodu na PDF chápán jako kompletní HTML stránka; Jako výchozí při neuvedení je použita volba text.(typ: string) TYP HODNOTY: string; (možnosti obsahu: text | xml)

title - Cílový název - Využíváno pouze při převodu na pdf a obsahuje titulek, tedy název cílového souboru(typ: string) TYP HODNOTY: string;

jsdelay - Čekání před převodem - Využíváno pouze při převodu na pdf, určuje, jak dlouho před převodem čekat na provedení JavaScriptu uvnitř HTML.(typ: string) TYP HODNOTY: string;

attach - Jako přílohu - Speciální možnost, která nahrazuje atribut path a je-li uvedena hodnota true, pak je soubor uložen mezi soubory čekající na přiložení k dokumentu; odpověď pak obsahuje i finální umístění v atributu path (vč. přiděleného jména souboru) a stačí, aby tentýž uživatel, který soubor dal uložit tuto vrácenou cestu použil v některém požadavku save-document, aby byl soubor použit jako příloha takto uloženého dokumentu (přípustné pouze pro uzel <save-files> a <save-file>, nikoli <file>).(typ: boolean) TYP HODNOTY: boolean;

zip - Zazipovat - Určuje, zda se jedná o ZIP archiv (soubor), mění další chovaní požadavku - aktivuje komprimaci seznamu ukládaných souborů do jediného výsledného ZIP souboru (ukládá se vždy jen do jednoho zip archívu); při nepoužítí této volby (nebo obsahuje-li false) jsou ukládány samostatné soubory (přípustné pouze pro uzel <save-files> a <save-file>, nikoli <file>);(typ: boolean) TYP HODNOTY: boolean;

zipped-file - Jméno zipu - Speciální možnost, která nahrazuje atribut path a je-li uvedena hodnota true, pak je soubor uložen mezi soubory čekající na přiložení k dokumentu; odpověď pak obsahuje i finální umístění v atributu path (vč. přiděleného jména souboru) a stačí, aby tentýž uživatel, který soubor dal uložit tuto vrácenou cestu použil v některém požadavku save-document, aby byl soubor použit jako příloha takto uloženého dokumentu;(typ: string) TYP HODNOTY: string;


Potomci


Uzel file

Popis uzlu file, který je potomkem uzlu save-files je umístěn v popisu typových uzlů.

Uzel reprezentující jeden soubor pro uložení v seznamu souborů save-files.

Uzel specifikující vlastnosti uložení souboru.

Bližší popis viz. file v popisu typu save-file.


Odpověď

Struktura odpovědi na požadavek save-files vrácená v obálce response:

syntax 
<response>
<save-files
type="ok|error"
count="{number}"
>
<file ... /> *
<error ... /> ?
</save-files>
</response>

Atributy

type - Obsahuje hodnoty ok nebo error (možnosti obsahu: ok | error)

count - Počet souborů - popis neuveden(typ: number) TYP HODNOTY: number;


Potomci


Uzel file

Popisuje výsledek, původní a nové jméno a také cestu jednoho uloženého souboru.

Informace o výsledku uložení dat do souboru.

Základní typ(y) uzlu(ů): save-file-result;

syntax 
<file
path="{string}"
type="ok|error"
name="{string}"
orig-name="{string}"
>
<error ... /> ?
</file>

Popis obsahu elementu file viz. popis typu save-file-result.


Uzel error

Popis uzlu error, který je potomkem uzlu save-files je umístěn v popisu typových uzlů.

Bližší popis viz. error.

Výraz pro identifikaci chyb v odpovědi serveru: save-files[@type='error'] (odkaz na popis detailu: @descr).


Další info

Požadavek pro ukládání jednoho nebo více souborů textových, HTML či XML souborů, s možností jejich zabalení do ZIPu či převodu do PDF a to do dostupných složek serveru. Tyto jsou pak dostupné pro běžné stahování nebo je rovněž možné využít párový požadavek load-files.

V uzlu save-files je uváděn kompletni seznam atributu jako v potomcích file. Díky tomu je umožněno dědění atributů, takže stejná nastavení platná pro všechny potomky file je praktičtější zapisovat do hlavního uzlu. U potomků jsou pak nastavovány pouze odlišnosti. Uvedení určitého atributu v uzlu file má pro daný soubor v seznamu vyšší váhu a je použit na místo případně přednastavenéhou atributu u rodiče. Takže jsou-li všechny soubory např. stejného typu, je možné uvést atribut pouze v rodičovském tagu. Bude-li se pak jeden typ lišit je možné jej specifikovat dodatečně u potomka s tímto odlišným obsahem.

Jednotlivé uzly file se chovají transakčně, tj. jsou buď uloženy všechny soubory nebo žádný. Při chybě u jednoho z ukládaných souborů jsou ostatní, již případně uložené soubory opět odebrány.

Pokud je v atributech file-type nebo pdf-source uvedena hodnota text, pak se provádí nahrazení escape sekvencí platných pro xml, tedy sekvence znaků &gt;, &lt;, &amp; apod. jsou nahrazeny za znaky >, <, & atd.. V případě uvedení typu xml v jednom z uvedených atributů je prováděna také jedna speciální náhrada a sice sekvence znaků #>## je nahrazena za &gt; !


Převod do PDF

Je-li typ výstupního souboru nastaven pomocí atributu file-type na hodnotu pdf, je prováděna konverze textového obsahu na PDF soubor. Tento textový obsah má v takovém přpadě obsahovat platné html. Je-li pak atribut pdf-source nastaven na xml, pak se předpokládá, že obsahem souboru je platné xhtml nebo také html5 a je s ním nakládáno jako s validním xml.

V rámci html mohou být i odkazy na obrázky, které se do pdf zařadí. Je však nutné, aby tyto odkazy byly absolutní z hlediska webového sídla zadaného pomocí běžných lomítek, jak je zvykem v URL odkazech, tedy např. /images/obrazek.png.

Při identifikaci problému při ukládání textového/xml souboru požadavkem save-files opět hraje klíčovou roli atribut type:

<save-files type="error" [count="n"] [orig-name=""] descr=""/>


Umístění path

Pro ukládání souborů je na serveru vyhrazena složka, kam mohou být soubory ukládány. Nastavení path pak umožňuje toto místo dále dělit na podsložky v jedné či několika úrovních. To, kde je složka pro umístění souborů fyzicky umístěna a její dostupnost závisí na nastavení konfiguračního souboru serveru. Zpravidla to bývá mimo webové sídlo, což je vzhledem k povaze ukládaných věcí a vzhledem k různým přístupovým právům k databázi výrazně doporučováno (více viz. nastavení složek serveru).

Požadavek využívá povolení save-file u virtuálních adresářů. Pro tyto účely rovněž používá oprávnění uživatele mapované pod "p_pubsaves";

Požadavek save-filePožadavek save-filesPožadavek load-files