You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rivet-dev@tcl.apache.org by da...@apache.org on 2007/04/26 12:50:40 UTC
svn commit: r532699 - in /tcl/rivet/branches/1_0: ChangeLog doc/download.tcl
doc/rivet.it.xml doc/rivet.xml
Author: davidw
Date: Thu Apr 26 03:50:39 2007
New Revision: 532699
URL: http://svn.apache.org/viewvc?view=rev&rev=532699
Log:
* doc/download.tcl: Example from Massimo Manghi.
* doc/rivet.xml, doc/rivet.it.xml: Information about generating files
to send out.
Added:
tcl/rivet/branches/1_0/doc/download.tcl
Modified:
tcl/rivet/branches/1_0/ChangeLog
tcl/rivet/branches/1_0/doc/rivet.it.xml
tcl/rivet/branches/1_0/doc/rivet.xml
Modified: tcl/rivet/branches/1_0/ChangeLog
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/1_0/ChangeLog?view=diff&rev=532699&r1=532698&r2=532699
==============================================================================
--- tcl/rivet/branches/1_0/ChangeLog (original)
+++ tcl/rivet/branches/1_0/ChangeLog Thu Apr 26 03:50:39 2007
@@ -1,3 +1,10 @@
+2007-04-26 David N. Welton <da...@dedasys.com>
+
+ * doc/download.tcl: Example from Massimo Manghi.
+
+ * doc/rivet.xml, doc/rivet.it.xml: Information about generating
+ files to send out.
+
2006-10-05 David N. Welton <da...@dedasys.com>
* rivet/packages/dio/dio_Oracle.tcl: Backported from trunk.
Added: tcl/rivet/branches/1_0/doc/download.tcl
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/1_0/doc/download.tcl?view=auto&rev=532699
==============================================================================
--- tcl/rivet/branches/1_0/doc/download.tcl (added)
+++ tcl/rivet/branches/1_0/doc/download.tcl Thu Apr 26 03:50:39 2007
@@ -0,0 +1,45 @@
+# Code example for the transmission of a pdf file.
+
+if {[var exists pdfname]} {
+ set pdfname [var get pdfname]
+
+# let's build the full path to the pdf file. The 'pdf_repository'
+# directory must be readable by the apache children
+
+ set pdf_full_path [file join $pdf_repository ${pdfname}.pdf]
+ if {[file exists $pdf_full_path]} {
+
+# Before the file is sent we inform the client about the file type and
+# file name. The client can be proposed a filename different from the
+# original one. In this case, this is the point where a new file name
+# must be generated.
+
+ headers type "application/pdf"
+ headers add Content-Disposition "attachment; filename=${pdfname}.pdf"
+ headers add Content-Description "PDF Document"
+
+# The pdf is read and stored in a Tcl variable. The file handle is
+# configured for a binary read: we are just shipping raw data to a
+# client. The following 4 lines of code can be replaced by any code
+# that is able to retrieve the data to be sent from any data source
+# (e.g. database, external program, other Tcl code)
+
+ set paper [open $pdf_full_path r]
+ fconfigure $paper -translation binary
+ set pdf [read $paper]
+ close $paper
+
+# Now we got the data: let's tell the client how many bytes we are
+# about to send (useful for the download progress bar of a dialog box)
+
+ headers add Content-Length [string length $pdf]
+
+# Let's send the actual file content
+
+ puts $pdf
+ } else {
+ source pdf_not_found_error.rvt
+ }
+} else {
+ source parameter_not_defined_error.rvt
+}
Modified: tcl/rivet/branches/1_0/doc/rivet.it.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/1_0/doc/rivet.it.xml?view=diff&rev=532699&r1=532698&r2=532699
==============================================================================
--- tcl/rivet/branches/1_0/doc/rivet.it.xml (original)
+++ tcl/rivet/branches/1_0/doc/rivet.it.xml Thu Apr 26 03:50:39 2007
@@ -8,6 +8,7 @@
<!ENTITY vars.rvt SYSTEM "examples/vars.rvt" >
<!ENTITY upload.html SYSTEM "examples/upload.html" >
<!ENTITY upload.rvt SYSTEM "examples/upload.rvt" >
+ <!ENTITY download.tcl SYSTEM "examples/download.tcl" >
]>
<!--
@@ -697,6 +698,7 @@
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
@@ -713,6 +715,25 @@
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <arg>exists</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Restituisce 1 se esiste un upload chiamato
+ <arg>uploadname</arg>. Questo comando può essere utile
+ negli script che si vuole usare nell'elaborazione di
+ più pagine che inviano upload differenti che quindi
+ necessitano di elaborazione specifica.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
@@ -1088,18 +1109,127 @@
<example id="upload">
<title>Caricare file</title>
<para>
- Il seguente HTML in un file, detto,
- <filename>upload.html</filename>
+ Il comando <command>upload</command> fornisce a Rivet la
+ possibilità di accedere ai file trasferiti tramite http come
+ parti di una form "multipart". Per esempio il seguente
+ frammento HTML (<filename>upload.html</filename>)
</para>
<programlisting>&upload.html;</programlisting>
<para>
- Può essere usato con il seguente codice Tcl in un secondo file
- (<filename>upload.rvt</filename> per esempio) per creare una
- form che carica un file.
+ crea una form con una text input entry associata ad un bottone
+ per l'esplorazione del file system locale.
+ Cliccando sul bottone appare un file browser con
+ il quale l'utente può scegliere il file da inviare (nella
+ text input entry apparirà il path al file scelto).
+ Per essere certi di inviare
+ il contentuto del file è necessario combinare l'azione degli
+ attributi enctype e method nel tag <form...> nel modo
+ specificato nell'esempio. Se non viene fatto la form invierà la
+ definizione del path del file, non il suo contenuto.
+ </para>
+ <para>
+ Nello script invocato nell'azione della form (<filename>upload.rvt</filename>)
+ i comandi <command>upload</command> <arg>argument ...</arg> possono
+ essere usati per manipolare i file inviati al webserver
</para>
<programlisting>&upload.rvt;</programlisting>
+ <para>
+ Non dimenticate che il server Apache deve aver accesso
+ in scrittura nella directory specificata per l'upload. Le
+ direttive di configurazione di Rivet per
+ per l'upload hanno un impatto considerevole sul funzionamento
+ del meccanismo di upload. Controllate la parte della documentazione
+ relativa a queste direttive in modo da scegliere i valori
+ che meglio soddisfano le vostre necessità.
+ </para>
+ <para>
+ E' anche importante capire che alcuni comandi <command>upload</command>
+ sono effettivi se usati in modo mutuamente esclusivo. Apache
+ memorizza i dati in file temporanei che vengono letti da comandi come
+ <command>upload save <arg>upload name</arg><arg>filename</arg></command>
+ oppure <command>upload data <arg>upload name</arg></command>.
+ Due chiamate successive che si riferiscono allo stesso upload
+ ritornerebbero un file vuoto alla seconda chiamata perchè la prima
+ consumerebbe i dati presenti.
+ In modo analogo la chiamata <command>upload channel <arg>upload name</arg>
+ </command> ritorna un canale Tcl al file (che può essere usato
+ in funzioni Tcl ordinarie di accesso ai file) solo se non avete già
+ letto o salvato i dati usando rispettivamente <command>upload data
+ <arg>upload name</arg></command> o <command>upload save
+ <arg>filename</arg></command>
+ </para>
+ </example>
+ <example id="file_download">
+ <title>File Download</title>
+ <para>
+ In generale mettere un file nelle condizioni di essere scaricato
+ con http è facile quanto stabilire la URI del file stesso
+ e lasciare che i meccanismi di download standard di Apache
+ facciano quello che è necessario. Se un simile approccio
+ è adeguato al vostro progetto non c'è altro da
+ fare che posizionare i vostri file destinati al download in una
+ directory all'interno dell'albero definito dalla DocumentRoot (o
+ in una qualsiasi delle directory che potete configurare con
+ il parametro Alias di Apache o con un Virtual Host)
+ </para>
+ <para>
+ Quando un client invia una uri per scaricare un certo file Apache
+ determina il tipo di contenuto sulla base dell'estensione
+ del file, invia gli header necessari ad informare il client
+ e quindi invia il contenuto stesso del file. Se il client è
+ un browser in grado di rappresentare il
+ contenuto del file questo apparirà all'utente nella finestra
+ del browser stesso. Diversamente, se il browser non ha
+ metodi "builtin" o dei plugin registrati per quel tipo di file,
+ apparirà la tipica finestra di download che chiede istruzioni
+ all'utente.
+ </para>
+ <para>
+ Rivet è però di aiuto nel caso abbiato esigenze più sofisticate.
+ Immaginate per esempio di sviluppare un applicazione web based
+ che raccogliere informazioni di input da passare a programmi
+ esterni o altre procedure Tcl che generano il contenuto di
+ un file a richiesta. In questi casi il file stesso non esiste
+ e non è possibile definire per esso una URI. In altre
+ circostanze il vostro file esiste, ma potreste aver bisogno
+ di inibirne dinamicamente il download
+ e nasconderlo dal web, non solo per i nuovi visitatori del sito,
+ ma anche per quelli che potrebbero aver salvato nei loro bookmarks
+ un riferimento a quel file. Naturalmente potreste eliminare dalle
+ vostre pagine ogni riferimento a quella risorsa (le vostre pagine
+ sono generate dinamicamente, non è vero?) e constestualmente
+ spostare il file in una directory inaccessibile, ma sembra una
+ soluzione tortuosa e poco elegante.
+ </para>
+ <para>
+ Mettere Tcl e Rivet nella condizione di controllare completamente il
+ processo di download aiuta a costruire meccanismi di download
+ più eleganti e sicuri
+ </para>
+ <para>
+ Ecco un esempio di una procedura Tcl che valuta una richiesta
+ di download di un file PDF sulla base del valore di un parametro
+ passato dal client. Il parametro è il nome (senza estensione)
+ del file pdf da scaricare. I file pdf sono tenuti in una
+ directory definita dalla variabile <command>pdf_repository</command>
+ </para>
+ <programlisting>&download.tcl;</programlisting>
+ <para>
+ Prima che il file PDF venga inviato la procedura usa gli header
+ Content-Type, Content-Disposition, Content-Description e Content-Length
+ in modo da informare il client su tipo di file, il nome (proposto)
+ e la sua dimensione. Notate che per impostare il Content-Type Rivet
+ usa una forma specializzata del comando <command>headers</command>.
+ Gli header devono essere inviati prima che i dati siano spediti verso
+ il canale di output. Fare confusione in questo schema causa un errore
+ poichè in quel caso il protocollo stesso viene violato.
+ </para>
+ <para>
+ Altre informazioni sul significato dei "mime headers" nel contesto
+ del protocoll http posso venir trovati alla pagina
+ <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"/>
+ </para>
</example>
-
</section>
<section id="tcl_packages">
Modified: tcl/rivet/branches/1_0/doc/rivet.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/branches/1_0/doc/rivet.xml?view=diff&rev=532699&r1=532698&r2=532699
==============================================================================
--- tcl/rivet/branches/1_0/doc/rivet.xml (original)
+++ tcl/rivet/branches/1_0/doc/rivet.xml Thu Apr 26 03:50:39 2007
@@ -8,6 +8,7 @@
<!ENTITY vars.rvt SYSTEM "examples/vars.rvt" >
<!ENTITY upload.html SYSTEM "examples/upload.html" >
<!ENTITY upload.rvt SYSTEM "examples/upload.rvt" >
+ <!ENTITY download.tcl SYSTEM "examples/download.tcl" >
]>
<!--
@@ -1507,7 +1508,6 @@
<section id="examples">
<title>Examples and Usage</title>
-
<para>
Some examples of Rivet usage follow. Some prior Tcl knowledge
is assumed. If you don't know much Tcl, don't worry, it's easy,
@@ -1606,7 +1606,7 @@
<filename>upload.html</filename> creates a form with a text
input entry. By clicking the file chooser button the file
browser shows up and the user selects the file to be uploaded
- (the file path will appear in the text input). In order make
+ (the file path will appear in the text input). In order to make
sure you're uploading the whole file you must combine the
action of the enctype and method attributes of the
<form...> tag in the way shown in the example. Failure
@@ -1645,7 +1645,73 @@
data <arg>upload name</arg></command> command.
</para>
</example>
-
+ <example id="file_download">
+ <title>File Download</title>
+ <para>
+ In general setting up a data file to be sent over http is as
+ easy as determining the file's URI and letting Apache's
+ standard download mechanism do all that is neeed. If this
+ approach fits your design all you have to do is to keep the
+ downloadable files somewhere within Apache's DocumentRoot (or
+ in any of the directories that you can configure and register
+ using the Alias definitions or the Virtual Hosts mechanism).
+ </para>
+ <para>
+ When a client sends a request for a file's uri Apache takes
+ care of determining the filetype, sends appropriate headers to
+ the client and then the file content. If the client is a
+ browser capable of displaying the content of the file a
+ representation is shown in browser's window. When the browser
+ hasn't a valid builtin method or plugin registered for the
+ file's content type it pops the typical download dialog asking
+ for directions from the user.
+ </para>
+ <para>
+ Rivet can help if you have more sofisticated needs too. For
+ instance you may be developing an application that uses
+ webpages as user interface that collects input parameters and
+ passes them on to scripts or programs that generate the file
+ content on demand. In these cases the file itself doesn't
+ exists on the server and a URI cannot be defined. In other
+ circumstances you may need to dynamically inhibit the download
+ of a specific file and hide it away, even to those clients
+ that might have already saved the file's URI to the file in
+ their bookmarks. Your scripts may expunge from the pages
+ every reference to the file (your pages are dynamical, aren't
+ they?) and move the file out of way, but it looks like a
+ cumbersome solution.
+ </para>
+ <para>
+ Putting Tcl and Rivet in charge of the whole download
+ mechanism helps in building cleaner and safer approaches to
+ the download problem.
+ </para>
+ <para>
+ In this example a procedure checks for the existence of a
+ parameter passed in by the browser. The parameter is the name
+ (without extension) of a pdf file name that has to be
+ downloaded. Pdf files are stored in a directory whose path is
+ in the <command>pdf_repository</command> variable.
+ </para>
+ <programlisting>&download.tcl;</programlisting>
+ <para>
+ Before the pdf is sent the procedure uses the
+ <constant>Content-Type</constant>, Content-Disposition,
+ <constant>Content-Description</constant> and
+ <constant>Content-Length</constant> headers in order to inform
+ the client about the file type, name and size. Notice that in
+ order to set the Content-Type header Rivet uses a specialiezed
+ form of the <command>headers</command> command. Headers must
+ be sent before data gets sent down the output channel. Messing
+ with this prescription causes an error to be raised (in fact
+ the protocol itself is been violated)
+ </para>
+ <para>
+ More information about the meaning of the mime headers in the
+ http context can be found at <ulink
+ url="http://www.w3.org/Protocols/rfc2616/rfc2616.html"/>
+ </para>
+ </example>
</section>
<section id="tcl_packages">
---------------------------------------------------------------------
To unsubscribe, e-mail: rivet-cvs-unsubscribe@tcl.apache.org
For additional commands, e-mail: rivet-cvs-help@tcl.apache.org