glimmer-dsl-opal 0.0.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1e27d44e69248f9febb6c2b8ce6d58d5f6a876d451b09d293769e3296e8c1ff
-  data.tar.gz: 30f77e89b509c325d8e609a2b6cda35425acb2b3e6f48ed8113c724208a1c0e9
+  metadata.gz: 321f0f4121858de374edacf81772b65ff3bd0ee1e155531b5a04681c1e7f5fa0
+  data.tar.gz: 5bfab859f5b96458ca452444253a8fb1fefe5274e2bdbc892e574ab6fcd74ed0
 SHA512:
-  metadata.gz: 6ee6ca73fef3795d270cf4980fd4392beb39bc2a4f240f5a0fe10014772206aa5da1ca502559a13da2abb3191f681d5f76041003d207736c4469be2709476d73
-  data.tar.gz: 381fde33081fca87a978babb4e3048acfacf70a56de249eb5ea44be9dd0c6f60139b278601d929110eb6f687f3dd65c31287458d8c98c0fc1e31c59c3b842d71
+  metadata.gz: 58ee88fda2ed5729f1c3b58035d6aa252fbb23ac2a12b120e88040aa485d7e34bf9f337c1a8e6f289c73c23528aec4dd735a00c0542c4c120c9499141815cc38
+  data.tar.gz: d70d728a4beb4ff5bff63c68b823155ab39b014163698fe875ffacbba09c2e18b91fc3b11fd529876857187fe7aae5e331ecf32b06f4d417a0615bd38d64877a

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Change Log
 
+## 0.3.0
+
+- Support opening a custom shell in a browser tab/window by passing in query parameters to URL (e.g. ?custom_shell=keyword+option1=value1 etc...)
+- Make custom shells automatically open in a new tab/window (while standard shells continue to open in the same window by replacing its content)
+- Hello, Custom Shell! Sample
+
+## 0.2.0
+
+- Color support
+- Font support
+- Custom Widget Support
+- Hello, Custom Widget! sample
+- Updated Hello, Combo! sample to match the latest changes in Glimmer DSL for SWT
+- `SWT` full re-implementation in Opal as `Glimmer::SWT` with all the `SWT` style constants
+
+## 0.1.0
+
+- Code redesign to better match the glimmer-dsl-swt APIs
+- opal-jquery refactoring
+- opal-rspec test coverage
+
+## 0.0.9
+
+- Upgraded to glimmer gem v0.9.3
+- Fixed issue with missing Glimmer::Opal::ElementProxy#id=(value) method breaking Contact Manager sample Find feature
+
+## 0.0.8
+
+- Contact Manager sample support
+
+## 0.0.7
+
+- Tic Tac Toe sample support
+- Login sample support
+
+## 0.0.6
+
+- Hello, Tab! sample support
+
+## 0.0.5
+
+- Hello, Browser! sample support
+
+## 0.0.4
+
+- Hello, List Single Selection! sample support
+- Hello, List Multi Selection! sample support
+
+## 0.0.3
+
+- Hello, Computed! sample support
+
+## 0.0.2
+
+- Hello, Combo! sample support
+
 ## 0.0.1
 
 - Initial support for webifying Glimmer SWT apps

data/README.md

@@ -1,14 +1,14 @@
-# <img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=65 /> Glimmer DSL for Opal 0.0.7 (Web GUI for Desktop Apps)
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for Opal 0.3.0 (Webify Desktop Apps)
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-opal.svg)](http://badge.fury.io/rb/glimmer-dsl-opal)
 [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for Opal is a web GUI adaptor for desktop apps built with [Glimmer](https://github.com/AndyObtiva/glimmer) & [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt).
+### You can finally live in pure Ruby land on the web!
 
-It enables running [Glimmer](https://github.com/AndyObtiva/glimmer) desktop apps on the web via [Rails](https://rubyonrails.org/) 5 and [Opal](https://opalrb.com/) 1.
+[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [Opal](https://opalrb.com/) is an experimental proof-of-concept web GUI adapter for [Glimmer](https://github.com/AndyObtiva/glimmer) desktop apps (i.e. apps built with [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt)). It webifies them via [Rails](https://rubyonrails.org/), allowing Ruby desktop apps to run on the web via [Opal Ruby](https://opalrb.com/) without changing a line of code. Apps may then be custom-styled for the web with standard CSS by web designers. 
 
-NOTE: Alpha Version 0.0.7 only supports capabilities for the following [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) [samples](https://github.com/AndyObtiva/glimmer#samples):
+Glimmer DSL for Opal successfully reuses the entire [Glimmer](https://github.com/AndyObtiva/glimmer) core DSL engine in [Opal Ruby](https://opalrb.com/) inside a web browser, and as such inherits the full range of powerful Glimmer desktop [data-binding](https://github.com/AndyObtiva/glimmer#data-binding) capabilities for the web.
 
-Hello Samples:
+NOTE: Alpha Version 0.3.0 only supports bare-minimum capabilities for the following [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) [samples](https://github.com/AndyObtiva/glimmer#samples):
 - [Hello, World!](#hello-world)
 - [Hello, Combo!](#hello-combo)
 - [Hello, Computed!](#hello-computed)
@@ -16,13 +16,15 @@ Hello Samples:
 - [Hello, List Multi Selection!](#hello-list-multi-selection)
 - [Hello, Browser!](#hello-browser)
 - [Hello, Tab!](#hello-tab)
-
-Elaborate Samples:
+- [Hello, Custom Widget!](#hello-custom-widget)
+- [Hello, Custom Shell!](#hello-custom-shell)
 - [Login](#login)
 - [Tic Tac Toe](#tic-tac-toe)
+- [Contact Manager](#contact-manager)
 
-Other Glimmer DSL gems:
-- [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
+Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
+- [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Library)
+- [glimmer-dsl-tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (Ruby Desktop Development GUI Library)
 - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
 - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets)
 
@@ -30,6 +32,7 @@ Other Glimmer DSL gems:
 
 The following keywords from [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) have partial support in Opal:
 
+Widgets:
 - `shell`
 - `label`
 - `combo`
@@ -39,54 +42,113 @@ The following keywords from [glimmer-dsl-swt](https://github.com/AndyObtiva/glim
 - `list` & `list(:multi)`
 - `tab_folder`
 - `tab_item`
-- `on_widget_selected`
-- `on_modify_text`
+- `table`
+- `table_column`
+- `message_box`
+- CustomWidget (ability to define any keyword as a custom widget)
+- CustomShell (ability to define any keyword as a custom shell (aka custom window) that opens in a new browser window)
+
+Layouts:
 - `grid_layout`
+- `row_layout`
+- `fill_layout`
 - `layout_data`
 
+Graphics:
+- `color`
+- `font`
+
+Data-Binding/Observers:
+- `bind`
+- `observe`
+- `on_widget_selected`
+- `on_modify_text`
+
+Event loop:
+- `async_exec`
+
 ## Pre-requisites
 
 - Rails 5: [https://github.com/rails/rails/tree/5-2-stable](https://github.com/rails/rails/tree/5-2-stable)
 - Opal 1: [https://github.com/opal/opal-rails](https://github.com/opal/opal-rails)
+- jQuery 3: [https://code.jquery.com/](https://code.jquery.com/) (jQuery 3.5.1 is included in the [glimmer-dsl-opal](https://rubygems.org/gems/glimmer-dsl-opal) gem)
 
 ## Setup
 
-Please follow these instructions to make Glimmer desktop apps work in Opal inside Rails 5
+(NOTE: if you run into issues, keep in mind this is a very early experimental and incomplete alpha. Also, there is a slight chance issues you encounter are fixed in master or some other branch that you could check out instead)
+
+Please install a Rails 5 gem (e.g. `gem install rails -v5.2.4.3` )
 
 Start a new Rails 5 app:
 
 ```
-rails new hello_world
+rails new glimmer_app
 ```
 
-Follow instructions to setup opal with a rails application: config/initializers/assets.rb
+Add the following to `Gemfile`:
 
-Add the following to `Gemfile` (NOTE: if you run into issues, they are probably fixed in master or development/wip branch, you may check out instead):
 ```
 gem 'opal-rails', '~> 1.1.2'
-gem 'opal-async', '~> 1.1.0'
-gem 'opal-browser', '~> 0.2.0'
-gem 'glimmer-dsl-opal', '~> 0.0.7', require: false
+gem 'opal-async', '~> 1.2.0'
+gem 'opal-jquery', '~> 0.4.4'
+gem 'glimmer-dsl-opal', '~> 0.3.0', require: false
+gem 'glimmer-dsl-xml', '~> 1.1.0', require: false
+gem 'glimmer-dsl-css', '~> 1.1.0', require: false
+
 ```
 
-Edit `config/initializers/assets.rb` and add:
+Follow (opal-rails)[https://github.com/opal/opal-rails] instructions, basically the configuration of: config/initializers/assets.rb
+
+Edit `config/initializers/assets.rb` and add the following at the bottom:
 ```
 Opal.use_gem 'glimmer-dsl-opal'
 ```
 
-Add the following line to the top of an empty `app/assets/javascripts/application.js.rb`
+Add the following line to the top of an empty `app/assets/javascripts/application.rb` (replacing `application.js`)
+
+```ruby
+require 'glimmer-dsl-opal' # brings opal and other dependencies automatically
+```
+
+Run:
+
+```
+rails g scaffold welcome
+```
+
+Modify `config/routes.rb`:
 
 ```ruby
-require 'glimmer-dsl-opal' # brings opal and opal browser too
+root to: 'welcome#index'
+```
+
+Add more code to `app/assets/javascripts/application.rb` inside a `Document.ready?` block from one of the samples below or a [Glimmer](https://github.com/AndyObtiva/glimmer) [app](https://github.com/AndyObtiva/glimmer#app)/[custom-shell gem](https://github.com/AndyObtiva/glimmer#custom-shell-gem).
+
+```ruby
+Document.ready? do
+  # require-statement/code goes here.
+end
 ```
 
 ## Samples
 
+Follow the instructions below to try out [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) samples webified via [glimmer-dsl-opal](https://rubygems.org/gems/glimmer-dsl-opal)
+
+Also, this external sample app contains all the samples mentioned below configured inside a Rails 5 [Opal](https://opalrb.com/) app with all the pre-requisites ready to go for convenience:
+
+[https://github.com/AndyObtiva/sample-glimmer-dsl-opal-rails5-app](https://github.com/AndyObtiva/sample-glimmer-dsl-opal-rails5-app)
+
 ### Hello Samples
 
 #### Hello, World!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_world'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 include Glimmer
@@ -96,7 +158,7 @@ shell {
   label {
     text 'Hello, World!'
   }
-}
+}.open
 ```
 
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
@@ -118,37 +180,51 @@ You should see "Hello, World!"
 
 #### Hello, Combo!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_combo'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 class Person
   attr_accessor :country, :country_options
-  
+
   def initialize
-    self.country_options=["", "Canada", "US", "Mexico"]
-    self.country = "Canada"
+    self.country_options = ['', 'Canada', 'US', 'Mexico']
+    reset_country
   end
 
   def reset_country
-    self.country = "Canada"
+    self.country = 'Canada'
   end
 end
 
 class HelloCombo
   include Glimmer
+  
   def launch
     person = Person.new
+    
     shell {
-      composite {
-        combo(:read_only) {
-          selection bind(person, :country)
-        }
-        button {
-          text "Reset"
-          on_widget_selected do
-            person.reset_country
-          end
-        }
+      row_layout(:vertical) {
+        pack false
+      }        
+      
+      text 'Hello, Combo!'      
+      
+      combo(:read_only) {
+        selection bind(person, :country)
+      }
+      
+      button {
+        text 'Reset Selection'
+        
+        on_widget_selected do
+          person.reset_country
+        end
       }
     }.open
   end
@@ -175,7 +251,14 @@ You should see "Hello, Combo!"
 
 #### Hello, Computed!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_computed'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 class HelloComputed
@@ -205,15 +288,15 @@ class HelloComputed
 
   def initialize
     @contact = Contact.new(
-      first_name: "Barry",
-      last_name: "McKibbin",
+      first_name: 'Barry',
+      last_name: 'McKibbin',
       year_of_birth: 1985
     )
   end
 
   def launch
     shell {
-      text "Hello Computed"
+      text 'Hello, Computed!'
       composite {
         grid_layout {
           num_columns 2
@@ -221,44 +304,44 @@ class HelloComputed
           horizontal_spacing 20
           vertical_spacing 10
         }
-        label {text "First &Name: "}
+        label {text 'First &Name: '}
         text {
           text bind(@contact, :first_name)
           layout_data {
-            horizontalAlignment :fill
-            grabExcessHorizontalSpace true
+            horizontal_alignment :fill
+            grab_excess_horizontal_space true
           }
         }
-        label {text "&Last Name: "}
+        label {text '&Last Name: '}
         text {
           text bind(@contact, :last_name)
           layout_data {
-            horizontalAlignment :fill
-            grabExcessHorizontalSpace true
+            horizontal_alignment :fill
+            grab_excess_horizontal_space true
           }
         }
-        label {text "&Year of Birth: "}
+        label {text '&Year of Birth: '}
         text {
           text bind(@contact, :year_of_birth)
           layout_data {
-            horizontalAlignment :fill
-            grabExcessHorizontalSpace true
+            horizontal_alignment :fill
+            grab_excess_horizontal_space true
           }
         }
-        label {text "Name: "}
+        label {text 'Name: '}
         label {
           text bind(@contact, :name, computed_by: [:first_name, :last_name])
           layout_data {
-            horizontalAlignment :fill
-            grabExcessHorizontalSpace true
+            horizontal_alignment :fill
+            grab_excess_horizontal_space true
           }
         }
-        label {text "Age: "}
+        label {text 'Age: '}
         label {
           text bind(@contact, :age, on_write: :to_i, computed_by: [:year_of_birth])
           layout_data {
-            horizontalAlignment :fill
-            grabExcessHorizontalSpace true
+            horizontal_alignment :fill
+            grab_excess_horizontal_space true
           }
         }
       }
@@ -287,7 +370,14 @@ You should see "Hello, Computed!"
 
 #### Hello, List Single Selection!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_list_single_selection'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 class Person 
@@ -327,7 +417,7 @@ HelloListSingleSelection.new.launch
 ```
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
 
-![Glimmer DSL for SWT Hello List Single Selection](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-list-single-selection.png)
+![Glimmer DSL for SWT Hello List Single Selection](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-list-single-selection.png)
 
 Glimmer app on the web (using `glimmer-dsl-opal` gem):
 
@@ -344,7 +434,13 @@ You should see "Hello, List Single Selection!"
 
 #### Hello, List Multi Selection!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_list_multi_selection'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 class Person
@@ -394,7 +490,7 @@ HelloListMultiSelection.new.launch
 ```
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
 
-![Glimmer DSL for SWT Hello List Multi Selection](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-list-multi-selection.png)
+![Glimmer DSL for SWT Hello List Multi Selection](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-list-multi-selection.png)
 
 Glimmer app on the web (using `glimmer-dsl-opal` gem):
 
@@ -411,7 +507,13 @@ You should see "Hello, List Multi Selection!"
 
 #### Hello, Browser!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_browser'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 include Glimmer
@@ -425,7 +527,7 @@ shell {
 ```
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
 
-![Glimmer DSL for SWT Hello Browser](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-browser.png)
+![Glimmer DSL for SWT Hello Browser](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-browser.png)
 
 Glimmer app on the web (using `glimmer-dsl-opal` gem):
 
@@ -442,7 +544,13 @@ You should see "Hello, Browser!"
 
 #### Hello, Tab!
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_tab'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 class HelloTab
@@ -472,8 +580,8 @@ HelloTab.new.launch
 ```
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
 
-![Glimmer DSL for SWT Hello Tab English](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-tab-english.png)
-![Glimmer DSL for SWT Hello Tab French](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-tab-french.png)
+![Glimmer DSL for SWT Hello Tab English](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-tab-english.png)
+![Glimmer DSL for SWT Hello Tab French](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-tab-french.png)
 
 Glimmer app on the web (using `glimmer-dsl-opal` gem):
 
@@ -489,11 +597,280 @@ You should see "Hello, Tab!"
 ![Glimmer DSL for Opal Hello Tab English](images/glimmer-dsl-opal-hello-tab-english.png)
 ![Glimmer DSL for Opal Hello Tab French](images/glimmer-dsl-opal-hello-tab-french.png)
 
+#### Hello, Custom Widget!
+
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_custom_widget'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
+
+```ruby
+# This class declares a `greeting_label` custom widget (by convention)
+class GreetingLabel
+  include Glimmer::UI::CustomWidget
+  
+  # multiple options without default values
+  options :name, :colors
+  
+  # single option with default value
+  option :greeting, default: 'Hello'
+  
+  # internal attribute (not a custom widget option)
+  attr_accessor :color
+  
+  before_body {
+    @font = {height: 24, style: :bold}
+    @color = :black
+  }
+  
+  after_body {
+    return if colors.nil?
+    
+    Thread.new {
+      colors.cycle { |color|
+        async_exec {
+          self.color = color
+        }
+        sleep(1)
+      }
+    }
+  }
+  
+  body {
+    # pass received swt_style through to label to customize (e.g. :center to center text)
+    label(swt_style) {
+      text "#{greeting}, #{name}!"
+      font @font
+      foreground bind(self, :color)
+    }
+  }
+  
+end
+
+# including Glimmer enables the Glimmer DSL syntax, including auto-discovery of the `greeting_label` custom widget
+include Glimmer
+
+shell {
+  fill_layout :vertical
+  
+  minimum_size 215, 215
+  text 'Hello, Custom Widget!'
+  
+  # custom widget options are passed in a hash
+  greeting_label(name: 'Sean')
+  
+  # pass :center SWT style followed by custom widget options hash
+  greeting_label(:center, name: 'Laura', greeting: 'Aloha') #
+  
+  greeting_label(:right, name: 'Rick') {
+    # you can nest attributes under custom widgets just like any standard widget
+    foreground :red
+  }
+  
+  # the colors option cycles between colors for the label foreground every second
+  greeting_label(:center, name: 'Mary', greeting: 'Aloha', colors: [:red, :dark_green, :blue])
+}.open
+```
+Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
+
+![Glimmer DSL for SWT Hello Custom Widget](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-custom-widget.gif)
+
+Glimmer app on the web (using `glimmer-dsl-opal` gem):
+
+Start the Rails server:
+```
+rails s
+```
+
+Visit `http://localhost:3000`
+
+You should see "Hello, Custom Widget!"
+
+![Glimmer DSL for Opal Hello Custom Widget](images/glimmer-dsl-opal-hello-custom-widget.gif)
+
+#### Hello, Custom Shell!
+
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/hello/hello_custom_shell'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
+
+```ruby
+require 'date'
+
+# This class declares an `email_shell` custom shell, aka custom window (by convention)
+# Used to view an email message
+class EmailShell
+  include Glimmer::UI::CustomShell
+  
+  # multiple options without default values  
+  options :date, :subject, :from, :message
+  
+  # single option with default value
+  option :to, default: '"John Irwin" <john.irwin@example.com>'
+  
+  before_body {
+    @swt_style |= swt(:shell_trim, :modeless)
+  }
+  
+  body {
+    # pass received swt_style through to shell to customize it (e.g. :dialog_trim for a blocking shell)
+    shell(swt_style) {
+      grid_layout(2, false)
+      
+      text subject      
+
+      label {
+        text 'Date:'
+      }
+      label {
+        text date
+      }
+
+      label {
+        text 'From:'
+      }
+      label {
+        text from
+      }
+
+      label {
+        text 'To:'
+      }
+      label {
+        text to
+      }
+
+      label {
+        text 'Subject:'
+      }
+      label {
+        text subject
+      }
+
+      label {
+        layout_data(:fill, :fill, true, true) {
+          horizontal_span 2 #TODO implement
+          vertical_indent 10
+        }
+        
+        background :white
+        text message        
+      }
+    }
+  }
+  
+end
+
+class HelloCustomShell
+  # including Glimmer enables the Glimmer DSL syntax, including auto-discovery of the `email_shell` custom widget
+  include Glimmer
+  
+  Email = Struct.new(:date, :subject, :from, :message, keyword_init: true)
+  EmailSystem = Struct.new(:emails, keyword_init: true)
+  
+  def initialize
+    @email_system = EmailSystem.new(
+      emails: [
+        Email.new(date: DateTime.new(2029, 10, 22, 11, 3, 0).strftime('%F %I:%M %p'), subject: '3rd Week Report', from: '"Dianne Tux" <dianne.tux@example.com>', message: "Hello,\n\nI was wondering if you'd like to go over the weekly report sometime this afternoon.\n\nDianne"),
+        Email.new(date: DateTime.new(2029, 10, 21, 8, 1, 0).strftime('%F %I:%M %p'), subject: 'Glimmer Upgrade v100.0', from: '"Robert McGabbins" <robert.mcgabbins@example.com>', message: "Team,\n\nWe are upgrading to Glimmer version 100.0.\n\nEveryone pull the latest code!\n\nRegards,\n\nRobert McGabbins"),
+        Email.new(date: DateTime.new(2029, 10, 19, 16, 58, 0).strftime('%F %I:%M %p'), subject: 'Christmas Party', from: '"Lisa Ferreira" <lisa.ferreira@example.com>', message: "Merry Christmas,\n\nAll office Christmas Party arrangements have been set\n\nMake sure to bring a Secret Santa gift\n\nBest regards,\n\nLisa Ferreira"),
+        Email.new(date: DateTime.new(2029, 10, 16, 9, 43, 0).strftime('%F %I:%M %p'), subject: 'Glimmer Upgrade v99.0', from: '"Robert McGabbins" <robert.mcgabbins@example.com>', message: "Team,\n\nWe are upgrading to Glimmer version 99.0.\n\nEveryone pull the latest code!\n\nRegards,\n\nRobert McGabbins"),
+        Email.new(date: DateTime.new(2029, 10, 15, 11, 2, 0).strftime('%F %I:%M %p'), subject: '2nd Week Report', from: '"Dianne Tux" <dianne.tux@example.com>', message: "Hello,\n\nI was wondering if you'd like to go over the weekly report sometime this afternoon.\n\nDianne"),
+        Email.new(date: DateTime.new(2029, 10, 2, 10, 34, 0).strftime('%F %I:%M %p'), subject: 'Glimmer Upgrade v98.0', from: '"Robert McGabbins" <robert.mcgabbins@example.com>', message: "Team,\n\nWe are upgrading to Glimmer version 98.0.\n\nEveryone pull the latest code!\n\nRegards,\n\nRobert McGabbins"),
+      ]
+    )
+  end
+  
+  def launch
+    shell {
+      grid_layout
+      
+      text 'Hello, Custom Shell!'
+      
+      label {
+        font height: 24, style: :bold
+        text 'Emails:'
+      }
+      
+      label {
+        font height: 18
+        text 'Click an email to view its message'
+      }
+      
+      table {
+        layout_data :fill, :fill, true, true
+      
+        table_column {
+          text 'Date:'
+          width 180
+        }
+        table_column {
+          text 'Subject:'
+          width 180
+        }
+        table_column {
+          text 'From:'
+          width 360
+        }
+        
+        items bind(@email_system, :emails), column_properties(:date, :subject, :from)
+        
+        on_mouse_up { |event|
+          email = event.table_item.get_data
+          Thread.new do
+            async_exec {
+              email_shell(date: email.date, subject: email.subject, from: email.from, message: email.message).open
+            }
+          end
+        }
+      }
+    }.open
+  end  
+end
+
+HelloCustomShell.new.launch
+```
+Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
+
+![Glimmer DSL for SWT Hello Custom Shell](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-custom-shell.png)
+![Glimmer DSL for SWT Hello Custom Shell Email1](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-custom-shell-email1.png)
+![Glimmer DSL for SWT Hello Custom Shell Email2](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-custom-shell-email2.png)
+![Glimmer DSL for SWT Hello Custom Shell Email3](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-hello-custom-shell-email3.png)
+
+Glimmer app on the web (using `glimmer-dsl-opal` gem):
+
+Start the Rails server:
+```
+rails s
+```
+
+Visit `http://localhost:3000`
+
+You should see "Hello, Custom Widget!"
+
+![Glimmer DSL for Opal Hello Custom Shell](images/glimmer-dsl-opal-hello-custom-shell.png)
+![Glimmer DSL for Opal Hello Custom Shell Email1](images/glimmer-dsl-opal-hello-custom-shell-email1.png)
+![Glimmer DSL for Opal Hello Custom Shell Email2](images/glimmer-dsl-opal-hello-custom-shell-email2.png)
+![Glimmer DSL for Opal Hello Custom Shell Email3](images/glimmer-dsl-opal-hello-custom-shell-email3.png)
+
 ### Elaborate Samples
 
 #### Login
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/elaborate/login'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 require "observer"
@@ -586,9 +963,9 @@ Login.new.launch
 ```
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
 
-![Glimmer DSL for SWT Login](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-login.png)
-![Glimmer DSL for SWT Login Filled In](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-login-filled-in.png)
-![Glimmer DSL for SWT Login Logged In](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-login-logged-in.png)
+![Glimmer DSL for SWT Login](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-login.png)
+![Glimmer DSL for SWT Login Filled In](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-login-filled-in.png)
+![Glimmer DSL for SWT Login Logged In](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-login-logged-in.png)
 
 Glimmer app on the web (using `glimmer-dsl-opal` gem):
 
@@ -607,7 +984,13 @@ You should see "Login" dialog
 
 #### Tic Tac Toe
 
-Add the following Glimmer code to `app/assets/javascripts/application.js.rb`
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/elaborate/tic_tac_toe'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
 
 ```ruby
 class TicTacToe
@@ -815,9 +1198,9 @@ TicTacToe.new.open
 ```
 Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
 
-![Glimmer DSL for SWT Tic Tac Toe](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-tic-tac-toe.png)
-![Glimmer DSL for SWT Tic Tac Toe In Progress](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-tic-tac-toe-in-progress.png)
-![Glimmer DSL for SWT Tic Tac Toe Game Over](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-tic-tac-toe-game-over.png)
+![Glimmer DSL for SWT Tic Tac Toe](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-tic-tac-toe.png)
+![Glimmer DSL for SWT Tic Tac Toe In Progress](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-tic-tac-toe-in-progress.png)
+![Glimmer DSL for SWT Tic Tac Toe Game Over](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-tic-tac-toe-game-over.png)
 
 Glimmer app on the web (using `glimmer-dsl-opal` gem):
 
@@ -834,6 +1217,356 @@ You should see "Tic Tac Toe"
 ![Glimmer DSL for Opal Tic Tac Toe In Progress](images/glimmer-dsl-opal-tic-tac-toe-in-progress.png)
 ![Glimmer DSL for Opal Tic Tac Toe Game Over](images/glimmer-dsl-opal-tic-tac-toe-game-over.png)
 
+#### Contact Manager
+
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-dsl-opal/samples/elaborate/contact_manager'
+```
+
+Or add the Glimmer code directly if you prefer to play around with it:
+
+```ruby
+class ContactManager
+  class Contact
+    attr_accessor :first_name, :last_name, :email
+  
+    def initialize(attribute_map)
+      @first_name = attribute_map[:first_name]
+      @last_name = attribute_map[:last_name]
+      @email = attribute_map[:email]
+    end
+  end
+end
+
+class ContactManager
+  class ContactRepository
+    NAMES_FIRST = %w[
+      Liam
+      Noah
+      William
+      James
+      Oliver
+      Benjamin
+      Elijah
+      Lucas
+      Mason
+      Logan
+      Alexander
+      Ethan
+      Jacob
+      Michael
+      Daniel
+      Henry
+      Jackson
+      Sebastian
+      Aiden
+      Matthew
+      Samuel
+      David
+      Joseph
+      Carter
+      Owen
+      Wyatt
+      John
+      Jack
+      Luke
+      Jayden
+      Dylan
+      Grayson
+      Levi
+      Isaac
+      Gabriel
+      Julian
+      Mateo
+      Anthony
+      Jaxon
+      Lincoln
+      Joshua
+      Christopher
+      Andrew
+      Theodore
+      Caleb
+      Ryan
+      Asher
+      Nathan
+      Thomas
+      Leo
+      Isaiah
+      Charles
+      Josiah
+      Hudson
+      Christian
+      Hunter
+      Connor
+      Eli
+      Ezra
+      Aaron
+      Landon
+      Adrian
+      Jonathan
+      Nolan
+      Jeremiah
+      Easton
+      Elias
+      Colton
+      Cameron
+      Carson
+      Robert
+      Angel
+      Maverick
+      Nicholas
+      Dominic
+      Jaxson
+      Greyson
+      Adam
+      Ian
+      Austin
+      Santiago
+      Jordan
+      Cooper
+      Brayden
+      Roman
+      Evan
+      Ezekiel
+      Xaviar
+      Jose
+      Jace
+      Jameson
+      Leonardo
+      Axel
+      Everett
+      Kayden
+      Miles
+      Sawyer
+      Jason
+      Emma
+      Olivia
+    ]
+    NAMES_LAST = %w[
+      Smith
+      Johnson
+      Williams
+      Brown
+      Jones
+      Miller
+      Davis
+      Wilson
+      Anderson
+      Taylor
+    ]
+    def initialize(contacts = nil)
+      @contacts = contacts || 100.times.map do |n|
+        random_first_name_index = (rand*NAMES_FIRST.size).to_i
+        random_last_name_index = (rand*NAMES_LAST.size).to_i
+        first_name = NAMES_FIRST[random_first_name_index]
+        last_name = NAMES_LAST[random_last_name_index]
+        email = "#{first_name}@#{last_name}.com".downcase
+        Contact.new(
+          first_name: first_name,
+          last_name: last_name,
+          email: email
+        )
+      end
+    end
+  
+    def find(attribute_filter_map)
+      @contacts.find_all do |contact|
+        match = true
+        attribute_filter_map.keys.each do |attribute_name|
+          contact_value = contact.send(attribute_name).downcase
+          filter_value = attribute_filter_map[attribute_name].downcase
+          match = false unless contact_value.match(filter_value)
+        end
+        match
+      end
+    end
+  end
+end
+
+class ContactManager
+  class ContactManagerPresenter
+    attr_accessor :results
+    @@contact_attributes = [:first_name, :last_name, :email]
+    @@contact_attributes.each {|attribute_name| attr_accessor attribute_name}
+  
+    def initialize(contact_repository = nil)
+      @contact_repository = contact_repository || ContactRepository.new
+      @results = []
+    end
+  
+    def list
+      self.results = @contact_repository.find({})
+    end
+  
+    def find
+      filter_map = {}
+      @@contact_attributes.each do |attribute_name|
+        filter_map[attribute_name] = self.send(attribute_name) if self.send(attribute_name)
+      end
+      self.results = @contact_repository.find(filter_map)
+      @sort_attribute_name = nil
+      @sort_direction_ascending = nil
+    end
+  
+    def toggle_sort(attribute_name)
+      @sort_attribute_name = attribute_name
+      @sort_direction_ascending = !@sort_direction_ascending
+      sorted_results = self.results.sort_by {|contact| contact.send(attribute_name).downcase}
+      sorted_results = sorted_results.reverse unless @sort_direction_ascending
+      self.results = sorted_results
+    end
+  end
+end
+
+class ContactManager
+  include Glimmer
+
+  def initialize
+    @contact_manager_presenter = ContactManagerPresenter.new
+    @contact_manager_presenter.list
+  end
+
+  def launch
+    shell {
+      text "Contact Manager"
+      composite {
+        composite {
+          grid_layout 2, false
+          label {text "First &Name: "}
+          text {
+            text bind(@contact_manager_presenter, :first_name)
+            on_key_pressed {|key_event|
+              @contact_manager_presenter.find if key_event.keyCode == Glimmer::SWT::SWTProxy[:cr]
+            }
+          }
+          label {text "&Last Name: "}
+          text {
+            text bind(@contact_manager_presenter, :last_name)
+            on_key_pressed {|key_event|
+              @contact_manager_presenter.find if key_event.keyCode == Glimmer::SWT::SWTProxy[:cr]
+            }
+          }
+          label {text "&Email: "}
+          text {
+            text bind(@contact_manager_presenter, :email)
+            on_key_pressed {|key_event|
+              @contact_manager_presenter.find if key_event.keyCode == Glimmer::SWT::SWTProxy[:cr]
+            }
+          }
+          composite {
+            grid_layout 2, false
+            button {
+              text "&Find"
+              on_widget_selected {
+                @contact_manager_presenter.find
+              }
+            }
+            button {
+              text "&List All"
+              on_widget_selected {
+                @contact_manager_presenter.list
+              }
+            }
+          }
+        }
+
+        table(:multi) { |table_proxy|
+          layout_data {
+            horizontal_alignment :fill
+            vertical_alignment :fill
+            grab_excess_horizontal_space true
+            grab_excess_vertical_space true
+            height_hint 200
+          }
+          table_column {
+            text "First Name"
+            width 80
+            on_widget_selected {
+              @contact_manager_presenter.toggle_sort(:first_name)
+            }
+          }
+          table_column {
+            text "Last Name"
+            width 80
+            on_widget_selected {
+              @contact_manager_presenter.toggle_sort(:last_name)
+            }
+          }
+          table_column {
+            text "Email"
+            width 200
+            on_widget_selected {
+              @contact_manager_presenter.toggle_sort(:email)
+            }
+          }
+          items bind(@contact_manager_presenter, :results), column_properties(:first_name, :last_name, :email)
+          on_mouse_down { |event|
+            table_proxy.edit_table_item(event.table_item, event.column_index)
+          }
+        }
+      }
+    }.open
+  end
+end
+
+ContactManager.new.launch
+
+```
+Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
+
+Glimmer DSL for SWT Contact Manager
+
+![Glimmer DSL for SWT Contact Manager](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-contact-manager.png)
+
+Glimmer DSL for SWT Contact Manager Find
+
+![Glimmer DSL for SWT Contact Manager Find](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-contact-manager-find.png)
+
+Glimmer DSL for SWT Contact Manager Edit Started
+
+![Glimmer DSL for SWT Contact Manager Edit Started](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-contact-manager-edit-started.png)
+
+Glimmer DSL for SWT Contact Manager Edit In Progress
+
+![Glimmer DSL for SWT Contact Manager Edit In Progress](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-contact-manager-edit-in-progress.png)
+
+Glimmer DSL for SWT Contact Manager Edit Done
+
+![Glimmer DSL for SWT Contact Manager Edit Done](https://github.com/AndyObtiva/glimmer-dsl-swt/raw/master/images/glimmer-contact-manager-edit-done.png)
+
+Glimmer app on the web (using `glimmer-dsl-opal` gem):
+
+Start the Rails server:
+```
+rails s
+```
+
+Visit `http://localhost:3000`
+
+You should see "Tic Tac Toe"
+
+Glimmer DSL for Opal Contact Manager
+
+![Glimmer DSL for Opal Contact Manager](images/glimmer-dsl-opal-contact-manager.png)
+
+Glimmer DSL for Opal Contact Manager Find
+
+![Glimmer DSL for Opal Contact Manager Find](images/glimmer-dsl-opal-contact-manager-find.png)
+
+Glimmer DSL for Opal Contact Manager Edit Started
+
+![Glimmer DSL for Opal Contact Manager Edit Started](images/glimmer-dsl-opal-contact-manager-edit-started.png)
+
+Glimmer DSL for Opal Contact Manager Edit In Progress
+
+![Glimmer DSL for Opal Contact Manager Edit In Progress](images/glimmer-dsl-opal-contact-manager-edit-in-progress.png)
+
+Glimmer DSL for Opal Contact Manager Edit Done
+
+![Glimmer DSL for Opal Contact Manager Edit Done](images/glimmer-dsl-opal-contact-manager-edit-done.png)
+
 ## Help
 
 ### Issues
@@ -868,5 +1601,11 @@ These features have been suggested. You might see them in a future version of Gl
 
 ## License
 
-Copyright (c) 2020 Andy Maleh.
-See LICENSE.txt for further details.
+[MIT](https://opensource.org/licenses/MIT)
+
+Copyright (c) 2020 - Andy Maleh. 
+See [LICENSE.txt](LICENSE.txt) for further details.
+
+--
+
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=40 />](https://github.com/AndyObtiva/glimmer) Built for [Glimmer](https://github.com/AndyObtiva/glimmer) (Ruby Desktop Development GUI Library).