glimmer-dsl-opal 0.0.8 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a67315f8276add7f19a24f488c635567a39fe798e7e21e49ce23de2aeb6c0d2
-  data.tar.gz: e667498792a2522e9271a04ccd2051396c778e528dd77fbb593c6369eee971e2
+  metadata.gz: 1d32ed10e3cc93c0f4bde45e35265071c281d73b4371e68306dccbb3e3406e05
+  data.tar.gz: 421daff761291fa3e118d090c450378ab5291f640ed5d81292560d1d8df8736b
 SHA512:
-  metadata.gz: 02db0846e7e3b430387e693aa4981c2f01636a01b5ed5ba32646cbdac15991604ccbd5efa4d8e8b837027c69861c28b8d1917f5bef792121de9be8b86584e064
-  data.tar.gz: 5d07f4b44c97c81bcf554b18d423e0007efe14bf8cdaa8529f0c295581518654a94989dcc1a0e921e8626a7ca3ca243f572a4d163f3e4bd450fe81684303dae2
+  metadata.gz: 220ad6c819df436720e3756b9cef24a74ced1f6c1a14aa7ed5604b09b949a8badc99bbbfb1ce5a048b80c35bde882d0f0136e788dc07a54c9071ebaa9c72a680
+  data.tar.gz: 80c1d6150624d0095ec7965f060e572841e1a7446b664c4741bd553302a805a051593084e495ccee472e66865e398f77443c5d91253f26fa3320b8fc9d9e168a

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Change Log
 
+## 0.4.0
+
+- Support `display` keyword representing an SWT Display
+- Support display `on_swt_keydown` event listener (display-wide widget observer)
+- Support `DisplayProxy#shells` method keeping track of open shell
+- Make a custom shell open in the same window if there is no shell open already
+- Support `sync_exec` keyword as just an alias to `async_exec`
+- Provide a makeshift require for 'glimmer-dsl-swt' that requires 'glimmer-dsl-opal' instead
+- Fake APIs on the web for OS.os?, File.read, Display.setAppName, Display.setAppVersion
+- Provide a minimal URI class that supports URI::encode_www_form_component and URI::decode_www_form_component from Ruby
+
+## 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

data/README.md

@@ -1,12 +1,17 @@
-# <img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=65 /> Glimmer DSL for Opal 0.0.8 (Webify 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.4.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 DSL for Opal is a web GUI adaptor for webifying [Glimmer](https://github.com/AndyObtiva/glimmer) desktop apps (i.e. apps built with [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/) and [Opal](https://opalrb.com/) without changing a line of code. Apps may then be custom-styled for the web via standard CSS.
+[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. 
+
+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.
+
+NOTE: Alpha Version 0.4.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:
 
-NOTE: Alpha Version 0.0.8 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)
@@ -14,19 +19,38 @@ NOTE: Alpha Version 0.0.8 only supports bare-minimum capabilities for the follow
 - [Hello, List Multi Selection!](#hello-list-multi-selection)
 - [Hello, Browser!](#hello-browser)
 - [Hello, Tab!](#hello-tab)
+- [Hello, Custom Widget!](#hello-custom-widget)
+- [Hello, Custom Shell!](#hello-custom-shell)
+
+Elaborate:
+
 - [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)
+External:
+
+- [Glimmer Calculator](#glimmer-calculator)
+
+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)
 
+## Background
+
+The idea behind Glimmer DSL for Opal is that you start by having a [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) desktop app that communicates with a Rails API for any web/cloud concerns. The GUI DSL is very simple in Glimmer DSL for SWT. Once the app is built. You simply embed it in a Rails app as a one line require statement after adding the Glimmer DSL for Opal gem, and BOOM, it just works on the web inside a web browser with the same server/client communication you had in the desktop app (I am working on adding minimal support for net/http in Opal so that desktop apps that use it continue to work in a web browser).
+
+Part of the idea is that web browsers just render GUI widgets similar to those of a desktop app (after all a web browser is a desktop app), so whether you run your GUI on the desktop or on the web should just be a low-level concern, hopefully automated completely with Glimmer DSL for Opal.
+
+Last but not least, you would likely want some special branding on the web, so you can push that off to a web designer who would be more than happy to do the web graphic design and customize the look and feel with pure CSS (no need for programming with Ruby or JavaScript). This enables a clean separation of concerns and distribution of tasks among developers and designers, let alone saving effort on the web GUI by reusing the desktop GUI as a base right off the bat.
+
 ## Supported Glimmer DSL Keywords
 
 The following keywords from [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) have partial support in Opal:
 
+Widgets:
 - `shell`
 - `label`
 - `combo`
@@ -39,38 +63,61 @@ The following keywords from [glimmer-dsl-swt](https://github.com/AndyObtiva/glim
 - `table`
 - `table_column`
 - `message_box`
+- Glimmer::UI::CustomWidget: ability to define any keyword as a custom widget
+- Glimmer::UI::CustomShell: ability to define any keyword as a custom shell (aka custom window) that opens in a new browser window (tab) automatically unless there is no shell open in the current browser window (tab)
+
+Layouts:
+- `grid_layout`
+- `row_layout`
+- `fill_layout`
+- `layout_data`
+
+Graphics:
+- `color`
+- `font`
+
+Data-Binding/Observers:
+- `bind`
+- `observe`
 - `on_widget_selected`
 - `on_modify_text`
-- `observe`
-- `bind`
+
+Event loop:
+- `display`
 - `async_exec`
-- `grid_layout`
-- `layout_data`
 
 ## 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
 
-(NOTE: if you run into issues, they are probably fixed in master or development/wip branch, you may check out instead)
+(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` )
+Please install a Rails 5 gem: 
+
+```
+gem install rails -v5.2.4.4
+```
 
 Start a new Rails 5 app:
 
 ```
-rails new glimmer_app
+rails new glimmer_app_server
 ```
 
 Add the following to `Gemfile`:
 
 ```
 gem 'opal-rails', '~> 1.1.2'
-gem 'opal-async', '~> 1.1.0'
-gem 'opal-browser', '~> 0.2.0'
-gem 'glimmer-dsl-opal', '~> 0.0.8', require: false
+gem 'opal-async', '~> 1.2.0'
+gem 'opal-jquery', '~> 0.4.4'
+gem 'glimmer-dsl-opal', '~> 0.4.0', require: false
+gem 'glimmer-dsl-xml', '~> 1.1.0', require: false
+gem 'glimmer-dsl-css', '~> 1.1.0', require: false
+
 ```
 
 Follow (opal-rails)[https://github.com/opal/opal-rails] instructions, basically the configuration of: config/initializers/assets.rb
@@ -80,21 +127,71 @@ Edit `config/initializers/assets.rb` and add the following at the bottom:
 Opal.use_gem 'glimmer-dsl-opal'
 ```
 
+Run:
+
+```
+rails g scaffold welcome
+```
+
+Modify `config/routes.rb`:
+
+```ruby
+root to: 'welcomes#index'
+```
+
 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 opal browser too
+require 'glimmer-dsl-opal' # brings opal and other dependencies automatically
 ```
 
-Add more code to `app/assets/javascripts/application.rb` from one of the samples below or require a [Glimmer](https://github.com/AndyObtiva/glimmer) app/[custom-shell](https://github.com/AndyObtiva/glimmer#custom-shell-gem) gem.
+Open a `Document.ready?` block and add inside it Glimmer GUI DSL code or a require statement for one of the samples below.
+
+```ruby
+Document.ready? do
+  # require-statement/code goes here.
+end
+```
+
+Example to confirm setup is working:
+
+```ruby
+Document.ready? do
+  include Glimmer
+  
+  shell {
+    fill_layout
+    text 'Example to confirm setup is working'
+    label {
+      text "Welcome to Glimmer DSL for Opal!"
+      foreground :red
+      font height: 24
+    }
+  }.open
+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)
+
+Some of the screenshots might be out of date with updates done to samples in both [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) and [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal).
+
 ### Hello Samples
 
 #### Hello, World!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -126,37 +223,51 @@ You should see "Hello, World!"
 
 #### Hello, Combo!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -183,7 +294,14 @@ You should see "Hello, Combo!"
 
 #### Hello, Computed!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -213,15 +331,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
@@ -229,44 +347,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
           }
         }
       }
@@ -295,7 +413,14 @@ You should see "Hello, Computed!"
 
 #### Hello, List Single Selection!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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 
@@ -335,7 +460,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):
 
@@ -352,7 +477,13 @@ You should see "Hello, List Single Selection!"
 
 #### Hello, List Multi Selection!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -402,7 +533,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):
 
@@ -419,7 +550,13 @@ You should see "Hello, List Multi Selection!"
 
 #### Hello, Browser!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -433,7 +570,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):
 
@@ -450,7 +587,13 @@ You should see "Hello, Browser!"
 
 #### Hello, Tab!
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -480,8 +623,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):
 
@@ -497,11 +640,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.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"
@@ -594,9 +1006,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):
 
@@ -615,7 +1027,13 @@ You should see "Login" dialog
 
 #### Tic Tac Toe
 
-Add the following Glimmer code to `app/assets/javascripts/application.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
@@ -823,9 +1241,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):
 
@@ -844,7 +1262,13 @@ You should see "Tic Tac Toe"
 
 #### Contact Manager
 
-Add the following Glimmer code to `app/assets/javascripts/application.rb`
+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
@@ -962,104 +1386,6 @@ class ContactManager
       Jason
       Emma
       Olivia
-      Ava
-      Isabella
-      Sophia
-      Charlotte
-      Mia
-      Amelia
-      Harper
-      Evelyn
-      Abigail
-      Emily
-      Elizabeth
-      Mila
-      Ella
-      Avery
-      Sofia
-      Camila
-      Aria
-      Scarlett
-      Victoria
-      Madison
-      Luna
-      Grace
-      Chloe
-      Penelope
-      Layla
-      Riley
-      Zoey
-      Nora
-      Lily
-      Eleanor
-      Hannah
-      Lillian
-      Addison
-      Aubrey
-      Ellie
-      Stella
-      Natalie
-      Zoe
-      Leah
-      Hazel
-      Violet
-      Aurora
-      Savannah
-      Audrey
-      Brooklyn
-      Bella
-      Claire
-      Skylar
-      Lucy
-      Paisley
-      Everly
-      Anna
-      Caroline
-      Nova
-      Genesis
-      Emilia
-      Kennedy
-      Samantha
-      Maya
-      Willow
-      Kinsley
-      Naomi
-      Aaliyah
-      Elena
-      Sarah
-      Ariana
-      Allison
-      Gabriella
-      Alice
-      Madelyn
-      Cora
-      Ruby
-      Eva
-      Serenity
-      Autumn
-      Adeline
-      Hailey
-      Gianna
-      Valentina
-      Isla
-      Eliana
-      Quinn
-      Nevaeh
-      Ivy
-      Sadie
-      Piper
-      Lydia
-      Alexa
-      Josephine
-      Emery
-      Julia
-      Delilah
-      Arianna
-      Vivian
-      Kaylee
-      Sophie
-      Brielle
-      Madeline
     ]
     NAMES_LAST = %w[
       Smith
@@ -1074,7 +1400,7 @@ class ContactManager
       Taylor
     ]
     def initialize(contacts = nil)
-      @contacts = contacts || 1000.times.map do |n|
+      @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]
@@ -1235,23 +1561,23 @@ Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObt
 
 Glimmer DSL for SWT Contact Manager
 
-![Glimmer DSL for SWT Contact Manager](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-contact-manager.png)
+![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/raw/master/images/glimmer-contact-manager-find.png)
+![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/raw/master/images/glimmer-contact-manager-edit-started.png)
+![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/raw/master/images/glimmer-contact-manager-edit-in-progress.png)
+![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/raw/master/images/glimmer-contact-manager-edit-done.png)
+![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):
 
@@ -1284,6 +1610,39 @@ 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)
 
+### External Samples
+
+#### Glimmer Calculator
+
+Add the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem to `Gemfile` (without requiring):
+
+```
+gem 'glimmer-cs-calculator', require: false
+```
+
+Add the following require statement to `app/assets/javascripts/application.rb`
+
+```ruby
+require 'glimmer-cs-calculator/launch'
+```
+
+Glimmer app on the desktop (using the [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
+
+![Glimmer Calculator Linux](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-screenshot-linux.png)
+
+Glimmer app on the web (using `glimmer-dsl-opal` gem):
+
+Start the Rails server:
+```
+rails s
+```
+
+Visit `http://localhost:3000`
+
+You should see "Glimmer Calculator"
+
+![Glimmer Calculator Opal](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-screenshot-opal.png)
+
 ## Help
 
 ### Issues
@@ -1318,5 +1677,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).