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 mx...@apache.org on 2007/10/11 16:28:48 UTC
svn commit: r583833 - in /tcl/rivet/trunk/doc: ./ examples/ html/
Author: mxmanghi
Date: Thu Oct 11 07:28:45 2007
New Revision: 583833
URL: http://svn.apache.org/viewvc?rev=583833&view=rev
Log:
docs from branch 1_0 merged into trunk
Added:
tcl/rivet/trunk/doc/examples/download.tcl
- copied unchanged from r583826, tcl/rivet/branches/1_0/doc/examples/download.tcl
tcl/rivet/trunk/doc/examples/rivet_web_service.tcl
- copied unchanged from r583826, tcl/rivet/branches/1_0/doc/examples/rivet_web_service.tcl
Modified:
tcl/rivet/trunk/doc/Makefile.in
tcl/rivet/trunk/doc/html/commands.en.html
tcl/rivet/trunk/doc/html/commands.it.html
tcl/rivet/trunk/doc/html/commands.ru.html
tcl/rivet/trunk/doc/html/dio.en.html
tcl/rivet/trunk/doc/html/diodisplay.en.html
tcl/rivet/trunk/doc/html/directives.en.html
tcl/rivet/trunk/doc/html/directives.it.html
tcl/rivet/trunk/doc/html/directives.ru.html
tcl/rivet/trunk/doc/html/examples.en.html
tcl/rivet/trunk/doc/html/examples.it.html
tcl/rivet/trunk/doc/html/examples.ru.html
tcl/rivet/trunk/doc/html/help.en.html
tcl/rivet/trunk/doc/html/help.it.html
tcl/rivet/trunk/doc/html/help.ru.html
tcl/rivet/trunk/doc/html/index.en.html
tcl/rivet/trunk/doc/html/index.it.html
tcl/rivet/trunk/doc/html/index.ru.html
tcl/rivet/trunk/doc/html/installation.en.html
tcl/rivet/trunk/doc/html/installation.it.html
tcl/rivet/trunk/doc/html/installation.ru.html
tcl/rivet/trunk/doc/html/internals.en.html
tcl/rivet/trunk/doc/html/internals.it.html
tcl/rivet/trunk/doc/html/internals.ru.html
tcl/rivet/trunk/doc/html/rivet.en.html
tcl/rivet/trunk/doc/html/rivet.it.html
tcl/rivet/trunk/doc/html/rivet.ru.html
tcl/rivet/trunk/doc/html/session_package.en.html
tcl/rivet/trunk/doc/html/tcl_packages.en.html
tcl/rivet/trunk/doc/html/tcl_packages.it.html
tcl/rivet/trunk/doc/html/tcl_packages.ru.html
tcl/rivet/trunk/doc/html/upgrading.en.html
tcl/rivet/trunk/doc/html/upgrading.it.html
tcl/rivet/trunk/doc/html/upgrading.ru.html
tcl/rivet/trunk/doc/rivet.it.xml
tcl/rivet/trunk/doc/rivet.xml
Modified: tcl/rivet/trunk/doc/Makefile.in
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/Makefile.in?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/Makefile.in (original)
+++ tcl/rivet/trunk/doc/Makefile.in Thu Oct 11 07:28:45 2007
@@ -1,8 +1,8 @@
-# Makefile.in generated by automake 1.9.4 from Makefile.am.
+# Makefile.in generated by automake 1.9.6 from Makefile.am.
# @configure_input@
# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004 Free Software Foundation, Inc.
+# 2003, 2004, 2005 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
@@ -69,7 +69,9 @@
AMDEP_FALSE = @AMDEP_FALSE@
AMDEP_TRUE = @AMDEP_TRUE@
AMTAR = @AMTAR@
-APXS = @APXS@
+APR_CPPFLAGS = @APR_CPPFLAGS@
+APR_INCLUDES = @APR_INCLUDES@
+APR_LDFLAGS = @APR_LDFLAGS@
APXS_CPPFLAGS = @APXS_CPPFLAGS@
APXS_CPPFLAGS_SHLIB = @APXS_CPPFLAGS_SHLIB@
APXS_INCLUDES = @APXS_INCLUDES@
@@ -112,14 +114,13 @@
EXEEXT = @EXEEXT@
F77 = @F77@
FFLAGS = @FFLAGS@
+GREP = @GREP@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
LDFLAGS = @LDFLAGS@
-LDFLAGS_DEBUG = @LDFLAGS_DEBUG@
LDFLAGS_DEFAULT = @LDFLAGS_DEFAULT@
-LDFLAGS_OPTIMIZE = @LDFLAGS_OPTIMIZE@
LD_LIBRARY_PATH_VAR = @LD_LIBRARY_PATH_VAR@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
@@ -146,20 +147,18 @@
PKG_INCLUDES = @PKG_INCLUDES@
PKG_LIBS = @PKG_LIBS@
PKG_LIB_FILE = @PKG_LIB_FILE@
-PKG_OBJECTS = @PKG_OBJECTS@
-PKG_SOURCES = @PKG_SOURCES@
PKG_STUB_LIB_FILE = @PKG_STUB_LIB_FILE@
PKG_STUB_OBJECTS = @PKG_STUB_OBJECTS@
PKG_STUB_SOURCES = @PKG_STUB_SOURCES@
PKG_TCL_SOURCES = @PKG_TCL_SOURCES@
RANLIB = @RANLIB@
RANLIB_STUB = @RANLIB_STUB@
+RIVET_BASE_INCLUDE = @RIVET_BASE_INCLUDE@
SET_MAKE = @SET_MAKE@
SHARED_BUILD = @SHARED_BUILD@
SHELL = @SHELL@
SHLIB_CFLAGS = @SHLIB_CFLAGS@
SHLIB_LD = @SHLIB_LD@
-SHLIB_LD_FLAGS = @SHLIB_LD_FLAGS@
SHLIB_LD_LIBS = @SHLIB_LD_LIBS@
STLIB_LD = @STLIB_LD@
STRIP = @STRIP@
@@ -183,12 +182,9 @@
TCL_THREADS = @TCL_THREADS@
TCL_VERSION = @TCL_VERSION@
VERSION = @VERSION@
-ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_CXX = @ac_ct_CXX@
ac_ct_F77 = @ac_ct_F77@
-ac_ct_RANLIB = @ac_ct_RANLIB@
-ac_ct_STRIP = @ac_ct_STRIP@
am__fastdepCC_FALSE = @am__fastdepCC_FALSE@
am__fastdepCC_TRUE = @am__fastdepCC_TRUE@
am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@
@@ -198,6 +194,8 @@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
+apache_include = @apache_include@
+apache_version_dir = @apache_version_dir@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
@@ -205,27 +203,36 @@
build_os = @build_os@
build_vendor = @build_vendor@
datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
+htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
+localedir = @localedir@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
+psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
+with_apr_config = @with_apr_config@
+with_apxs = @with_apxs@
all: all-am
.SUFFIXES:
Modified: tcl/rivet/trunk/doc/html/commands.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/commands.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/commands.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/commands.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/commands.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/commands.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/dio.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/dio.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/diodisplay.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/diodisplay.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/directives.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/directives.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/directives.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/directives.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/directives.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/directives.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/examples.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/examples.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/examples.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/examples.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/examples.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/examples.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/help.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/help.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/help.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/help.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/help.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/help.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/index.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/index.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/index.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/index.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/index.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/index.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/installation.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/installation.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/installation.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/installation.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/installation.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/installation.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/internals.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/internals.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/internals.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/internals.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/internals.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/internals.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/rivet.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/rivet.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/rivet.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/rivet.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/rivet.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/rivet.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/session_package.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/session_package.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/tcl_packages.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/tcl_packages.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/tcl_packages.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/tcl_packages.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/tcl_packages.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/tcl_packages.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/upgrading.en.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/upgrading.en.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/upgrading.it.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/upgrading.it.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/html/upgrading.ru.html
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/html/upgrading.ru.html?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
Binary files - no diff available.
Modified: tcl/rivet/trunk/doc/rivet.it.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/rivet.it.xml?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/rivet.it.xml (original)
+++ tcl/rivet/trunk/doc/rivet.it.xml Thu Oct 11 07:28:45 2007
@@ -8,6 +8,8 @@
<!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" >
+ <!ENTITY rivet_web_service.tcl SYSTEM "examples/rivet_web_service.tcl" >
]>
<!--
@@ -697,6 +699,7 @@
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>
<cmdsynopsis>
@@ -713,6 +716,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 +1110,210 @@
<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>
+ <example id="ajax_xml_messaging">
+ <title>Messagi XML e Ajax</title>
+ <para>
+ Il comando <command>headers</command> è fondamentale
+ per generare messaggi in formato XML che devono essere compresi
+ dal codice JavaScript usato in applicazioni Ajax.
+ </para>
+ <para>
+ Ajax è una tecnica di <quote>web programming</quote> che usa
+ intensamente la capacità di JavaScript (e di altri
+ linguaggi di scripting come VBScript) di manipolare dinamicamente
+ la struttura HTML di una pagina. Nei browser moderni il codice
+ JavaScript può inviare richieste http POST e GET verso
+ il webserver. Queste richieste posso chiedere al webserver di
+ lanciare script (per esempio script Tcl basati su Rivet) che,
+ a loro volta, costruiscono risposte che vengono inviate al
+ browser. JavaScript solitamente usa un handler che gestisce
+ in modo asincrono la comunicazione. Quando un messaggio di
+ risposta viene ricevuto l'handler elabora il contenuto della
+ risposta e modifica il contenuto della pagina corrente con
+ i nuovi dati. Ajax aiuta a sviluppare applicazioni web più
+ pronte e flessibili: invece di passare attraverso il ciclo
+ di richiesta-generazione-trasferimento di un pagina, Ajax
+ permette al programmatore di richiedere e trasmettere solo
+ i dati essenziali, contribuendo così a soddisfare il
+ generale requisito della separazione tra dati e interfaccia
+ utente (risparmiando altresì al server di inviare
+ lo stesso codice html and gli stessi elementi grafici ogni
+ volta che i dati di una pagina vengono aggiornati).
+ </para>
+ <para>
+ Nelle applicazioni Ajax la comunicazione tra client e server viene
+ controllata da una istanza di una classe specializzata che, nel
+ mondo non-IE si chiama XMLHttpRequest, mentre per il mondo IE
+ si chiama ActiveXObject. Attraverso un istanza di questa classe
+ una richiesta tipo GET o POST viene inviata e il server risponde
+ con un messaggio che viene immagazzinato come stringa nella
+ proprietà <command>returnedText</command> dell'instanza
+ di XMLHttpRequest. Nonostante questo canale di comunicazione
+ non implichi affatto che la comunicazione su di esso si effettui
+ con un protocollo specifico, è diventato ampiamente
+ comune sfruttare XML come linguaggio per questi messaggi. Un
+ certo numero di specificazioni di protocollo basate su XML vengono
+ usate per queste applicazioni, tra queste SOAP e XML-RPC (l'ultima
+ è una raccomandazione del consorzio W3C. Comunque sia
+ voi potete inventare anche il vostro protocollo (basato su XML, ma
+ anche in altro formato). E' utile tuttavia sapere che se gli
+ headers http sono opportunamente specificati e se il messaggio
+ di ritorno è scritto in XML <quote>well formed</quote>, allora
+ anche la proprietà
+ <ulink url="http://www.w3schools.com/ajax/ajax_responsexml.asp">
+ XMLResponse</ulink> di XMLHttpRequest viene definita con una
+ con un oggetto che è un'istanza di una classe che
+ possiede i metodi e le proprietà dell'
+ <ulink url="http://www.w3schools.com/dom/default.asp">
+ XML W3C DOM</ulink>, permettendo al codice JavaScript di manipolare
+ i dati contenuti nel messaggio con questo modello di DOM.
+ </para>
+ <para>
+ In questo esempio uno script Rivet inizializza un array con
+ i dati essenziali riguardanti alcuni dei maggiori compositori
+ della musica europea. Questo array ha il ruolo di un database
+ che, in una caso reale, può contenere grosse tabelle
+ con migliaia di righe, le quali possono avere dati più
+ completi ed estesi. Lo script è ideato per inviare al
+ client 2 tipi di risposte: un <quote>catalogo</quote> dei
+ compositori oppure un recordo singolo con le informazioni di
+ un compositore
+ </para>
+ <programlisting>&rivet_web_service.tcl;</programlisting>
+ <para>
+ Per brevità il JavaScript e l'HTML non verranno riportati
+ qui. Possono essere scaricati (assieme allo script Tcl) nell'archivio
+ <ulink url="http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz">
+ rivet-ajax.tar.gz</ulink> archive. Semplicemente
+ aprendo questo archivio in una directory accessibile dal vostro
+ server Apache e puntando con un browser alla pagina rivetService.html
+ dovreste essere in grado di far girare l'esempio. Ogni volta
+ che scegliete il nome di un compositore una nuova query viene
+ inviata e registrata nel log di apache, anche se la pagina html
+ non viene mai ricaricata, ma solo aggiornata con i nuovi dati.
+ </para>
</example>
-
</section>
<section id="tcl_packages">
Modified: tcl/rivet/trunk/doc/rivet.xml
URL: http://svn.apache.org/viewvc/tcl/rivet/trunk/doc/rivet.xml?rev=583833&r1=583832&r2=583833&view=diff
==============================================================================
--- tcl/rivet/trunk/doc/rivet.xml (original)
+++ tcl/rivet/trunk/doc/rivet.xml Thu Oct 11 07:28:45 2007
@@ -8,6 +8,8 @@
<!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" >
+ <!ENTITY rivet_web_service.tcl SYSTEM "examples/rivet_web_service.tcl" >
]>
<!--
@@ -585,7 +587,6 @@
<section id="commands">
<title>Rivet Tcl Commands and Variables</title>
-
<refentry>
<refnamediv>
<refname>var</refname>
@@ -596,9 +597,7 @@
<refsynopsisdiv>
<cmdsynopsis>
- <command>
- var
- </command>
+ <command>var</command>
<group choice="req">
<arg>get</arg>
<arg>list</arg>
@@ -609,9 +608,7 @@
</cmdsynopsis>
<cmdsynopsis>
- <command>
- var_qs
- </command>
+ <command>var_qs</command>
<group choice="req">
<arg>get</arg>
<arg>list</arg>
@@ -622,9 +619,7 @@
</cmdsynopsis>
<cmdsynopsis>
- <command>
- var_post
- </command>
+ <command>var_post</command>
<group choice="req">
<arg>get</arg>
<arg>list</arg>
@@ -633,8 +628,6 @@
<arg>all</arg>
</group>
</cmdsynopsis>
-
-
</refsynopsisdiv>
<refsect1>
@@ -769,8 +762,8 @@
<title>Description</title>
<para>The upload command is for file upload manipulation.
See the relevant Apache Directives to further configure the
- behavior of this Rivet feature.</para>
-
+ behavior of this Rivet feature.
+ </para>
<variablelist>
<varlistentry>
@@ -828,6 +821,23 @@
<term>
<cmdsynopsis>
<command>upload</command>
+ <arg choice="plain">exists</arg>
+ <arg><replaceable>uploadname</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Returns true if an upload named <arg>uploadname</arg>
+ exists. This can be used in scripts that are meant to
+ be run by different forms that send over uploads that
+ might need specific processing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <cmdsynopsis>
+ <command>upload</command>
<arg choice="plain">size</arg>
<arg><replaceable>uploadname</replaceable></arg>
</cmdsynopsis>
@@ -885,8 +895,6 @@
<para>
See <xref linkend="upload"/>.
</para>
-
-
</refsect1>
</refentry>
@@ -1010,7 +1018,6 @@
</refsect1>
</refentry>
-
<refentry>
<refnamediv>
<refname>include</refname>
@@ -1490,7 +1497,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,
@@ -1583,18 +1589,191 @@
<example id="upload">
<title>File Upload</title>
<para>
- The following HTML in one file, say,
- <filename>upload.html</filename>
+ The <command>upload</command> command endows Rivet with an
+ interface to access files transferred over http as parts of a
+ multipart form. The following HTML in one file, say,
+ <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 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
+ to do so would result in the client sending only the file's
+ path, rather than the actual contents.
</para>
<programlisting>&upload.html;</programlisting>
<para>
- Can be used with the following Tcl code, in a second file
- (<filename>upload.rvt</filename> for instance)
- in order to create a file upload form.
+ In the script invoked by the form
+ (<filename>upload.rvt</filename>) <command>upload</command>
+ <arg>argument ...</arg> commands can be used to manipulate the
+ various files uploaded.
</para>
<programlisting>&upload.rvt;</programlisting>
+ <para>
+ Don't forget that the apache server must have write access to
+ the directory where files are being created. The Rivet Apache
+ directives have a substantial impact on the upload process,
+ you have to carefully read the docs in order to set the
+ appropriate directives values that would match your
+ requirements.
+ </para>
+ <para>
+ It is also important to understand that some
+ <command>upload</command> commands are effective only when
+ used in a mutually exclusive way. Apache stores the data in
+ temporary files which are read by the <command>upload save
+ <arg>upload name</arg><arg>filename</arg> </command> or by the
+ <command>upload data <arg>upload name</arg> </command>
+ command. Subsequent calls to these 2 commands using the same
+ <arg>upload name</arg> argument will return no data on the
+ second call. Likewise <command>upload channel <arg>upload
+ name</arg></command> will return a Tcl file channel that you
+ can use in regular Tcl scripts only if you haven't already
+ read the data, for example with a call to the <command>upload
+ 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 needed. 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 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 the browser's window. When the browser
+ hasn't a valid builtin method or plugin registered for the
+ file's content the typical download dialog pops up asking
+ for directions from the user.
+ </para>
+ <para>
+ Rivet can help if you have more sofisticated needs. For
+ instance you may be developing an application that uses
+ webpages to collect input data that have to be
+ passed on to scripts or programs. In this case the content
+ is generated on demand and a real file representing the
+ data doesn't exist on the server. 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 URI to the file in their bookmarks.
+ Your scripts may expunge from the pages
+ every link to the file (your pages are dynamic, 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.
+ 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 sets the
+ <constant>Content-Type</constant>,
+ <constant>Content-Disposition</constant>,
+ <constant>Content-Description</constant> and
+ <constant>Content-Length</constant> headers to inform
+ the client about the file type, name and size. Notice that in
+ order to set the <constant>Content-Type</constant> 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>
+ <example id="ajax_xml_messaging">
+ <title>XML Messages and Ajax</title>
+ <para>
+ The <command>headers</command> command is crucial for generating
+ XML messages that have to be understood by JavaScript code used
+ in Ajax applications.
+ </para>
+ <para>
+ Ajax is a web programming technique that heavily relies on the
+ abilty of JavaScript (and other scriping languages like VBScript) to
+ manipulate dynamically the HTML structure of a page. In modern browsers
+ JavaScript code is enabled to send GET or POST requests to the webserver.
+ These requests can ask the server to run scripts (for example Rivet
+ Tcl scripts) that build responses and send them back to the browser.
+ JavaScript code reads asynchronously these responses, elaborates
+ their content and accordingly modifies the page on display.
+ Ajax helps to build web applications that are more responsive and
+ flexible. Instead of going through the cycle of request-generation-transfer
+ of a page, Ajax allows the programmer to request and transmit only
+ the essential data thus matching the general requirement of separation
+ between data and user interface (and saving the server from sending over
+ the same html code and graphics every time a page is refreshed)
+ </para>
+ <para>
+ In Ajax applications the communication between client and server
+ is controlled by an instance of a specialized object: the non-IE world
+ uses the XMLHttpRequest class to create it,
+ whereas IE uses the ActiveXObject class. Through an instance of
+ that class a POST or GET request is sent to the server, which in turn
+ responds with a message that is stored as a string in a property of the
+ communication object called 'returnedText'.
+ Although this sort of communication channel doesn't imply that the messages
+ being transmitted through it have a specific protocol, it's become widely
+ customary to use XML as the format for such messages. A number
+ of XML specification are being used for this, among which XML-RPC and
+ SOAP are worth to be quoted. Anyway, you can invent your own protocol
+ (either based on XML or anything else), but one has to be aware of the fact
+ that if the http headers are properly set and the message returned
+ to the client is a well formed XML fragment, also the property
+ <ulink url="http://www.w3schools.com/ajax/ajax_responsexml.asp">
+ XMLResponse</ulink> is set with a reference to an object
+ that stores the response as an XML document. This object is an
+ instance of a class that implements the
+ <ulink url="http://www.w3schools.com/dom/default.asp">
+ XML W3C DOM</ulink> tree methods and properties, thus
+ enabling the scripts to read and manipulate the data embedded in
+ the XML message with a structured and standard interface.
+ </para>
+ <para>
+ In this example a Rivet script initializes an array with the
+ essential data regarding a few of the major composers of the
+ european music. This array plays the role of a database
+ which, in a real case, might store large tables with thousands
+ records and more complete and extended information.
+ The script is designed to send back to the client two
+ types of responses: a catalog of the composers or a single
+ record of a composer.
+ </para>
+ <programlisting>&rivet_web_service.tcl;</programlisting>
+ <para>
+ For sake of brevity the JavaScript and HTML will not listed here.
+ They can be downloaded (along with the Tcl script) stored in the
+ <ulink url="http://people.apache.org/~mxmanghi/rivet-ajax.tar.gz">
+ rivet-ajax.tar.gz</ulink> archive. By simply
+ opening this tar archive in a directory accessible by your
+ apache server and pointing your browser to the rivetService.html
+ page you should see a page with a drop-down list. Every time
+ a different name is picked from the list a new query is sent and
+ logged in the apache access.log file, even though the html
+ is never reloaded.
+ </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