documentation improvements, oauth feature example

Doxyfile

@@ -31,7 +31,7 @@ PROJECT_NAME           = Wt
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 3.2.0
+PROJECT_NUMBER         = 3.2.1
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 

doc/main

@@ -3,29 +3,37 @@ namespace Wt {
 
 /*!
 
-  \mainpage Wt documentation.
+  \mainpage %Wt documentation.
 
-   <a href="http://www.webtoolkit.eu/wt/">%Wt</a> is a C++ library for
+   <a href="http://www.webtoolkit.eu/wt">%Wt</a> is a C++ library for
    developing web applications.
 
-   This is a reference manual which has been generated from
-   the source code.
-
    For learning web application programming with %Wt, we recommend
    reading the <a href="../../tutorial/wt.html"> hands-on introduction
    to %Wt</a>, which includes a complete tutorial (reworked in
    December 2011).
-
+
+   This is a reference manual which has been generated from the source code,
+   which we aim to be thorough and complete. There are a number of starting
+   points we recommend for specific information:
+
    In addition, there is also:
    - \ref overview - Overview of the main %Wt components (recommended!).
-   - \ref InstallationUnix - How to build %Wt and your applications on Unix-like systems.
-   - \ref InstallationWindows - How to build %Wt and your applications on Microsoft Windows systems.
+   - \ref InstallationUnix - How to build %Wt and your applications
+     on Unix-like systems.
+   - \ref InstallationWindows - How to build %Wt and your applications on
+     Microsoft Windows systems.
    - \ref Releasenotes - Release notes.
    - \ref ext - Using %Ext widgets, widgets based on ExtJS.
-   - \ref example - A line-by-line explanation, mainly shows how to achieve client-side event handling in C++.
-   - <a href="../../tutorial/dbo.html">Tutorial for Dbo</a> - %Wt's C++ ORM library.
+   - \ref example - A line-by-line explanation, mainly shows how to implement
+      client-side event handling in C++ (a parodox!).
+   - <a href="../../tutorial/dbo.html">Tutorial for Dbo</a> - %Wt's C++ ORM
+     library.
+   - <a href="../../tutorial/auth.html">Tutorial for Auth</a> - %Wt's
+     Authentication module.
    - <a href="../../examples/html/modules.html">Examples documentation</a>.
-  \page overview Library overview
+
+   \page overview Library overview
 
    \section contents Contents
 
@@ -656,10 +664,11 @@ appRoot=C:\Program Files\MyApplications\AppRoot
 
     <dd>Whether the application presents rendered content as XHTML or
       HTML. %Wt always renders XHTML1 compatible HTML, but by default
-      indicates to the browser that it is in fact HTML. However, to
-      use inline SVG (see WSvgImage), it is necessary to present an
-      XHTML mime type. Setting this option will do so only for
-      browsers that indicate support for XHTML.  </dd>
+      indicates to the browser that it is in fact HTML. Before the adoption
+      of HTML5, use inline SVG (see WSvgImage), it was necessary to present
+      an XHTML mime type. Setting this option will do so only for
+      browsers that indicate support for XHTML. Nowadays, this option
+      is rarely useful.</dd>
 
     <dt><strong>web-sockets</strong></dt>
 
@@ -673,9 +682,8 @@ appRoot=C:\Program Files\MyApplications\AppRoot
       acts as both an HTTP and WebSocket server, multiplexed on the
       same port(s).
 
-      This feature is still experimental: the Web Sockets RFC is still
-      a draft. %Wt implements up to version 17 of the draft (latest as of
-      November 2011).</dd>
+      %Wt implements the final Web Sockets RFC candidate, as well as
+      all prior drafts.</dd>
 
     <dt><strong>redirect-message</strong></dt>
 

doc/tutorial/auth.doc

@@ -3,7 +3,7 @@ Introduction to Wt::Auth
 
 Koen Deforche <koen@emweb.be> +
 
-For Wt 3.2.1 (January ?? 2012)
+For Wt 3.2.1 (February ?? 2012)
 
 :doc: link:http://www.webtoolkit.eu/wt/doc/reference/html/
 :tutorials: link:http://www.webtoolkit.eu/wt/doc/tutorial/
@@ -12,9 +12,8 @@ For Wt 3.2.1 (January ?? 2012)
 == Prerequisites
 
 In Wt 3.2.0, an authentication module was added to Wt. In this
-tutorial, we use an authentication feature example as a hands-on
-introduction to this module. This example is included in the Wt
-distribution, in
+tutorial, we use an example as a hands-on introduction to this
+module. This example is included in the Wt distribution, in
 https://github.com/kdeforche/wt/tree/master/examples/feature/auth1[examples/feature/auth1].
 
 This introduction assumes that you have a reasonable understanding of

examples/Doxyfile

@@ -4,7 +4,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 PROJECT_NAME           = "Wt examples"
-PROJECT_NUMBER         = 3.2.0
+PROJECT_NUMBER         = 3.2.1
 OUTPUT_DIRECTORY       = ../doc/examples
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English

examples/feature/CMakeLists.txt

@@ -5,6 +5,7 @@ SUBDIRS(
   mediaplayer
   miniwebgl
   multiple_servers
+  oauth
   serverpush
   socketnotifier
   suggestionpopup

examples/feature/auth1/README.md

@@ -12,6 +12,12 @@ How to run
 
 See the README in the parent directory.
 
+Additional arguments: `-c wt_config.xml`
+
+The configuration file specifies the configuration for using Google as
+an authentication provider (you need to register with Google for this to
+work).
+
 What it illustrates
 -------------------
 

examples/feature/auth1/wt_config.xml

@@ -0,0 +1,20 @@
+<server>
+    <application-settings location="*">
+	<properties>
+
+	    <!-- You need to register at google for this to work, and enter
+                 there the same values as you do here. -->
+            <!--
+	    <property name="google-oauth2-redirect-endpoint">
+		http://localhost:8080/oauth2callback
+	    </property>
+	    <property name="google-oauth2-client-id">
+		00000000000.apps.googleusercontent.com
+	    </property>
+	    <property name="google-oauth2-client-secret">
+		abcdefghijk-123456789xyz
+	    </property>
+            -->
+	</properties>
+    </application-settings>
+</server>

examples/feature/oauth/CMakeLists.txt

@@ -0,0 +1,7 @@
+WT_ADD_EXAMPLE(oauth.wt 
+        OAuth.C
+)
+
+TARGET_LINK_LIBRARIES(auth.wt)
+
+INCLUDE_DIRECTORIES(${WT_SOURCE_DIR}/src)

examples/feature/oauth/OAuth.C

@@ -0,0 +1,74 @@
+/*
+ * Copyright (C) 2012 Emweb bvba, Kessel-Lo, Belgium.
+ *
+ * See the LICENSE file for terms of use.
+ */
+#include <Wt/WApplication>
+#include <Wt/WContainerWidget>
+#include <Wt/WImage>
+#include <Wt/WServer>
+#include <Wt/WText>
+
+#include <Wt/Auth/AuthService>
+#include <Wt/Auth/GoogleService>
+
+Wt::Auth::AuthService authService;
+Wt::Auth::GoogleService *googleService = 0;
+
+class OAuthApplication : public Wt::WApplication
+{
+public:
+  OAuthApplication(const Wt::WEnvironment& env)
+    : Wt::WApplication(env)
+  {
+    if (!googleService) {
+      new Wt::WText("This example requires a Google Auth service "
+		    "configuration", root());
+      return;
+    }
+
+    process_ = googleService->createProcess
+      (googleService->authenticationScope());
+    Wt::WImage *ggi = new Wt::WImage("css/oauth-google.png", root());  
+    ggi->clicked().connect(process_,
+			   &Wt::Auth::OAuthProcess::startAuthenticate);
+
+    process_->authenticated().connect(this, &OAuthApplication::authenticated);
+  }
+
+  void authenticated(const Wt::Auth::Identity& identity) {
+    root()->clear();
+    new Wt::WText("Welcome, " + identity.name(), root());
+  }
+
+private:
+  Wt::Auth::OAuthProcess* process_;
+};
+
+Wt::WApplication *createApplication(const Wt::WEnvironment& env)
+{
+  return new OAuthApplication(env);
+}
+
+int main(int argc, char **argv)
+{
+  try {
+    Wt::WServer server(argv[0]);
+
+    server.setServerConfiguration(argc, argv, WTHTTP_CONFIGURATION);
+    server.addEntryPoint(Wt::Application, createApplication);
+
+    if (Wt::Auth::GoogleService::configured()) {
+      googleService = new Wt::Auth::GoogleService(authService);
+    }
+
+    if (server.start()) {
+      Wt::WServer::waitForShutdown();
+      server.stop();
+    }
+  } catch (Wt::WServer::Exception& e) {
+    std::cerr << e.what() << std::endl;
+  } catch (std::exception &e) {
+    std::cerr << "exception: " << e.what() << std::endl;
+  }
+}

examples/feature/oauth/README.md

@@ -0,0 +1,24 @@
+Auth1 feature example
+---------------------
+
+This is an example that illustrates the use of the
+`Wt::Auth::OAuthService` API for OAuth-2.0-based authentication (aka
+OpenID Connect), which can also be used directly without the rest of
+the Wt::Auth framework.
+
+How to run
+----------
+
+See the README in the parent directory.
+
+Additional arguments: `-c wt_config.xml`
+
+The configuration file specifies the configuration for using Google as
+an authentication provider (you need to register with Google for this to
+work).
+
+What it illustrates
+-------------------
+
+- the use of many aspects of the `Wt::Auth::OAuthService` (outside the
+  authentication framework).

examples/feature/oauth/wt_config.xml

@@ -0,0 +1,20 @@
+<server>
+    <application-settings location="*">
+	<properties>
+
+	    <!-- You need to register at google for this to work, and enter
+                 there the same values as you do here. -->
+            <!--
+	    <property name="google-oauth2-redirect-endpoint">
+		http://localhost:8080/oauth2callback
+	    </property>
+	    <property name="google-oauth2-client-id">
+		00000000000.apps.googleusercontent.com
+	    </property>
+	    <property name="google-oauth2-client-secret">
+		abcdefghijk-123456789xyz
+	    </property>
+            -->
+	</properties>
+    </application-settings>
+</server>

examples/hangman/README.md

@@ -9,6 +9,12 @@ How to run
 
 See the README in the parent directory.
 
+Additional arguments: `-c wt_config.xml`
+
+The configuration file specifies the configuration for using Google as
+an authentication provider (you need to register with Google for this to
+work), and customizes some email settings.
+
 What it illustrates
 -------------------
 

src/Wt/Auth/AuthWidget.C

@@ -31,10 +31,6 @@
 #include "AuthWidget"
 #include "web/WebUtils.h"
 
-#ifndef WT_DEBUG_JS
-#include "js/AuthWidget.min.js"
-#endif
-
 #include <memory>
 
 namespace skeletons {
@@ -379,9 +375,6 @@ void AuthWidget::createOAuthLoginView()
     WContainerWidget *icons = new WContainerWidget();
     icons->setInline(isInline());
 
-    WApplication *app = WApplication::instance();
-    LOAD_JAVASCRIPT(app, "js/AuthWidget.js", "authPopupWindow", wtjs1);
-
     for (unsigned i = 0; i < model_->oAuth().size(); ++i) {
       const OAuthService *auth = model_->oAuth()[i];
 

src/Wt/Auth/OAuthService.C

@@ -36,6 +36,10 @@
 
 #define ERROR_MSG(e) WString::tr("Wt.Auth.OAuthService." e)
 
+#ifndef WT_DEBUG_JS
+#include "js/AuthWidget.min.js"
+#endif
+
 namespace Wt {
 
 LOGGER("Auth::OAuthService");
@@ -48,8 +52,7 @@ public:
   OAuthRedirectEndpoint(OAuthProcess *process)
     : WResource(process),
       process_(process)
-  {
-  }
+  { }
 
   void sendError(Http::Response& response)
   {
@@ -161,6 +164,8 @@ OAuthProcess::OAuthProcess(const OAuthService& service,
   redirectEndpoint_ = new OAuthRedirectEndpoint(this);
   WApplication *app = WApplication::instance();
 
+  LOAD_JAVASCRIPT(app, "js/AuthWidget.js", "authPopupWindow", wtjs1);
+
   std::string url = app->makeAbsoluteUrl(redirectEndpoint_->url());
   oAuthState_ = service_.encodeState(url);
 

src/Wt/Chart/WChart2DRenderer.C

@@ -247,7 +247,8 @@ private:
     c.setY(p.y() + 0.3 * (p1.y() - p.y()));
   }
 
-  static void computeC(const WPointF& p_1, const WPointF& p0, const WPointF& p1,
+  static void computeC(const WPointF& p_1, const WPointF& p0,
+		       const WPointF& p1,
 		       WPointF& c1, WPointF& c2) {
     double m1x = (p_1.x() + p0.x())/2.0;
     double m1y = (p_1.y() + p0.y())/2.0;

src/Wt/Chart/WChartGlobal

@@ -44,11 +44,8 @@ enum MarkerType {
  * Data series of type LineSeries or CurveSerie may be filled under or
  * above the line or curve. This enumeration specifies the other limit
  * of this fill.
- * Data series of type BarSeries may use MinimumValueFill to configure the
- * plot to render the bars from the data point to the bottom of the chart or
- * MaximumValueFill to render the bars from the data point to the top of the 
- * chart. The NoFill and ZeroValueFill will be ignored for data series of the
- * BarSeries type.
+ * Data series of type BarSeries can use this setting to configure the bottom
+ * of the chart.
  *
  * \sa WDataSeries::setFillRange(FillRangeType range)
  * \sa WCartesianChart

src/Wt/Chart/WDataSeries

@@ -269,6 +269,11 @@ public:
    *
    * Line or curve series may be filled under or above the curve, using the
    * brush(). This setting specifies the range that is filled.
+   * Bar series may use MinimumValueFill to configure the chart to render its 
+   * bars from the data point to the bottom of the chart or MaximumValueFill to
+   * render the bars from the data point to the top of the chart. The default 
+   * value is ZeroValueFill, this value configures the chart to render the bars
+   * from the data point to zero.
    */
   void setFillRange(FillRangeType fillRange);
 

src/Wt/Chart/WDataSeries.C

@@ -28,7 +28,10 @@ WDataSeries::WDataSeries(int modelColumn, SeriesType type, Axis axis)
     yLabel_(false),
     barWidth_(0.8),
     hidden_(false)
-{ }
+{ 
+  if (type_ == BarSeries)
+    fillRange_ = ZeroValueFill;
+}
 
 void WDataSeries::setBarWidth(const double width) 
 {