Doc: Added QtWebKit examples from Qt Quarterly 26 and 32.

3 files changed, 674 insertions, 0 deletions

diff --git a/doc/src/examples/simplewebplugin.qdoc b/doc/src/examples/simplewebplugin.qdoc
new file mode 100644
index 0000000..9093b9b
--- /dev/null
+++ b/doc/src/examples/simplewebplugin.qdoc
@@ -0,0 +1,181 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example webkit/simplewebplugin
+    \title Simple Web Plugin Example
+
+    The Simple Web Plugin example shows how to embed a regular Qt widget into a
+    Web page displayed using QWebView.
+
+    \image webkit-simplewebplugin.png A table widget embedded in a Web page.
+
+    In this example, we will show how to include Qt widgets in Web-centric user
+    interfaces.
+
+    \section1 QtWebKit Basics
+
+    QtWebKit provides integration between Qt and WebKit on two different levels.
+    On a low level, Qt provides widgets for Web pages to be rendered onto; on a
+    high level, a set of classes are provided that represent all the key
+    components of a Web browser.
+
+    QWebView is a widget that is used to display Web pages, QWebPage represents
+    the content in a page, and QWebFrame represents an individual frame in a
+    Web page. The code to display a Web page is very simple:
+
+    \snippet webkitsnippets/simple/main.cpp Using QWebView
+
+    The widget provides fundamental Web browsing features, such as Cascading
+    Style Sheet and JavaScript support. Other technologies can be added to
+    provide a more comprehensive experience.
+
+    \section1 Adding a Widget to a Page
+
+    Since Qt is used to render pages, it is easy to add both standard and
+    custom widgets to pages. All we need is some markup to indicate where a
+    widget is expected in a page and a mechanism that lets us know when it
+    needs to be created.
+
+    The markup used involves the \c <object> element, described in the HTML 4
+    specification, which is used to include generic objects in Web pages. When
+    describing an object to represent a widget, there are typically three
+    attributes this element can have: a \c data attribute that indicates where
+    any relevant data can be obtained; \c width and \c height attributes can
+    be used to set the size of the widget on the page.
+
+    Here's how we might describe such an object:
+
+    \snippet examples/webkit/simplewebplugin/pages/index.html embedded object
+
+    The mechanism used by QtWebKit to insert widgets into pages is a plugin
+    factory that is registered with a given WebPage instance. Factories are
+    subclasses of QWebPluginFactory and can be equipped to supply more than one
+    type of widget.
+
+    \section1 Creating a Widget to Embed
+
+    To demonstrate how the factory is used, we create a simple widget that can
+    be used to display Comma-Separated Values (CSV) files. The widget class,
+    \c CSVView, is just a subclass of QTableView with extra functions to set
+    up an internal data model. Instances of the factory class, \c CSVFactory,
+    are responsible for creating \c CSVView widgets and requesting data on
+    their behalf.
+
+    The \c CSVFactory class is defined in the following way:
+
+    \snippet examples/webkit/simplewebplugin/csvfactory.h plugin factory
+
+    The public functions give a good overview of how QtWebKit will use the
+    factory to create widgets. We begin by looking at the factory's constructor:
+
+    \snippet examples/webkit/simplewebplugin/csvfactory.cpp constructor
+
+    The factory contains a network access manager which we will use to obtain
+    data for each of the plugin widgets created.
+
+    The \c plugins() function is used to report information
+    about the kinds of widget plugins it can create; our implementation reports
+    the MIME type it expects and provides a description of the plugin:
+
+    \snippet examples/webkit/simplewebplugin/csvfactory.cpp plugins
+
+    The \c create() function is where most of the action happens. It is
+    called with a MIME type that describes the kind of data to be displayed,
+    a URL that refers to the data, and information about any additional
+    arguments that were specified in the Web page. We begin by checking the
+    basic MIME type information passed in the \c mimeType parameter, and only
+    continue if we recognize it.
+
+    \snippet examples/webkit/simplewebplugin/csvfactory.cpp begin create
+
+    We construct a view widget
+    using the fully-specified MIME type, which is guaranteed to be in the list of
+    arguments if a MIME type has been supplied.
+
+    \snippet examples/webkit/simplewebplugin/csvfactory.cpp submit request
+
+    Lastly, we use the network access manager to request the data specified by
+    the \c url parameter, connecting its \c finished() signal to the view's
+    \c updateModel() slot so that it can collect the data. The reply object is
+    intentionally created on the heap; the \c finished() signal is connected to
+    its \c deleteLater() slot, ensuring that Qt will dispose of it when it is no
+    longer needed.
+
+    The \c CSVView class provides only minor extensions to the functionality of
+    QTableView, with a public slot to handle incoming data and a private
+    variable to record exact MIME type information:
+
+    \snippet examples/webkit/simplewebplugin/csvview.h definition
+
+    The constructor is simply used to record the MIME type of the data:
+
+    \snippet examples/webkit/simplewebplugin/csvview.cpp constructor
+
+    To save space, we will only look at parts of the \c updateModel() function,
+    which begins by obtaining the QNetworkReply object that caused the slot
+    to be invoked before checking for errors:
+
+    \snippet examples/webkit/simplewebplugin/csvview.cpp update model begin
+
+    Assuming that the data is correct, we need to determine whether the
+    CSV file includes a table header, and to find out which character encoding was
+    used to store the data. Both these pieces of information may be included in
+    the complete MIME type information, so we parse this before continuing---this
+    is shown in the online example code.
+
+    \snippet examples/webkit/simplewebplugin/csvview.cpp read data begin
+
+    Since QNetworkReply is a QIODevice subclass, the reply can be read
+    using a suitably configured text stream, and the data fed into a standard
+    model. The mechanics of this can be found in the
+    \l{webkit/simplewebplugin/csvview.cpp}{code listing}. Here, we skip to the
+    end of the function where we close the reply object and set the model on
+    the view:
+
+    \snippet examples/webkit/simplewebplugin/csvview.cpp update model
+
+    Once the reply has been read, and the model populated with data, very little
+    needs to be done by the plugin. Ownership of the view widget is handled
+    elsewhere, and we have ensured that the model will be destroyed when it is
+    no longer needed by making it a child object of the view.
+
+    Let's look quickly at the \c MainWindow implementation:
+
+    \snippet examples/webkit/simplewebplugin/mainwindow.cpp constructor
+
+    Apart from creating and setting a factory on the QWebPage object, the
+    most important task is to enable Web plugins. If this global setting is not
+    enabled, plugins will not be used and our \c <object> elements will simply
+    be ignored.
+
+    \section1 Further Reading
+
+    The \l{Web Plugin Example} extends this example by adding a signal-slot
+    connection between the embedded widget and a JavaScript function in the
+    page.
+*/
diff --git a/doc/src/examples/webftpclient.qdoc b/doc/src/examples/webftpclient.qdoc
new file mode 100644
index 0000000..156dedd
--- /dev/null
+++ b/doc/src/examples/webftpclient.qdoc
@@ -0,0 +1,336 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example webkit/webftpclient
+    \title Web FTP Client Example
+
+    The Web FTP Client example shows how to add support for a new protocol
+    to QtWebKit-based applications.
+
+    \image webkit-webftpclient.png An FTP client displaying the contents of the ftp.qt.nokia.com site.
+
+    \section1 Introduction
+
+    The QtWebKit module presents many ways to integrate the worlds of native
+    desktop and mobile applications and the Web, making it possible for
+    developers to extend and combine features found in Qt and WebKit to create
+    new ones. In this article, we examine the use of Qt's network access API
+    with WebKit and show how to turn QWebView into a simple FTP client.
+
+    In the \l{Web Plugin Example}, we extended Qt's WebKit integration by
+    showing how to add custom widgets to Web pages. In the article, we used
+    QNetworkRequest to ask for content for display in a widget, and we obtained
+    the data returned by the server by reading from the corresponding
+    QNetworkReply.
+
+    Qt's network access API is a technology that aims to replace much, but not
+    all, of the functionality provided by the QHttp and QFtp classes.
+    Although the network access API is a Qt-specific technology, the QtWebKit
+    module integrates this Qt technology with WebKit to enable customization of
+    the browser engine by Qt application developers. It also means that we can
+    control how the browser engine obtains and renders content.
+
+    Since QNetworkRequest and QNetworkReply are designed to provide a reusable
+    abstraction for network operations, it seems obvious to use these classes
+    to add FTP support to browsers written using QtWebKit. To do this, we first
+    need to examine the network access classes before we see how the QtWebKit
+    module uses them to manage network operations.
+
+    \section1 Network Access
+
+    The central class in Qt's network access API is QNetworkAccessManager.
+    This class performs the work of dispatching requests to remote servers and
+    handling incoming replies. Applications typically construct an instance of
+    this class and use it for all high level network communication.
+
+    Applications create QNetworkRequest objects, each of them specifying a URL
+    where the request is to be sent and containing meta-data that will be
+    understood by the server. Each request is dispatched by passing it to a
+    function in the network manager \mdash there are different functions
+    corresponding to different kinds of operations, such as
+    \l{QNetworkAccessManager::}{get()}, \l{QNetworkAccessManager::}{put()} and
+    \l{QNetworkAccessManager::}{post()}. Each of these functions returns a
+    QNetworkReply object which is used to obtain the content sent in the reply,
+    as well as any meta-data that describes it.
+
+    The QtWebKit module provides the QWebPage class which represents the
+    content displayed in a QWebView widget. Behind the scenes, this class uses
+    a default network access manager to handle network communication. This
+    default manager works perfectly well for fetching content over HTTP from
+    \tt{http://} URLs, but only supports fetching of files over FTP when using
+    \tt{ftp://} URLs.
+
+    Fortunately, QWebPage provides the \l{QWebPage::}{setNetworkAccessManager()}
+    function that allows the default manager to be replaced with one with more
+    features. This lets us add improved support for FTP quite easily if we can
+    write a new manager that supports \tt{ftp://} URLs.
+
+    The process of replacing the manager and using a new one with an existing
+    QWebPage object can be broken up into three steps:
+
+    \list 1
+    \o Creating a new QNetworkAccessManager subclass.
+    \o Creating a new QNetworkReply subclass to deal with the FTP protocol.
+    \o Setting the new manager on the QWebPage.
+    \endlist
+
+    Additionally, to provide a reasonable user experience, we should also handle
+    content that the browser engine cannot display. To do this, we create a
+    custom \c{Downloader} object. We will briefly return to this topic later.
+
+    \section1 Creating a New Network Manager
+
+    Replacing an existing network manager for a QWebPage is conceptually simple:
+    we subclass QNetworkAccessManager and reimplement its
+    \l{QNetworkAccessManager::}{createRequest()} function to check for URLs
+    with the \tt{ftp} scheme. However, we want to ensure that the manager uses
+    any existing cache and proxy settings that may have been set up for the
+    existing manager used by the QWebPage.
+
+    To keep the existing proxy and cache, we give our network manager a
+    constructor that accepts the old manager as an argument. In the constructor,
+    we reuse the settings from the old manager.
+
+    \snippet examples/webkit/webftpclient/networkaccessmanager.cpp constructor
+
+    The \c{createRequest()} function is used to create and dispatch requests to
+    remote servers for each of the different kinds of operation that the API
+    presents to the developer. Since we are only interested in performing simple
+    fetches of resources using the \tt{ftp} scheme, we filter out other schemes
+    and other kinds of operation, delegating the task of handling these to the
+    default implementation.
+
+    \snippet examples/webkit/webftpclient/networkaccessmanager.cpp create request
+
+    Here, we construct and return an instance of the \c FtpReply class. This
+    class performs most of the work of handling the FTP protocol.
+
+    \section1 Creating a Custom Reply
+
+    The network access API is designed to be simple to use: we set up a request,
+    dispatch it using the network manager, and obtain a QNetworkReply object.
+    If we are not interested in the reply's meta-data, we can simply read the
+    data using its \l{QNetworkReply::}{readAll()} function because QNetworkReply
+    is a QIODevice subclass.
+
+    In order to keep the API so simple, however, we need to perform some work
+    behind the scenes. In this case, that means that we must perform a series of
+    communications with the FTP server. Fortunately, we can use the existing
+    implementation provided by QFtp to perform the low level work.
+
+    In the \c FtpReply class, we need to reimplement four functions in the
+    QIODevice API to ensure that it will work correctly. These functions,
+    \l{QIODevice::}{abort()}, \l{QIODevice::}{bytesAvailable()},
+    \l{QIODevice::}{isSequential()}, \l{QIODevice::}{readData()},
+    rely on the rest of the implementation to fill a QByteArray with data and
+    use an integer offset to track how much has been read from the device by
+    the browser.
+
+    \snippet examples/webkit/webftpclient/ftpreply.h class definition
+
+    The \c{processCommand()}, \c{processListInfo} and \c{processData()} slots
+    handle interaction with the FTP server. The private \c{setContent()} and
+    \c{setListContent()} functions are used to add meta-data to the reply and
+    compose HTML for the browser to display.
+
+    Two of the private variables hold information about the data obtained from
+    the FTP server: \c items is updated to contain information about each
+    file found at a given URL, and \c content contains the raw data obtained
+    from the server. The \c offset variable is used to track how much data has
+    been read by the browser from the reply.
+
+    In the constructor, we construct a QFtp object and connect the signals and
+    slots that form the basis of the interaction with the FTP server. The high
+    level communication is reported by the \l{QFtp::}{commandFinished()}
+    signal. New data from the server is reported by the
+    \l{QFtp::}readyRead()} signal.
+    Individual items in an FTP directory listing are reported by the
+    \l{QFtp::}{listInfo()} signal.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp constructor
+
+    We also initialize the \c offset into the data that represents the number
+    of bytes that the browser has read from the reply. Additionally, we define
+    a list of units for use with the \c setListContent() function.
+    The last two tasks performed in the constructor are to set the URL of the
+    reply so that the browser can tell where it came from, and to connect to
+    the FTP server.
+
+    \section2 Fetching Data from the Server
+
+    All communication with the server is handled by the \c processCommand()
+    slot, which acts on responses from the server and tells us when a command
+    we have issued has completed.
+    This slot performs the task of logging in to the server when connection has
+    occurred (the \l{QFtp::}{ConnectToHost} command has completed), asking for
+    a list of files when logged in (\l{QFtp::}{Login} has completed),
+    preparing a page with a listing when all file information has been received
+    (\l{QFtp::}{List} has completed), and setting the current content for the
+    reply when data has been fetched from the server
+    (\l{QFtp::}{Get} has completed).
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp process command
+
+    The result of the \l{QFtp::}{List} command is handled by looking at the
+    number of items obtained from the server.
+    The items themselves are recorded by the \c processListInfo() slot. When a
+    \l{QFtp::}{List} command is complete, we can count the number of items
+    received and determine whether or not we should create a file listing, or
+    try to fetch the file instead by invoking a \l{QFtp::}{Get} command.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp process list info
+
+    Since the reply will only be used once, we can simply append items to a list
+    and never bother to clear it.
+
+    The \c processData() slot simply appends data obtained from the FTP server
+    to the QByteArray containing the content to be supplied to the browser.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp process data
+
+    Data is appended to the \c content array until the connection to the FTP
+    server is closed, either by the reply or by the server itself. One of the
+    ways in which this happens is when a \l{QFtp::}{Get} command completes. At
+    this point, the \c setContent() function is called from within the
+    \c processCommand() function.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp set content
+
+    Here, we prepare the reply for use by the browser by opening it for
+    unbuffered reading and setting the header that reports the amount of data
+    held by the reply. We emit signals that indicate that the network operation
+    has finished and that it has data to be read. Since we are no longer
+    interested in the FTP server, we close the connection to it.
+
+    \section2 Preparing Content for the Reader
+
+    Another way in which the reply closes the connection to the server is when
+    the \c setListContent() function is called from the \c processCommand()
+    function. Most of the implementation of this function involves transforming
+    the information about the items held in the reply's private \c items
+    variable to HTML.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp set list content
+
+    Once the HTML description of the files has been composed in a QString, we
+    convert it to a UTF-8 encoded set of bytes which we store in the reply's
+    private \c content variable. In this case, the QByteArray holds HTML
+    instead of file data. We set the reply's headers to indicate that it
+    contains UTF-8 encoded HTML with a certain length, and we emit the
+    \l{QNetworkReply::}{readyRead()} and \l{QNetworkReply::}{finished()}
+    signals to let the browser know that it can start reading the content.
+
+    \section2 Supplying Data to the Browser
+
+    We reimplement four QIODevice functions to provide basic read-only behavior,
+    simply supplying the data held in the \c content array.
+
+    We do not support aborting of the reply, so our \c abort() implementation
+    is empty.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp abort
+
+    Similarly, we do not support random access reading, so \c isSequential()
+    is reimplemented to always return true.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp is sequential
+
+    The \c bytesAvailable() function returns the total number of bytes held by
+    the reply minus the value of \c offset, which is the number of bytes we
+    have already supplied to the reader.
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp bytes available
+
+    \snippet examples/webkit/webftpclient/ftpreply.cpp read data
+
+    The \c readData() reimplementation tries to return as much data to the
+    reader as it will allow, copying bytes directly to the appropriate location
+    in memory. The \c offset variable is updated to keep track of how many
+    bytes have been read.
+
+    \section1 Enabling the Protocol
+
+    Now that we have an FTP-enabled network manager and a reply that can handle
+    communication with FTP servers, we can now enable the manager for a given
+    QWebPage.
+    We derive the \c FtpView class from QWebView and configure its behavior in
+    its constructor.
+
+    As we mentioned earlier, we pass the original network manager to the
+    newly-created manager and pass the new manager to the QWebPage belonging to
+    the browser. This enables our network manager for the content it displays.
+
+    \snippet examples/webkit/webftpclient/ftpview.cpp constructor
+
+    We also go to some effort to handle content that WebKit does not natively
+    support, using a \c Downloader helper class to manage this and files that
+    the user downloads via the browser's \gui{Save Link...} context menu entry.
+
+    In the example's \c main() function, we perform the usual steps to
+    initialize our Qt application. We choose an appropriate starting URL for
+    the \c FtpView widget to open before running the application's event loop.
+
+    \snippet examples/webkit/webftpclient/main.cpp main
+
+    \section1 Summary
+
+    As we have seen, enabling support for another protocol and URL scheme in
+    QtWebKit is a fairly simple process involving the creation of a network
+    manager and custom reply object. The implementation challenges
+    are mostly related to how the protocol is handled by the custom
+    QNetworkReply subclass where, in our case, we need to issue the appropriate
+    commands in the correct order to obtain data from the FTP server.
+
+    We also need to ensure that that the reply emits the appropriate signals to
+    inform the browser that it has content to be read. Our implementation is
+    intentionally simple, only notifying the browser with the
+    \l{QIODevice::}{readyRead()} signal when \e all the content is ready to
+    read and emitting the \l{QNetworkReply::}{finished()} signal to indicate
+    that communication is complete; a more sophisticated approach would
+    interleave the commands sent to the server with the emission of signals,
+    allowing the browser to read content as data is obtained from the FTP
+    server.
+
+    The reply also needs to be open for reading. Forgetting to call the
+    \l{QIODevice::}{open()} function is a common error to make when dealing
+    with devices, but in this case it is the reply's responsibility to open
+    itself.
+    It must indicate how much content it has for the browser to read. As we
+    have seen, this is done by setting the reply's
+    \l{QNetworkRequest::}{ContentLengthHeader} header with the appropriate
+    value. With this information available, the browser can read from the reply
+    when the content becomes available, displaying a directory listing or
+    downloading content depending on the type of data supplied.
+
+    We can use the approach described in this article to enable support for
+    other protocols by writing or extending a network manager to handle URL
+    schemes such as \tt mailto, \tt sip, \tt news, \tt file and \tt ldap.
+    Applications that integrate Web content with information from other sources
+    can also provide custom URL schemes as long as care is taken not to use an
+    existing public scheme.
+*/
diff --git a/doc/src/examples/webplugin.qdoc b/doc/src/examples/webplugin.qdoc
new file mode 100644
index 0000000..0410670
--- /dev/null
+++ b/doc/src/examples/webplugin.qdoc
@@ -0,0 +1,157 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example webkit/webplugin
+    \title Web Plugin Example
+
+    The Web Plugin example shows how to communicate between a Qt widget
+    embedded in a Web page and the page itself.
+
+    \image webkit-webplugin.png A table widget embedded in a Web page.
+
+    In this example, we will take the widget described in the
+    \l{Simple Web Plugin Example} and show how to set up communications between
+    the widget and the Web environment.
+
+    \section1 Setting up Communications
+
+    There are two ways of interacting with the content in a Web page. The first
+    way involves the use of QWebElement to read and modify the page
+    content and structure; this is useful for certain types of application, as
+    demonstrated by the \l{DOM Traversal Example} and the
+    \l{Simple Selector Example}.
+
+    The second way is to add Qt objects to the page, connecting their signals
+    to JavaScript functions, and executing the object's slots directly from
+    JavaScript in the page. We explore this approach in this example.
+
+    To perform this communication, we require an updated \c CSVView widget from
+    the \l{Simple Web Plugin Example} that can emit a signal whenever a row is
+    selected, a JavaScript function to modify elements on the page, and some
+    glue code to make the connection.
+
+    On the page, the plugin is declared like this:
+
+    \snippet examples/webkit/webplugin/pages/index.html embedded object
+
+    As in the previous example, the \c <object> definition includes information
+    about the data to be displayed, its location, and the dimensions of the
+    plugin in the page.
+
+    Later in the document, we include a table that we will update with data
+    from the \c CSVView widget:
+
+    \snippet examples/webkit/webplugin/pages/index.html table
+
+    The \c CSVView widget is similar to the previous version. However, we
+    wish to obtain and export individual rows of data, so we define the
+    \c rowSelected() signal and \c exportRow() slot to perform this task.
+
+    \snippet examples/webkit/webplugin/csvview.h definition
+
+    Since we wish to obtain one row of data at a time, the constructor includes
+    code to restrict how the user can interact with the view:
+
+    \snippet examples/webkit/simplewebplugin/csvview.cpp constructor
+
+    The \c exportRow() slot provides a convenient mechanism for obtaining and
+    emitting the values found on the current row of the table:
+
+    \snippet examples/webkit/webplugin/csvview.cpp export row
+
+    This slot is connected to a signal belonging to the view's selection model:
+    \l{QItemSelectionModel::}{currentChanged()}. This can be seen by examining
+    the \c updateModel() function in the source code.
+
+    \c exportRow() emits the \c rowSelected() signal, passing strings containing
+    the name, address and quantity in the current table row. To see how this
+    data is passed to the Web page, we need to look at the \c CSVFactory class.
+
+    \section1 Connecting Components Together
+
+    In the \c CSVFactory class, we reimplement the \l{QWebPluginFactory::}{create()}
+    function to create instances of the \c CSVView class, as in the previous
+    example.
+
+    \snippet examples/webkit/webplugin/csvfactory.cpp begin create
+
+    We also expose the view widget to the frame in the page that
+    contains the elements, and set up a connection between the view and a
+    JavaScript function defined in the page header:
+
+    \snippet examples/webkit/webplugin/csvfactory.cpp create connection
+
+    The view is added to the Web page as \c view, and the connection code we
+    evaluate performs a signal-slot connection from the view's \c rowSelected()
+    signal to a pure JavaScript function:
+
+    \js
+    view.rowSelected.connect(fillInTable);
+    \endjs
+
+    \c fillInTable is the name of the JavaScript function to modify the
+    form's input elements. This function expects three arguments: the name,
+    address and quantity values for a row of data.
+
+    Whenever the current row changes in the \c view object, the \c exportRow()
+    slot is called, the data found in the selected row is extracted from the
+    model and emitted in the \c rowSelected() signal as three strings, and
+    the above connection ensures that \c fillInTable() will be called with the
+    current items of data. The appropriate type conversions occur behind the
+    scenes to ensure that each QString is converted to a JavaScript string
+    object.
+
+    The rest of the function is the same as in the previous example:
+
+    \snippet examples/webkit/webplugin/csvfactory.cpp submit request
+
+    We now give the JavaScript \c fillInForm() function to show what it does
+    with the strings it is given. The function itself is defined in the HTML
+    page header:
+
+    \snippet examples/webkit/webplugin/pages/index.html script
+
+    We obtain the elements in the page that we wish to update by using the HTML
+    Document Object Model (DOM) API. The values of these elements are updated
+    with the \c name, \c address and \c quantity strings supplied.
+
+    \section1 Linking Things Together
+
+    Although we have used the widgets to demonstrate the use of signals and
+    slots for communication between Qt components and JavaScript in the browser,
+    we do not need to embed widgets in Web pages to be able to do this. By
+    inserting objects into pages and evaluating JavaScript, Qt applications can
+    be made to examine and process information found online.
+
+    One additional improvement that can be made to this example is to create
+    a relation between the embedded widget and the table to be updated. We
+    could do this by including \c <param> elements within the \c <object>
+    element that refers to the table cells by their \c id attributes. This
+    would help us to avoid hard-coding the \c customers_name,
+    \c customers_address and \c customers_quantity identifiers in the script.
+*/