Monday, October 21, 2013

Ganelon tutorial, part 2: widgets and actions.

This part of Ganelon tutorial shows how to connect Clojure project to MongoDB and then create dynamic widgets and actions that manage application data. You can see the complete application for this step in a GitHub repository: https://github.com/tlipski/ganelon-tutorial/tree/PART2_WIDGETS.

If you want to see the final result of an entire tutorial, you can view the tutorial app running live at http://ganelon-tutorial.tomeklipski.com or you can check out/star/fork the source code at http://github.com/tlipski/ganelon-tutorial.

For more information regarding Ganelon, you can visit the project website: http://ganelon.tomeklipski.com.

Connecting to MongoDB

Using mongodb is Clojure project is very easy and there's nothing Ganelon-specific about it.

First we will add dependency for congomongo library ([congomongo "0.4.1"]) to project.clj:

  :dependencies [[ganelon "0.9.0"]
                 [congomongo "0.4.1"]
                 [crypto-random "1.1.0"]]

There's also another new library referenced - crypto-random. It is a useful tool when it comes to generating secure random identifiers - something that will come in very handy when creating new meetups or invitations.

Having the MongoDB library in place, we can add connection setup to src/ganelon/tutorial.clj:

(ns ganelon.tutorial
  (:gen-class)
  (:require [ganelon.tutorial.pages.routes]
            [ring.middleware.stacktrace]
            [ring.middleware.reload]
            [ganelon.web.middleware :as middleware]
            [ganelon.web.app :as webapp]
            [noir.session :as sess]
            [somnium.congomongo :as db]))

(defn get-mongo-url []
  (or
    (get (System/getenv) "MONGOHQ_URL")
    (System/getProperty "MONGOHQ_URL")
    "mongodb://localhost/meetups"))

(defn initialize[]
  (db/set-connection! (db/make-connection (get-mongo-url))))

The get-mongo-url function returns mongo db url either from environment or from default development setup. In real-life scenario, the connection options will be much more complex, including username&password, failover options, etc.

It is also noteworthy, that we don't have to manage MongoDB connections ourselves - the underlying libraries are taking care of that for us.

The initialize function is referenced in lein-ring plugin configuration and will be invoked upon ring application initialization.

Accessing the data with MongoDB

To separate our application from underlying persistence layer, we will create seperate service namespaces for basic data integration. Fortunately, most of the work is done by congomongo library and we can use native Clojure data structures in all layers.

Data operations are defined in three namespaces:

All of functions in these namespace are quite simple and mostly cover congomongo (somnium.congomongo is imported as db) references, for example:

(defn retrieve-list [meetup-id]
  (db/fetch :meetup-times :where {:meetup-id meetup-id} 
    :sort {:date 1 :time 1}))

(defn add-time! [meetup-id date time]
  (when (empty? (db/fetch :meetup-times :where 
                  {:meetup-id meetup-id :date date :time time}))
   (db/insert! :meetup-times {:meetup-id meetup-id :date date 
                              :time time :create-time (java.util.Date.) 
                              :accepted []})))

Defining widgets

Finally, having all the other components in place, we are able to create some Ganelon-specific widgets and actions!

New meetup widget

The new meetup widget consists of two parts, listed below. Entire definition is contained in ganelon.tutorial.widgets.meetup-add namespace.

First of all, we have widget definition. As you can see below, it is a standard Clojure function, and it is invoked explicitly from Clojure code - ganelon.tutorial.pages.routes/meetup-layout to be exact.

(defn new-meetup-widget []
  (widgets/with-div
    [:h1 "New meetup"]
    [:p "Please provide meetup details:"]
    (widgets/action-form "meetup-create" {} {:class "form well"}
      [:div.control-group [:label.control-label {:for "inputTitle"} "Title"]
       [:div.controls
        [:input#inputTitle {:placeholder "Title for a meetup" :type "text"
                            :name "title"
                            :required "1"}]]]
      [:div.control-group [:label.control-label {:for "inputPlace"} "Place"]
       [:div.controls
        [:input#inputPlace {:placeholder "Place for a meetup" :type "text"
                            :name "place"
                            :required "1"}]]]
      [:div.control-group
       [:div.controls
        [:button.btn.btn-primary.btn-large {:type "submit"} "Create"]]])))

We use Hiccup to generate HTML form, styled by Bootstrap. One significant difference is that we don't use [:form] HTML tag, but rather ganelon.web.widgets/action-form function. This function allows us to reference a Ganelon action to be invoked upon form submission - client side.

Action meetup-create, creating new meetup is defined with a help of a ganelon.web.actions/defjsonaction macro.

(actions/defjsonaction "meetup-create" [title place]
  (let [id (meetup/create! title place)]
    [(ui-operations/open-page (str "/meetup/edit/" id))]))

The action itself is pretty straightforward:

  • First we create new meetup in MongoDB using form params - the destructuring syntax underneath is Compojure's, since we are using its handler infrastructure.
  • Then, we return one operation to be performed - to redirect the browser to meetup's edit page, containing its random and unique id.

In the next part of the tutorial, this action will change and will not reload entire page - and we will use custom JavaScript actions to achieve that.

Meetup details widget (and sub-widgets)

Meetup details widget is more complicated than the previous one, since it has to support not only edition of meetup place and title, but also:

Please observe, that the main meetup details widget is referencing sub-widgets as functions: meetup-edit-form-widget, meetup-times/meetup-times-widget and meetup-invitations/meetup-invitations-widget. This way, we can decompose our web application into a set of widgets with clearly defined dependencies.

(defn meetup-details-widget [meetup-id]
  (widgets/with-div
    (let [meetup (meetup/retrieve meetup-id)]
      [:div
        [:div {:style "padding-top: 20px;"}
          (meetup-edit-form-widget meetup)]
        (meetup-times/meetup-times-widget meetup-id)
        (meetup-invitations/meetup-invitations-widget meetup-id)])))

As we have more possibilities here than just meetup creation, we can make the form more dynamic. For example, we will capture :onchange JavaScript events for meetup title and place to update the fields in MongoDB without save button. Even more, we will display a confirmation label next to a saved field.

In meetup edition widget definition, we will add standard HTML attributes, referencing our Ganelon action (meetup-title-update) - but client-side! As Ganelon has information about defined actions, there is an interface available as a standard Compojure route (by default under /ganelon/actions.js), publishing all these functions to be referenced in JavaScript client-side:

(defn meetup-edit-form-widget [meetup]
  (widgets/with-div
    [:h1 "Meetup details"]
    (let [url (str (web-helpers/current-request-host-part)  "/meetup/edit/" 
                (:_id meetup))]
      [:p "Meetup admin url: " [:a {:href url } url]])
    [:form.form-horizontal.well
     [:div.control-group [:label.control-label {:for "inputTitle"} "Title"]
      [:div.controls [:input#inputTitle.input-xlarge 
                      {:placeholder "Title for a meetup" :type "text"
                       :value (:title meetup)
                       :onkeypress "$('#update-title-loader > *').fadeOut();"
                       :onchange (str "GanelonAction.meetup_title_update('" 
                                   (:_id meetup) 
                                   "', this.value);")
                       :name "title"
                       :required "1"}]
       [:span#update-title-loader]]]
     [:div.control-group [:label.control-label {:for "inputPlace"} "Place"]
      [:div.controls [:input#inputPlace.input-xlarge 
                      {:placeholder "Place for a meetup" :type "text"
                       :value (:place meetup)
                       :onkeypress "$('#update-place-loader > *').fadeOut();"
                       :onchange (str "GanelonAction.meetup_place_update('" 
                                   (:_id meetup) 
                                   "', this.value);")
                       :name "place"
                       :required "1"}]
       [:span#update-place-loader]]]]))

Once more, we are using standard Bootstrap 2 classes here to render a form.

Actions update meetup details in MongoDB, but also update form elements with jQuery's fade effect, provided by ganelon.web.ui-operations/fade function - for example:

(actions/defjsonaction "meetup-title-update" [id title]
  (meetup/update! id :title title)
  [(ui-operations/fade (str ".meetup-title-" id) 
     (hiccup.util/escape-html title))
   (ui-operations/fade "#update-title-loader"
    (hiccup.core/html [:span {:onmouseover "$(this).fadeOut();"}
                       " " [:i.icon-check] " Saved"]))])

You are welcome to browse the operations available in ganelon.web.ui-operations namespace - but please note, that it is also very easy to define your own, more fitting for you apps specific needs!

Meetup times widget allows us to add new invitations and to list and manage existing ones - including invitation confirmation status for each time and invitation. The whole implementation is available in ganelon.tutorial.widgets.meetup-times namespace.

(defn toggle-meetup-times-button [t inv editable-invitation-ids]
  (let [accepted? (some #{(:_id inv)} (:accepted t))]
    (widgets/with-div
      [:div {:style (str "padding: 8px; " (if accepted?
                                            "background-color: #5bb75b"
                                            "background-color: #9da0a4"))}
       (if (or (not editable-invitation-ids) (some #{(:_id inv)}
                                               editable-invitation-ids))
         (widgets/action-loader-link "meetup-times-toggle-invitation"
           {:invitation-id (:_id inv)
            :id (:_id t)
            :value (not accepted?)} {}
           (if accepted? [:i.icon-thumbs-up ] [:i.icon-thumbs-down ]))
         " ")])))

(defn meetup-times-list-widget [meetup-id editable-invitation-ids]
  (widgets/with-widget "meetup-times-list-widget"
    (let [times (meetup-time/retrieve-list meetup-id)]
      (if (not-empty times)
        (let [invitations (invitation/retrieve-list meetup-id)]
          [:table.table.table-striped.table-hover {:style "width: initial"}
           [:thead [:tr
                    (when-not editable-invitation-ids [:th ])
                    [:th "Date"] [:th "Time"]
                    (for [inv invitations]
                      [:th [:small
                            (hiccup.util/escape-html (:name inv))]])]]
           (for [t times]
             [:tr (when-not editable-invitation-ids
                    [:td (widgets/action-link "meetup-remove-time"
                           {:id (:_id t)} {} [:i.icon-remove ])])
              [:td (:date t)] [:td (:time t)]
              (for [inv invitations]
                [:td {:style "text-align: center; padding:0px;
                               border-left: 1px solid #ccc"}
                 (toggle-meetup-times-button t
                   inv editable-invitation-ids)])])])
      [:div.alert [:i "No meetup times defined yet!"]]))))

Please observe, that we are using widgets in loop here - as ganelon.web.widgets/with-div macro binds widget each time to a unique and random value, we can tons of instances of the same widget side by side.

We can also define a function which will return Ganelon UI operation refreshing times list - to be invoked externally (e.g. from invitations list widget):

(defn refresh-meetup-times-list-widget-operations [meetup-id]
  (ui-operations/fade "#meetup-times-list-widget"
    (meetup-times-list-widget meetup-id nil)))

This operation references widget by id attribute, allowing us to invoke it without widget-id context set.

The meetup-times-toggle-invitation action takes advantage of Compojure's route params support, allowing us to access them by name directly:

(actions/defwidgetaction "meetup-times-toggle-invitation" 
  [id invitation-id value]
  (if (boolean (Boolean. value))
    (meetup-time/accept-time! id invitation-id)
    (meetup-time/reject-time! id invitation-id))
  (toggle-meetup-times-button (meetup-time/retrieve id) 
     (invitation/retrieve invitation-id) [invitation-id]))

meetup-add-time action itself provides simple validation mechanism:

(actions/defjsonaction "meetup-add-time" [id date time]
  (if-let [new-mu (meetup-time/add-time! id date time)]
    ;success
     [(ui-operations/make-empty "#meetup-add-time-message")
      (ui-operations/fade "#meetup-times-list-widget"
        (meetup-times-list-widget id nil))]
    ;error - such time already exists
     (ui-operations/fade "#meetup-add-time-message"
        (hiccup.core/html
          [:div.alert
           [:button.close {:type "button" :data-dismiss "alert"} "×"]
           [:p "Such date & time combination already exists!" ]]))))

ganelon.web.ui-operations/make-empty operation simply removes all contents from designated dom element.

Meetup invitations list widget works on similar principle as meetup times widget listed above:

(defn meetup-invitations-widget [meetup-id]
  (widgets/with-widget "meetup-invitations-widget"
    [:h2 "Meeting invitations"]
    (widgets/action-form "invitation-create"
      {:meetup-id meetup-id}
      {:class "form-horizontal well"}
      [:span "Recipient's name:"] " "
      [:input {:type "text" :name "name" :required "1"}] " "
      [:button.btn.btn-primary "Create new invitation"]
      )
    (let [invitations (invitation/retrieve-list meetup-id)]
      (if (empty? invitations)
        [:div.alert 
         "No invitations created yet. Please use the form above to add some!"]
        (for [inv invitations]
          [:p
           [:b (hiccup.util/escape-html (:name inv))] [:br]
           "Link: " [:a {:href 
                         (str (web-helpers/current-request-host-part) 
                           "/i/" (:_id inv))}
                        (str (web-helpers/current-request-host-part) 
                          "/i/" (:_id inv))]
           (widgets/action-link "invitation-cancel"
             {:meetup-id meetup-id :id (:_id inv)}
             {:class "pull-right"}
             [:i.icon-remove] " Cancel")])))))

(actions/defwidgetaction "invitation-create" [name meetup-id]
  (invitation/create! meetup-id name)
  (actions/put-operation!
    (meetup-times/refresh-meetup-times-list-widget-operations 
      meetup-id))
  (meetup-invitations-widget meetup-id))

(actions/defwidgetaction "invitation-cancel" [meetup-id id]
  (invitation/delete! id)
  (actions/put-operation!
    (meetup-times/refresh-meetup-times-list-widget-operations 
      meetup-id))
  (meetup-invitations-widget meetup-id))

One thing worth noticing is that we put operation refreshing meetup times widget upon invitation creation or deletion. Instead of accessing widget functions for meetup times directly, we call a wrapper function which encapsulates all the necessary logic - e.g. DIV identification and returns ready to use Ganelon UI operation.

Invitation widget

Invitation widget is used by meetup attendees and allows them only to confirm or reject their presence at the meetup at given time. Whole implementation is provided withing ganelon.tutorial.widgets.invitation-details namespace.

(defn invitation-details-widget [id]
  (widgets/with-div
    (if-let [inv (invitation/retrieve id)]
      (let [meetup (meetup/retrieve (:meetup-id inv))]
        [:div
         [:div [:h2 (hiccup.util/escape-html (:title meetup))]
         [:p "Located at: " [:b (hiccup.util/escape-html (:place meetup))]]
         [:p "Sent to: " [:b (hiccup.util/escape-html (:name inv))]]]
         [:h2 "Confirm your presence"]
         [:p "Please mark times & dates that are best for you:"]
         (meetup-times/meetup-times-list-widget (:meetup-id inv) [id])])
      [:div.alert.alert-error [:h2 "Invitation not found"]
       [:p "Invitation with a supplied id has not been found.
            Please make sure that the link is correct."]])))

Please note, that we are re-using meetup-times/meetup-times-list-widget to provide meetup times and to allow the attendee to confirm or negate his/her presence at the meetup. We do so by providing additional parameter to function invocation, limiting displayed invitations only to the currently used.

Summary

In this blog post we have learned, that it is very easy to build dynamic, AJAX-oriented web application entirely in Clojure, server side. Even better, such approach allows us to re-use existing components in different scenarios. We don't have to stick with our application being single-page and we are totally 100% SEO friendly in such approach, as widgets are used both in standard HTML page rendering as in updates to the page itself.

In the next post I will show how to add middleware for security handling and how to define custom Ganelon UI operations in JavaScript.

Tuesday, August 20, 2013

Ganelon tutorial, part 1: basic setup, routes & templates

This part of Ganelon tutorial shows how to start Ganelon-enabled project with leiningen, configure basic pages with Hiccup templates and run the jetty-ring adapter. You can see the complete application for this step in a GitHub repository: https://github.com/tlipski/ganelon-tutorial/tree/PART1_ROUTES.

If you want to see the final result of an entire tutorial, you can view the tutorial app running live at http://ganelon-tutorial.tomeklipski.com or you can check out/star/fork the source code at http://github.com/tlipski/ganelon-tutorial.

For more information regarding Ganelon, you can visit the project website: http://ganelon.tomeklipski.com.

Creating Ganelon project

Ganelon is just a standard Leiningen/Maven/Gradle/etc. dependency, so you can just use lein new to start a new project or set up the project.clj file and src/, script/ and resources/ directories manually.

In either way, it is important that the project.clj file contains a dependency on ganelon 0.9.0 library. What is worth mentioning, is that ganelon comes with dependencies on lib-noir, Compojure & hiccup, so in simple cases, it is enough to just add this one dependency when it comes to Clojure web apps.

Ganelon 0.9.0 is deployed to clojars, so it will get fetched alongside other Clojure libraries.

Our project.clj at this moment looks like this:

(defproject ganelon-tutorial "0.9-SNAPSHOT"
  :description "Ganelon tutorial"
  :url "http://ganelon.tomeklipski.com"
  :dependencies [[ganelon "0.9.0"]
                 [org.clojure/clojure "1.5.1"]]
  :license {:name "Eclipse Public License - v 1.0"
            :url "http://www.eclipse.org/legal/epl-v10.html"
            :distribution :repo
            :comments "same as Clojure"}
  :plugins [[lein-ring "0.8.6"]]
  :ring {:handler ganelon.tutorial/handler :init ganelon.tutorial/initialize})

As we can see, there is only one dependency other than Clojure 1.5.1 - it is for ganelon 0.9.0. There is also a lein-ring configuration with a pretty standard settings - an initialize function, which at this moment does nothing but will establish a connection pool for MongoDB and a handler reference.

Handler definition

Our handler will be using Ganelon's simple mechanism for establishing routes - and we will mix app-handler from Ganelon with standard Ring middleware.

You can add your own handlers and middleware here and it will just work. If you don't want to or cannot use Compojure routes, you can just skip this step altogether and use raw Ring handlers from ganelon.web.actions package.

(def handler
  (->
    (ganelon.web.app/app-handler
      (ganelon.web.app/javascript-actions-route))
    middleware/wrap-x-forwarded-for
    (ring.middleware.stacktrace/wrap-stacktrace)
    (ring.middleware.reload/wrap-reload {:dirs ["src/ganelon/tutorial/pages"]})))

View the entire ganelon/tutorial.clj file.

Please also note, that we are using a convienent ring.middleware.reload/wrap-reload middleware, which will reload all the changes to Clojure files in specified directories - src/ganelon/tutorial/pages in this case.

Defining the Hiccup templates

The simplest way (but sometimes not the most effective) to achieve common layout and HTML code for pages with Hiccup is to define them as functions, accepting page content as parameters:

(defn layout [& content]
  (hiccup/html5
    [:head [:meta {:name "viewport" :content "width=device-width, initial-scale=1.0"}]
     [:title "Ganelon tutorial - Meetups"]
     ;real life site should use CDN/minify to serve static resources
     (hiccup/include-css "/ganelon/css/bootstrap.css")
     (hiccup/include-css "/ganelon/css/bootstrap-responsive.css")
     ]
    [:body.default-body [:div#navbar (navbar)]
     [:div.container {:style "padding-top: 70px"}
      content]
     [:footer {:style "opacity:0.9; text-align: center; padding: 30px 0; margin-top: 70px; border-top: 1px solid #E5E5E5; color: #f6f6f6; background-color: #161616;"}
      [:div.container [:p "The Ganelon framework has been designed, created and is maintained by " [:a {:href "http://twitter.com/tomeklipski"} "@tomeklipski"] "."]
       [:p "The code is available under " [:a {:href "http://opensource.org/licenses/eclipse-1.0.php"} "Eclipse Public License 1.0"] "."]
       [:p [:a {:href "http://github.com/tlipski/ganelon-tutorial"} "View the sources on GitHub."]]
       [:p "This interactive tutorial runs on " [:a {:href "http://cloudbees.com"} "CloudBees"]
        " and " [:a {:href "http://mongohq.com"} "MongoHQ"] "."]
       ]]]))

View the entire ganelon/tutorial/pages/common.clj file.

As you can see, we are using standard Bootstrap2 CSS/classes - nothing fancy.

We have also defined a helper layout with common UI components and put it routes.clj file:

(defn meetup-layout [& contents]
  (common/layout
    [:div.row-fluid [:div.span3 [:div {:style "border: 1px dashed #363636"} "TODO - new meetup widget here"]
                     [:div {:style "border: 1px dashed #363636"} "TODO - meetup list widget here"]]
     [:div.span1 ]
     [:div.span8 [:div#contents contents]]]))

Defining routes

With templates already defined, we can set up our routes. They will contain placeholders for widgets, as these will be added in the next steps of the tutorial:

(dyna-routes/defpage "/" []
  (meetup-layout
    [:div.hero-unit [:h1 "Welcome"]
     [:p "Welcome to the interactive tutorial for " [:a {:href "http://ganelon.tomeklipski.com"} "Ganelon micro-framework."]]
     [:p "This sample application used to manage meetups provides links to display source of every widget and action used.
      In addition to that, each widget has a dashed border to mark its boundary."]]))

(dyna-routes/defpage "/meetup/edit/:id" [id]
    (meetup-layout
      [:div {:style "border: 1px dashed #363636"} "TODO - meetup details widget here"]))

(dyna-routes/defpage "/i/:id" [id]
  (meetup-layout
    [:div {:style "border: 1px dashed #363636"} "TODO - invitation details widget here"])) 

The ganelon.web.dyna-routes/defpage macro simply creates compojure.core/ANY route and adds it to a list maintained in the ganelon.web.dyna-routes namespace. The routes can be grouped for easier management and middleware can be defined in a similar way. More information is available on the Routing page of Ganelon project website.

Running the project

After that, we have two general ways to run our project and there is nothing specific to Ganelon about them:

The simplest is to use lein-ring plugin and run lein ring server:

$ lein ring server
2013-08-19 21:39:41.474:INFO:oejs.Server:jetty-7.6.1.v20120215
2013-08-19 21:39:41.502:INFO:oejs.AbstractConnector:Started SelectChannelConnector@0.0.0.0:3000
Started server on port 3000

We can also use lein ring uberjar to obtain an executable jar file.

If we are using some IDE not compliant with Leiningen - for example IntelliJ IDEA, we can create a simple script to run our jetty-ring adapter:

(ns run
  (:require [ganelon.tutorial]
            [ring.adapter.jetty :as jetty]))

(defonce SERVER (atom nil))

(defn start-demo [port]
  (jetty/run-jetty ganelon.tutorial/handler {:port port :join? false}))

(ganelon.tutorial/initialize)

(let [port (Integer. (get (System/getenv) "PORT" "3000"))]
  (swap! SERVER (fn [s] (when s (.stop s)) (start-demo port))))

This scripts just optionally stops and then starts jetty adapter for our handler - but can be loaded for example into IntelliJ IDEA's REPL.

After applying either method, we can just navigate to http://localhost:3000/ to see the running application.

What's next?

In the next part of the tutorial, I will show how to build widgets, actions and use them to propagate data back and forth between a web app and a MongoDB instance.

Monday, August 19, 2013

Ganelon tutorial, intro

What is Ganelon?

Ganelon is a microframework of mine, built to ease the pain of using AJAX in Ring/Compojure based Clojure web applications. 
The microframework is not intended as an end-to-end framework, solving all the problems of building web applications in Clojure, but rather as a tool that solves one particular problem in an elegant and simple way. 
Other problems, such as routing, templating or integration with underlaying HTTP(S) server architecture have their own, well established solutions. For example there is Compojure or Mustache for routing, Hiccup or  Clabango for templating, etc. 
For a full list, you can go to http://www.clojure-toolbox.com/. Important thing to note is that by using Ganelon you are still free to apply any other Ring-compliant or client-side libraries - Ganelon simply enhances your application's capabilities, not forces you down some narrow path.

How does Ganelon work?

Ganelon is also different from modern, JavaScript/ClojureScript based web frameworks, as it gives a control over user interface behaviour directly to a code running server-side. JavaScript layer is very thin and provides a set of generic operations; the layer can of course be easily extended as we will see in the tutorial. More information is available in the documentation.
As to my knowledge, there are no other Clojure frameworks built this way, but similar principle is used for example in Vaadin or Wicket (Java) or in Weblocks (Common LISP). The main difference is that Ganelon is not keeping the information about widget state. 

Ganelon tutorial

In the Ganelon tutorial, I will show how to:
  • Setup a new Ganelon project, configure basic routes and layout templates (using Hiccup) (PART  1).
  • Build reusable, dynamic elements of UI (widgets) and use MongoDB (from mongohq) as a persistence layer (PART 2).
  • Add middleware for security handling and define custom operations (PART 3).
  • Finally, I will show how can the tutorial app display its source code (PART 4).
If you want to see the final result, you can view the tutorial app running live at http://ganelon-tutorial.tomeklipski.com or you can check out/star/fork the source codes at http://github.com/tlipski/ganelon-tutorial.


Thursday, April 18, 2013

Ganelon 0.9.0 released

Ganelon - a micro-framework supporting server-side oriented AJAX web applications in Ring/Clojure has been released in version 0.9.0 - first publicly available non-SNAPSHOT.

In addition to that, an interactive tutorial app (meetings management with MongoDB) has been launched at http://ganelon-tutorial.tomeklipski.com. Source codes for it can be found in GitHub repository: https://github.com/tlipski/ganelon-tutorial
In the following weeks, this tutorial app will be used as a base for a tutorial blog series.

Using Ganelon

To use Ganelon in your Compojure/Ring/Clojure web application, simply add the following dependency to your project.clj file:

    [ganelon "0.9.0"]
For more information on using Ganelon, please visit http://ganelon.tomeklipski.com.

Production use

Ganelon is used to build user interface for Daily Social - social news aggregator delivering top stories to Pocket or Readability. So it is used in production for almost half a year. The demo and interactive tutorial sites are written using Ganelon as well.

I think that the best thing to do now - is to give a Ganelon a try and see how it works out for yourself.
Any issues/fixes can be reported directly to the GitHub repo at http://github.com/tlipski/ganelon.

Most important features

As this is a first major release of Ganelon, instead of changes introduced, I will simply highlight most important features:
  • AJAX support for client-side operations, including basic functions and almost whole jQuery | Manipulation library.
    • Ability to add custom client-side operations.
    • Additional libraries for Bootstrap Modal JavaScript and jquery gritter plugin (Growl-style notifications).
  • Support for definition of AJAX actions as Compojure routes.
  • Basic functions rendering client-side code for HTML/JavaScript controls invoking AJAX actions.
  • Support for distributed configuration of Compojure routes - somewhat akin to Noir's defpage macro.
Helper library for Ganelon - ganelon-util has been released as well - the current version is 0.8.0. Ganelon adds subdependency on ganelon-util, so you don't have to worry about adding it manually.

Thursday, April 11, 2013

Running and debugging Clojure code with Intellij IDEA

In the following blog post, I will show how to install La Clojure plugin, import project from leiningen to IntelliJ IDEA, how to interact with REPL and finally how to use IDEA's debugger to debug Clojure code run from REPL. 
These features make Clojure development with IDEA a real pleasure.

Installation of La Clojure plugin

To use Clojure with IntelliJ IDEA, we have to add La Clojure plugin. To do that, we open File / Settings / Plugins from a menu, than click on Browse repositories... button at the bottom of the Settings window (highlighted in red).


Then, we select La Clojure from plugins list (we can use filter in the right top corner of the window), right click on the item and select Download and Install command:


Upon leaving the Settings window, IDEA will ask if we want to restart it - the plugin will not work unless we do.

Importing leiningen project

With the La Clojure plugin ready and active, we can import a leiningen project into IntelliJ IDEA. All we have to do is to generate appropriate Maven pom.xml file:

lein pom

Then, we can import the maven module using IntelliJ IDEA.

Step 1: select Import Project from welcome screen:


Step 2: point IDEA to pom.xml (not project.clj) file:


After steps above, you can follow standard IntelliJ IDEA Maven project import procedure: confirm Maven project options, select IDE, set project name and IDEA files location for a project.

One thing that has to be done manually is adding Clojure Facet to project modules. To do that, we simply select File / Project structure from a menu, then navigate to our module in Modules tab, click on a + sign and finally select Clojure:


Starting the REPL


With Maven project loaded successfully, IDEA will fetch dependencies which aren't already in Maven local repository. With these libraries fetched, we can start Clojure REPL for our project by selecting Tools / Start Clojure Console from a menu. 

We can also use the keyboard shortcut - Ctrl-Shift-D by default in the newest La Clojure version.

The REPL will set a classpath for all of our libraries and sources referenced in a current module:



Interacting with REPL

To load a current Clojure file to REPL by a load-file function, all we have to do is to select Tools / Clojure REPL / Load file to REPL or use a keyboard shortcut - Ctrl-Shift-L by default.


We can also use Tools / Clojure REPL menu to:
  • Run selected text in REPL 
  • Execute last S-Expression in REPL
  • Run top S-Expression in REPL

Debugging with REPL

With IntelliJ IDEA we can connect a remote debugger to a REPL, allowing us to debug our Clojure code.

Step 1: we have to create a Remote Debugger profile using Run / Edit Configurations... from a menu.
To add a Remote Debugger, we have to click on the plus '+' sign and select 'Remote' configuration type:


We can adjust the settings or leave them as default. Most importantly, we have to copy command line arguments for running remote JVM, for example:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

The default value for port is 5005, but it can be adjusted in case there is another process already listening on that port.

It is also convienient to name this Remote Debugging session as 'Clojure REPL Debugger' for example.

Step 2: apply command line arguments to REPL settings for Clojure facet in our module (File / Project Structure / Modules / [our module] / Clojure / JVM arguments):



Step 3: Start a REPL with Tools / Start Clojure Console or a keyboard shortcut - Ctrl-Shift-D by default:


If the REPL is already running, it needs to be stopped and started again.

Step 4: Start Remote Debugger configuration created in step 1 with Run / Debug 'Clojure REPL Debugger' or a keyboard shortcut - Shift-F9 by default.


The name of Remote Debugger configuration is dependent on the configuration created in step 1. For the sake of example, I am using 'Clojure REPL Debugger'.

And finally, with the Remote Debugger ready and connected to REPL, we can debug our Clojure code:





Tuesday, March 19, 2013

Introducing Ganelon - micro-framework supporting AJAX in Clojure/Ring web apps

I've recently published a simple Open Source micro-framework which allows server-side Clojure code to update web page content or invoke any JavaScript operations dynamically through XHR requests and thin JavaScript layer. 

Ganelon is fully Ring compatible and based on Compojure and lib-noir. Being a AJAX focused, it is not a direct replacement for Noir. It can rather ease the pain of handling dynamic page requests in any Ring-based web application.

The execution model is heavily influenced by Weblocks or Vaadin, but without session-statefulness and out-of-the-box rich user interface:

  • Certain parts of the page can be scoped as Widgets (for example using id attribute in HTML or ganelon.web.widgets.with-div utility macro) and referenced by id in Actions, and updated by Operations. Widgets can reference Actions to be invoked.
  • Actions are invoked as XHR requests and return a set of Operations to be performed client-side. Actions are in fact simple Ring handlers.
  • Operations provide abstraction layer over client-side JavaScript execution - e.g. using Bootstrap Modal or just updating part of DOM tree (a Widget or any other) or open certain URL in a browser window - or just anything else that has a simple integration layer provided.

The source codes are on GitHub: http://github.com/tlipski/ganelon and demo site and documentation is available at http://ganelon.tomeklipski.com.

Sample code (a shoutbox) is listed below:

;A Widget, returning HTML code:
(defn box-widget []
 (widgets/with-div
   [:p "Call count (since restart): " [:b @COUNTER] ". Last 4 entries:"]
   (for [entry @ENTRIES]
     [:div.hibox [:b (:time entry)] ": "
      (hiccup.util/escape-html (:msg entry))])
   (widgets/action-form "say-hi" {} {:class "form-inline"}
     [:input {:name "msg" :placeholder "Say hi!" :type "text"
              :maxlength "20" :size "20"}] " "
     [:button {:class "btn btn-primary"} "Send!"])))

;An Action, performing side effects and returning part of the page to be updated
(actions/defwidgetaction "say-hi" [msg]
 (swap! COUNTER inc)
 (swap! ENTRIES #(util/smart-subvec (flatten [(mkmsg msg) %]) 0 4))
 (box-widget))

JavaScript code uses jQuery and optionally Bootstrap, but the implementation is really trivial and therefore easy to replace using your favorite JS library.

Monday, March 18, 2013

Porting Activiti Explorer to Liferay Portal

In the following blog post,  I have highlighted the matter of embedding Activiti BPMS inside a Liferay Portal. With Activiti Explorer built in Vaadin and Spring, it is fairly easy to use entire  components in a totally different environment. 

Proof of concept fork with Tasks and Admin portlets is available in 
https://github.com/tlipski/Activiti/tree/master/modules/activiti-portlets.

Porting Activiti Explorer to Liferay Portal

Activiti is a popular Open Source, BPMN2.0-compliant BPMS that provides a great overall package. Not only there is a library that can be embedded inside your application, but Activiti also comes with an Explorer web application, which provides an ergonomic user interface for basic operations:



But, Activiti is "just" a BPMS - you can run your processes with it, maybe even connect to Active Directory, Alfresco or ESB - but if you want to embed it in your intranet/extranet portal, you are almost on your own. 

Please note, that embedding Activiti in portal is not the same as using it to manage portal assets - for example, as a replacement for Liferay's Kaleo Workflow. The matter discussed here is more focused on using all of Activiti features, including user interface.

Luckily, this is when frameworks used in Activiti pay off - Activiti Explorer is written in Vaadin 6 and Spring. With component oriented approach from Spring and UI modularity encouraged by Vaadin, it is fairly easy to port this application to Liferay. We can extract entire components from Activiti Explorer (e.g. Tasks panel) and use them in a whole new environment.
Extracting and re-using entire components requires much more work in a classical MVC approach and even may not always be possible. Also, portlet support in Vaadin makes a whole task much more pleasant.

For the impatient: The code is available in my fork of Activiti 5.13-SNAPSHOT: http://github.com/tlipski/Activiti, especially in activiti-portlets module https://github.com/tlipski/Activiti/tree/master/modules/activiti-portlets.

Necessary steps

"Fairly easy" does not mean without any effort. There are differences between a standard Vaadin application and a portletized one:
  • Portlet descriptors are necessary
  • GUI should be divided into separate portlets
  • Spring-Vaadin integration is different due to a portal-specific request life-cycle
  • Navigation can be provided by portal - including friendly URLs, which makes for a more standard user experience.
In addition to that, some mechanisms used by Activiti are already provided by Liferay Portal and we need to bridge them:
  • Users and Groups should be managed by Liferay Portal
  • Authentication data should be taken from a portlet container
  • Mail notifications could possibly use Liferay Mail API
Some other things have to be taken into account as well:
  • Distribution and management of Vaadin widgetset and version - we should use Vaadin Control Panel portlet and Liferay to manage Vaadin dependencies. This requires special handling, since Activiti Explorer 5.13 utilizes dCharts Vaadin Add-on.
  • Vaadin theme used in portlets - which is also customized by Activiti, but should be coherent with portal's look & feel.

Current state of work

It is nice to theorize, but certain things need to be verified in practice. At this moment, my fork at http://github.com/tlipski/Activiti provides:
  • Activiti Tasks portlet, which works in a user's context as if the user would log in to Activiti Explorer app. The portlet provides full functionality, including operations as starting a new task, fetching it from a task list, displaying task's events, assignment/ownership transfers, file attachments and so on.
  • Activiti Admin portlet in Liferay Control Panel - most tabs seem to work fine - except Users and Groups, which should be disabled as we are using Liferay Portal to do that.




Implementation details:

On the implementation side, most noteworthy changes which have been implemented in activiti-portlets module: https://github.com/tlipski/Activiti/tree/master/modules/activiti-portlets are:
  • IdentityProvider implementation utilizing Liferay API (need to work on user photos though!)
  • Spring-Vaadin bridging for portal (see my previous post).
  • Custom portlet applications and main Window class. The interesting detail here is that with Vaadin portlets, you should not set width of components to 100%, as it will result in 0px height. Generally speaking, the height in Vaadin portlet components should be set to undefined - null, or a preset value in pixels.

Next steps?

Connecting Liferay with Activiti brings a myriad of new possibilities, but before that, some basic things need to be done:
  • More portlets! Reporting and Processes tabs need their respective portlets, but also "start process" portlet might be worth considering since we can manage UI contents in a more flexible way.
  • More testing! If anyone is interested in testing Activiti portlets in Liferay, let me know and I will provide prebuilt applications. So far, I've used Liferay 6.1 GA2 CE and H2 in-memory database for Activiti.
  • Friendly urls - especially for tasks resolved by id, and for interportlet communication - e.g. when starting a process.

Sunday, February 24, 2013

Integrating Spring, Vaadin & Liferay

As there are numerous materials on how to integrate Vaadin with Spring, Spring with Liferay (using portlet dispatcher) and Vaadin with Liferay, the integration of all three technologies at once is not documented well.
In such approach, there are two major differences between Vaadin with Spring in a standard web application and portlets-based one. This post is based on Vaadin 6, but the rules itself apply to Vaadin 7 as well.

The setup

The solution requires that we will overwrite two methods defined in com​.vaadin​.terminal​.gwt​.server​.AbstractApplicationPortlet2.
To achieve that, we have to create our own subclass:
package com.tomeklipski.blog.sample.vaadin;

import com.vaadin.Application;
import com.vaadin.terminal.gwt.server.ApplicationPortlet2;

import javax.portlet.*;
import java.io.IOException;

/**
 * Created with IntelliJ IDEA.
 *
 * @author tomek@lipski.net.pl
 *         Date: 2/23/13 4:06 PM
 */
public class MyApplicationPortlet extends ApplicationPortlet2 {

/* overwritten methods here */

}
The newly created class has to be used in web.xml:
<servlet>
    <servlet-name>VaadinPortletServlet</servlet-name>
    <servlet-class>com.liferay.portal.kernel.servlet.PortletServlet</servlet-class>
    <init-param>
        <param-name>portlet-class</param-name>
        <param-value>com.tomeklipski.blog.sample.vaadin.MyApplicationPortlet</param-value>
    </init-param>
    <load-on-startup>0</load-on-startup>
</servlet>
And in portlet.xml as well:
<portlet>
    <portlet-name>MyPortlet</portlet-name>
    <display-name>My Sample Portlet</display-name>
    <portlet-class>com.tomeklipski.blog.sample.vaadin.MyApplicationPortlet</portlet-class>

    <init-param>
        <name>application</name>
        <value>com.tomeklipski.sample.vaadin.SomeApplication</value>
    </init-param>
    <init-param>
        <name>widgetset</name>
        <value>com.vaadin.portal.gwt.PortalDefaultWidgetSet</value>
    </init-param>
    <supports>
        <mime-type>text/html</mime-type>
        <portlet-mode>view</portlet-mode>
    </supports>
    <portlet-info>
        <title>My Sample Portlet</title>
        <short-title>Sample</short-title>
    </portlet-info>
</portlet>

Accessing Spring context in portlet

First of all - portlets are configured using listeners as well. Liferay adds its listeners to web.xml during deploy, so listeners in web.xml might look like this:
<listener>
    <listener-class>
        com.liferay.portal.kernel.servlet.PluginContextListener
    </listener-class>
</listener>
<listener>
    <listener-class>
        com.liferay.portal.kernel.servlet.SerializableSessionAttributeListener
    </listener-class>
</listener>
<listener>
    <listener-class>
        org.springframework.web.context.ContextLoaderListener       
    </listener-class>
</listener>
<listener>
    <listener-class>
        org.springframework.web.context.request.RequestContextListener
    </listener-class>
</listener>
<listener>
    <listener-class>
        com.liferay.portal.kernel.servlet.PortletContextListener
        </listener-class>
</listener>


As you can see, they are all mixed up and we cannot rely that during invocation of method javax.portlet.Portlet.init(PortletConfig config) the spring context is available.
If we want to refer to our application as a Spring bean, we have to overwrite method com​.vaadin​.terminal​.gwt​.server​.AbstractApplicationPortlet​.getNewApplication​(​PortletRequest request), and attempt to retrieve Spring context here:
@Override
protected Application getNewApplication(PortletRequest request) {
    PortletContext portletContext = getPortletContext();
    ApplicationContext webApplicationContext
            = PortletApplicationContextUtils.getWebApplicationContext(portletContext);
    Application app = (Application) webApplicationContext.getBean("app");
    return app;
}
The fetching of portlet and web application contexts can of course be optimized.

Accessing "session" scope

The "session" scope in Spring is a convient way to store objects related to a session, for example:
<bean name="app" class="com.tomeklipski.sample.vaadin.SomeApplication" scope="session">
    <property name="dataManager" ref="dataManager" />
    <property name="i18nManager" ref="i18nManager" />
</bean>
In standard web application, we can enable it using HttpRequestListener in web.xml:
<listener>
    <listener-class>
        org.springframework.web.context.request.RequestContextListener
    </listener-class>
</listener>
But, in JSR286 portlet, the listener is not invoked as it should and portlet specification does not provide the ability to add portlet request listeners as above.
Luckily, we can overwrite the method com​.vaadin​.terminal​.gwt​.server​.AbstractApplicationPortlet​.handleRequest​(​PortletRequest request, PortletResponse response) with a code, that will set appropriate ThreadContext values:
@Override
protected void handleRequest(PortletRequest request,
                             PortletResponse response)
        throws PortletException, IOException {
    LocaleContext previousLocaleContext = LocaleContextHolder.getLocaleContext();
    LocaleContextHolder.setLocaleContext(
            new SimpleLocaleContext(request.getLocale()), false);

    // Expose current RequestAttributes to current thread.
    RequestAttributes previousRequestAttributes = RequestContextHolder
            .getRequestAttributes();
    PortletRequestAttributes requestAttributes = null;
    if (previousRequestAttributes == null ||
            previousRequestAttributes.getClass()
                    .equals(PortletRequestAttributes.class)) {
        requestAttributes = new PortletRequestAttributes(request);
        RequestContextHolder.setRequestAttributes(requestAttributes,
                false);
    }

    try {
        super.handleRequest(request, response);
    } finally {
        LocaleContextHolder.setLocaleContext(previousLocaleContext,
                false);
        if (requestAttributes != null) {
            RequestContextHolder.setRequestAttributes(
                    previousRequestAttributes, false);
            requestAttributes.requestCompleted();
        }
    }
}

Summary

It is fairly easy to use Spring in Vaadin portlets - but there are some differences between standard Vaadin-Spring application approach and portletized one. We can easily overcome them by overwriting two methods in com​.vaadin​.terminal​.gwt​.server​.AbstractApplicationPortlet.