DEV Community

Cover image for Using ActiveRecord with SQLite DB in a JRuby Desktop App
Andy Maleh
Andy Maleh

Posted on

Using ActiveRecord with SQLite DB in a JRuby Desktop App

SQLite is the simplest relational database to use from JRuby desktop applications, it is built-in on all platforms (Mac, Windows, and Linux), and it can be utilized conveniently via ActiveRecord, the Rails object-relational mapping library following the Active Record Enterprise Application Architecture Pattern. In fact, I have used it a few years ago to build Are We There Yet?, a small project management app, using Glimmer DSL for SWT and bidirectional data-binding. In this blog post tutorial, I cover how to configure a SQLite database and connect to it using ActiveRecord from within a Ruby desktop application, data-binding the ActiveRecord Model to the GUI View bidirectionally.

are we there yet screenshot

Let us build a simple Contact Manager desktop app to demonstrate how to use a relational database to store contacts in a SQLite database via ActiveRecord.

contact manager screenshot

Requirements:

  1. Store contacts having the following attributes:
    • First Name
    • Last Name
    • Email
    • Phone
    • Street
    • City
    • State/Province
    • Zip/Postal Code
    • Country
  2. List stored contacts
  3. Search stored contacts by any of the contact attributes.
  4. Sort contacts by First Name, Last Name, Email, Phone, or Full Address
  5. Edit a stored contact
  6. Delete a stored contact
  7. Delete all stored contacts

Implementation:

We will use Glimmer DSL for SWT (JRuby Desktop Development GUI Framework) to build the solution. Nonetheless, the same solution could be implemented with Glimmer DSL for LibUI using MRI CRuby, or any of the other Glimmer desktop GUI libraries for that matter.

1- Gem Install

We will start by scaffolding a Ruby desktop application using Glimmer DSL for SWT v4.23.1.4. To do so, the library prerequisites (JDK 18 and JRuby 9.3.4.0) must be setup. Afterwards, you must install the glimmer-dsl-swt gem by running the following command (you can try the latest version if you prefer by leaving the version option out, but it might vary from this tutorial):

gem install glimmer-dsl-swt -v4.23.1.4
Enter fullscreen mode Exit fullscreen mode
% gem install glimmer-dsl-swt -v4.23.1.4
Fetching text-table-1.2.4.gem
Fetching rouge-3.28.0.gem
Fetching super_module-1.4.1.gem
Fetching wisper-2.0.1.gem
Fetching method_source-1.0.0.gem
Fetching tty-screen-0.8.1.gem
Fetching tty-cursor-0.7.1.gem
Fetching tty-reader-0.9.0.gem
Fetching tty-color-0.6.0.gem
Fetching pastel-0.8.0.gem
Fetching tty-prompt-0.23.1.gem
Fetching rake-tui-0.2.3.gem
Fetching awesome_print-1.9.2.gem
Fetching os-1.1.4.gem
Fetching nested_inherited_jruby_include_package-0.3.0.gem
Fetching jruby-win32ole-0.8.5.gem
Fetching facets-3.1.0.gem
Fetching array_include_methods-1.4.0.gem
Fetching glimmer-2.7.3.gem
Fetching puts_debuggerer-0.13.5.gem
Fetching glimmer-dsl-swt-4.23.1.4.gem
Fetching concurrent-ruby-1.1.10.gem
Successfully installed text-table-1.2.4
Successfully installed method_source-1.0.0
Successfully installed super_module-1.4.1
Successfully installed rouge-3.28.0
Successfully installed wisper-2.0.1
Successfully installed tty-screen-0.8.1
Successfully installed tty-cursor-0.7.1
Successfully installed tty-reader-0.9.0
Successfully installed tty-color-0.6.0
Successfully installed pastel-0.8.0
Successfully installed tty-prompt-0.23.1
Successfully installed rake-tui-0.2.3
Successfully installed awesome_print-1.9.2
Successfully installed puts_debuggerer-0.13.5
Successfully installed os-1.1.4
Successfully installed nested_inherited_jruby_include_package-0.3.0
Successfully installed jruby-win32ole-0.8.5
Successfully installed facets-3.1.0
Successfully installed array_include_methods-1.4.0
Successfully installed glimmer-2.7.3
Successfully installed concurrent-ruby-1.1.10

You are ready to use `glimmer` and `girb` commands on Windows and Linux.

On the Mac, run `glimmer-setup` command to complete setup of Glimmer DSL for SWT (it will configure a Mac required jruby option globally `-J-XstartOnFirstThread` so that you do not have to add manually), making `glimmer` and `girb` commands ready for use:

glimmer-setup

Successfully installed glimmer-dsl-swt-4.23.1.4

22 gems installed
Enter fullscreen mode Exit fullscreen mode

If you are running on a Mac machine, run the command mentioned in the post gem installation instructions (unless you have run it before):

glimmer-setup
Enter fullscreen mode Exit fullscreen mode

2- Scaffolding

To scaffold an application called contact_manager with Glimmer DSL for SWT, you can run the following command:

glimmer "scaffold[contact_manager]"
Enter fullscreen mode Exit fullscreen mode

This will generate the files of a Hello, World! application and launch it afterwards. Below is the output, including all the generated files.

% glimmer "scaffold[contact_manager]"
Fetching highline-2.0.3.gem
Fetching rack-2.2.3.gem
Fetching semver2-3.4.2.gem
Fetching kamelcase-0.0.2.gem
Fetching nokogiri-1.13.4-java.gem
Fetching multi_xml-0.6.0.gem
Fetching multi_json-1.15.0.gem
Fetching jwt-2.3.0.gem
Fetching ruby2_keywords-0.0.5.gem
Fetching faraday-retry-1.0.3.gem
Fetching faraday-rack-1.0.0.gem
Fetching faraday-patron-1.0.0.gem
Fetching faraday-net_http-1.0.1.gem
Fetching faraday-net_http_persistent-1.2.0.gem
Fetching multipart-post-2.1.1.gem
Fetching faraday-multipart-1.0.3.gem
Fetching faraday-httpclient-1.0.1.gem
Fetching faraday-excon-1.1.0.gem
Fetching faraday-em_synchrony-1.0.0.gem
Fetching faraday-em_http-1.0.0.gem
Fetching hashie-3.6.0.gem
Fetching thread_safe-0.3.6-java.gem
Fetching descendants_tracker-0.0.4.gem
Fetching public_suffix-4.0.6.gem
Fetching addressable-2.8.0.gem
Fetching github_api-0.19.0.gem
Fetching faraday-1.10.0.gem
Fetching oauth2-1.4.9.gem
Fetching rchardet-1.8.0.gem
Fetching git-1.10.2.gem
Fetching builder-3.2.4.gem
Fetching juwelier-2.4.9.gem
Successfully installed semver2-3.4.2
Successfully installed nokogiri-1.13.4-java
Successfully installed kamelcase-0.0.2
Successfully installed highline-2.0.3
Successfully installed rack-2.2.3
Successfully installed multi_xml-0.6.0
Successfully installed multi_json-1.15.0
Successfully installed jwt-2.3.0
Successfully installed ruby2_keywords-0.0.5
Successfully installed faraday-retry-1.0.3
Successfully installed faraday-rack-1.0.0
Successfully installed faraday-patron-1.0.0
Successfully installed faraday-net_http_persistent-1.2.0
Successfully installed faraday-net_http-1.0.1
Successfully installed multipart-post-2.1.1
Successfully installed faraday-multipart-1.0.3
Successfully installed faraday-httpclient-1.0.1
Successfully installed faraday-excon-1.1.0
Successfully installed faraday-em_synchrony-1.0.0
Successfully installed faraday-em_http-1.0.0
Successfully installed faraday-1.10.0
Successfully installed oauth2-1.4.9
Successfully installed hashie-3.6.0
Successfully installed thread_safe-0.3.6-java
Successfully installed descendants_tracker-0.0.4
Successfully installed public_suffix-4.0.6
Successfully installed addressable-2.8.0
Successfully installed github_api-0.19.0
Successfully installed rchardet-1.8.0
Successfully installed git-1.10.2
Successfully installed builder-3.2.4
Successfully installed juwelier-2.4.9
32 gems installed
irb_chwscreate.gitignore
irb_chwscreateRakefile
irb_chwscreateGemfile
irb_chwscreateLICENSE.txt
irb_chwscreateREADME.markdown
irb_chwscreate.document
irb_chwscreatelib
irb_chwscreatelib/contact_manager.rb
irb_chwscreate.rspec
Juwelier has prepared your gem in ./contact_manager
Created contact_manager/.gitignore
Created contact_manager/.ruby-version
Created contact_manager/.ruby-gemset
Created contact_manager/VERSION
Created contact_manager/LICENSE.txt
Created contact_manager/Gemfile
Created contact_manager/Rakefile
Created contact_manager/app/contact_manager.rb
Created contact_manager/app/contact_manager/view/app_view.rb
Created contact_manager/icons/windows/Contact Manager.ico
Created contact_manager/icons/macosx/Contact Manager.icns
Created contact_manager/icons/linux/Contact Manager.png
Created contact_manager/app/contact_manager/launch.rb
Created contact_manager/bin/contact_manager
jruby-9.3.4.0 - #gemset created /Users/andymaleh/.rvm/gems/jruby-9.3.4.0@contact_manager
jruby-9.3.4.0 - #generating contact_manager wrappers..............
Fetching gem metadata from https://rubygems.org/.........
Resolving dependencies...................
Using rake 13.0.6
Fetching public_suffix 4.0.6
Fetching array_include_methods 1.4.0
Fetching awesome_print 1.9.2
Fetching builder 3.2.4
Installing builder 3.2.4
Installing array_include_methods 1.4.0
Installing awesome_print 1.9.2
Installing public_suffix 4.0.6
Using bundler 2.3.9
Fetching concurrent-ruby 1.1.10
Fetching thread_safe 0.3.6 (java)
Installing concurrent-ruby 1.1.10
Fetching diff-lcs 1.5.0
Installing thread_safe 0.3.6 (java)
Installing diff-lcs 1.5.0
Fetching docile 1.4.0
Installing docile 1.4.0
Fetching facets 3.1.0
Fetching faraday-em_http 1.0.0
Fetching faraday-em_synchrony 1.0.0
Installing faraday-em_http 1.0.0
Installing facets 3.1.0
Installing faraday-em_synchrony 1.0.0
Fetching faraday-excon 1.1.0
Fetching faraday-httpclient 1.0.1
Installing faraday-excon 1.1.0
Installing faraday-httpclient 1.0.1
Fetching multipart-post 2.1.1
Fetching faraday-net_http 1.0.1
Installing multipart-post 2.1.1
Installing faraday-net_http 1.0.1
Fetching faraday-net_http_persistent 1.2.0
Fetching faraday-patron 1.0.0
Fetching faraday-rack 1.0.0
Installing faraday-net_http_persistent 1.2.0
Installing faraday-rack 1.0.0
Installing faraday-patron 1.0.0
Fetching faraday-retry 1.0.3
Installing faraday-retry 1.0.3
Fetching ruby2_keywords 0.0.5
Fetching rchardet 1.8.0
Installing ruby2_keywords 0.0.5
Installing rchardet 1.8.0
Fetching hashie 3.6.0
Fetching jwt 2.3.0
Installing hashie 3.6.0
Installing jwt 2.3.0
Fetching multi_json 1.15.0
Installing multi_json 1.15.0
Fetching multi_xml 0.6.0
Fetching rack 2.2.3
Installing multi_xml 0.6.0
Installing rack 2.2.3
Fetching jruby-win32ole 0.8.5
Fetching nested_inherited_jruby_include_package 0.3.0
Installing nested_inherited_jruby_include_package 0.3.0
Installing jruby-win32ole 0.8.5
Fetching os 1.1.4
Installing os 1.1.4
Fetching tty-color 0.6.0
Fetching tty-cursor 0.7.1
Fetching tty-screen 0.8.1
Installing tty-color 0.6.0
Installing tty-cursor 0.7.1
Installing tty-screen 0.8.1
Fetching wisper 2.0.1
Fetching rouge 3.28.0
Fetching method_source 1.0.0
Installing wisper 2.0.1
Installing method_source 1.0.0
Installing rouge 3.28.0
Fetching text-table 1.2.4
Installing text-table 1.2.4
Fetching highline 2.0.3
Installing highline 2.0.3
Using jar-dependencies 0.4.1
Fetching jruby-jars 9.3.4.0
Fetching jruby-rack 1.1.21
Installing jruby-rack 1.1.21
Fetching semver2 3.4.2
Installing semver2 3.4.2
Fetching racc 1.6.0 (java)
Installing racc 1.6.0 (java)
Fetching rspec-support 3.5.0
Installing rspec-support 3.5.0
Fetching rubyzip 1.3.0
Fetching simplecov-html 0.12.3
Installing rubyzip 1.3.0
Installing simplecov-html 0.12.3
Fetching simplecov_json_formatter 0.1.4
Installing simplecov_json_formatter 0.1.4
Fetching addressable 2.8.0
Fetching puts_debuggerer 0.13.5
Installing puts_debuggerer 0.13.5
Installing addressable 2.8.0
Fetching descendants_tracker 0.0.4
Installing descendants_tracker 0.0.4
Fetching faraday-multipart 1.0.3
Installing faraday-multipart 1.0.3
Fetching git 1.10.2
Fetching pastel 0.8.0
Fetching super_module 1.4.1
Installing git 1.10.2
Installing pastel 0.8.0
Installing super_module 1.4.1
Fetching tty-reader 0.9.0
Fetching psych 4.0.3 (java)
Installing tty-reader 0.9.0
Fetching kamelcase 0.0.2
Installing kamelcase 0.0.2
Installing jruby-jars 9.3.4.0
Installing psych 4.0.3 (java)
Fetching nokogiri 1.13.4 (java)
Fetching rspec-core 3.5.4
Installing rspec-core 3.5.4
  jar dependencies for psych-4.0.3-java.gemspec . . .
Installing gem 'ruby-maven' . . .
Fetching rspec-expectations 3.5.0
Installing rspec-expectations 3.5.0
Installing nokogiri 1.13.4 (java)
Fetching rspec-mocks 3.5.0
Installing rspec-mocks 3.5.0
Fetching simplecov 0.21.2
Installing simplecov 0.21.2
Fetching faraday 1.10.0
Installing faraday 1.10.0
Fetching glimmer 2.7.3
Installing glimmer 2.7.3
Fetching tty-prompt 0.23.1
Installing tty-prompt 0.23.1
Fetching rspec 3.5.0
Fetching warbler 2.0.5
Installing rspec 3.5.0
Installing warbler 2.0.5
Fetching oauth2 1.4.9
Fetching rake-tui 0.2.3
Installing rake-tui 0.2.3
Installing oauth2 1.4.9
Fetching glimmer-dsl-swt 4.23.1.4
Fetching github_api 0.19.0
using maven for the first time results in maven
downloading all its default plugin and can take time.
as those plugins get cached on disk and further execution
of maven is much faster then the first time.
Installing github_api 0.19.0
Installing glimmer-dsl-swt 4.23.1.4
2022-04-11T20:47:17.877-04:00 [main] WARN FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem
Pass '--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED' to enable.
      org.yaml:snakeyaml:1.28:compile
Fetching rdoc 6.4.0
Installing rdoc 6.4.0
Fetching juwelier 2.4.9
Installing juwelier 2.4.9
Bundle complete! 5 Gemfile dependencies, 74 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
Post-install message from glimmer-dsl-swt:
["
You are ready to use `glimmer` and `girb` commands on Windows and Linux.
On the Mac, run `glimmer-setup` command to complete setup of Glimmer DSL for SWT (it will configure a Mac required jruby option globally `-J-XstartOnFirstThread` so that you do not have to add manually), making `glimmer` and `girb` commands ready for use:
glimmer-setup
"]
   exist   .rspec
  create   spec/spec_helper.rb
Created contact_manager/spec/spec_helper.rb
Generated: contact_manager.gemspec
Locking gem jar-dependencies by downloading and storing in vendor/jars...
lock_jars --vendor-dir vendor/jars
Installing gem 'ruby-maven' . . .
Installing gem 'ruby-maven-libs' . . .
using maven for the first time results in maven
downloading all its default plugin and can take time.
as those plugins get cached on disk and further execution
of maven is much faster then the first time.
-- jar root dependencies --
2022-04-11T20:48:09.018-04:00 [main] WARN FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem
Pass '--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED' to enable.
      org.yaml:snakeyaml:1.28:compile
vendor jars:
irb_chws- create vendor/jars/org/yaml/snakeyaml/1.28/snakeyaml-1.28.jar
Jars.lock created
Generating JAR configuration (config/warble.rb) to use with Warbler...
/Users/andymaleh/.rvm/gems/jruby-9.3.4.0@contact_manager/bin/warble
cp /Users/andymaleh/.rvm/gems/jruby-9.3.4.0@contact_manager/gems/warbler-2.0.5/warble.rb config/warble.rb
Generating JAR with Warbler...
/Users/andymaleh/.rvm/gems/jruby-9.3.4.0@contact_manager/bin/warble
application directory `db' does not exist or is not a directory; skipping
application directory `docs' does not exist or is not a directory; skipping
application directory `fonts' does not exist or is not a directory; skipping
application directory `images' does not exist or is not a directory; skipping
application directory `lib' does not exist or is not a directory; skipping
application directory `package' does not exist or is not a directory; skipping
application directory `script' does not exist or is not a directory; skipping
application directory `sounds' does not exist or is not a directory; skipping
application directory `videos' does not exist or is not a directory; skipping
rm -f dist/contact_manager.jar
Creating dist/contact_manager.jar
Generating native executable with jpackage...
Java Version  18 Detected!
jpackage --type app-image --dest 'packages/bundles' --input 'dist' --main-class JarMain --main-jar 'contact_manager.jar' --name 'Contact Manager' --vendor 'Contact Manager' --icon 'icons/macosx/Contact Manager.icns'  --java-options '-XstartOnFirstThread' --mac-package-name 'Contact Manager' --mac-package-identifier 'org.contact_manager.application.contact_manager'  --app-version "1.0.0"  --copyright "Copyright (c) 2022 contact_manager"   --name 'Contact Manager' --description 'Contact Manager'   
Launching Glimmer Application: ./bin/contact_manager
Launching Glimmer Application: /Users/andymaleh/code/contact_manager/app/contact_manager/launch.rb
Enter fullscreen mode Exit fullscreen mode

Contact Manager Hello, World! Scaffolded Application:

scaffolded hello world app screenshot

3- Add ActiveRecord gems to Gemfile

Add the following ActiveRecord gems to Gemfile (we are using the latest versions compatible with JRuby 9.3.4.0, having Ruby 2.6.8 compatibility; ActiveRecord 7 requires a Ruby 2.7.0 compatible implementation, which JRuby does not support yet as of today, but should be supporting in the near future):

gem 'activerecord', '~> 6.1.5'
gem 'activerecord-jdbcsqlite3-adapter', '~> 61.1', :platform => :jruby
Enter fullscreen mode Exit fullscreen mode

Run:

bundle install
Enter fullscreen mode Exit fullscreen mode

Output:

Fetching gem metadata from https://rubygems.org/.......
Resolving dependencies..........................
Using rake 13.0.6
Using concurrent-ruby 1.1.10
Fetching zeitwerk 2.5.4
Fetching minitest 5.15.0
Using public_suffix 4.0.6
Fetching jdbc-sqlite3 3.28.0
Using array_include_methods 1.4.0
Using awesome_print 1.9.2
Using builder 3.2.4
Using bundler 2.3.9
Using thread_safe 0.3.6 (java)
Using diff-lcs 1.5.0
Using docile 1.4.0
Using facets 3.1.0
Using faraday-em_http 1.0.0
Using faraday-em_synchrony 1.0.0
Using faraday-excon 1.1.0
Using faraday-httpclient 1.0.1
Using multipart-post 2.1.1
Using faraday-net_http 1.0.1
Using faraday-net_http_persistent 1.2.0
Using faraday-patron 1.0.0
Using faraday-rack 1.0.0
Using faraday-retry 1.0.3
Using ruby2_keywords 0.0.5
Using rchardet 1.8.0
Using hashie 3.6.0
Using jwt 2.3.0
Using multi_json 1.15.0
Using multi_xml 0.6.0
Using rack 2.2.3
Using jruby-win32ole 0.8.5
Using nested_inherited_jruby_include_package 0.3.0
Using os 1.1.4
Using tty-color 0.6.0
Using tty-cursor 0.7.1
Using tty-screen 0.8.1
Using wisper 2.0.1
Using rouge 3.28.0
Using method_source 1.0.0
Using text-table 1.2.4
Using highline 2.0.3
Using jar-dependencies 0.4.1
Using jruby-jars 9.3.4.0
Using jruby-rack 1.1.21
Using semver2 3.4.2
Using racc 1.6.0 (java)
Using rspec-support 3.5.0
Using rubyzip 1.3.0
Using simplecov-html 0.12.3
Using simplecov_json_formatter 0.1.4
Fetching i18n 1.10.0
Installing zeitwerk 2.5.4
Installing minitest 5.15.0
Installing i18n 1.10.0
Fetching tzinfo 2.0.4
Using addressable 2.8.0
Using puts_debuggerer 0.13.5
Using descendants_tracker 0.0.4
Using glimmer 2.7.3
Using faraday-multipart 1.0.3
Using git 1.10.2
Using pastel 0.8.0
Using tty-reader 0.9.0
Using super_module 1.4.1
Using psych 4.0.3 (java)
Using kamelcase 0.0.2
Using nokogiri 1.13.4 (java)
Using rspec-core 3.5.4
Using rspec-expectations 3.5.0
Using rspec-mocks 3.5.0
Using warbler 2.0.5
Using simplecov 0.21.2
Using faraday 1.10.0
Using tty-prompt 0.23.1
Using rdoc 6.4.0
Using rspec 3.5.0
Using oauth2 1.4.9
Using rake-tui 0.2.3
Using github_api 0.19.0
Using glimmer-dsl-swt 4.23.1.4
Using juwelier 2.4.9
Installing tzinfo 2.0.4
Fetching activesupport 6.1.5
Installing activesupport 6.1.5
Fetching activemodel 6.1.5
Installing activemodel 6.1.5
Fetching activerecord 6.1.5
Installing activerecord 6.1.5
Fetching activerecord-jdbc-adapter 61.1 (java)
Installing jdbc-sqlite3 3.28.0
Installing activerecord-jdbc-adapter 61.1 (java)
Fetching activerecord-jdbcsqlite3-adapter 61.1 (java)
Installing activerecord-jdbcsqlite3-adapter 61.1 (java)
Bundle complete! 7 Gemfile dependencies, 84 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
Enter fullscreen mode Exit fullscreen mode

4- Add an ActiveRecord migration for the contacts database table

Add a db/migrate.rb file under the project root directory with the following content (you can change the ActiveRecord::Migration version depending on the gem version you are using), which will run migrations on every app start, and skip executed migrations on subsequent runs of the app:

migrate_dir = File.expand_path('../migrate', __FILE__)
Dir.glob(File.join(migrate_dir, '**', '*.rb')).each {|migration| require migration}

ActiveRecord::Migration[6.1].descendants.each do |migration| 
  begin
    migration.migrate(:up)
  rescue => e
    raise e unless e.full_message.match(/table "[^"]+" already exists/)
  end
end
Enter fullscreen mode Exit fullscreen mode

And, add a db/migrate/20220411211513_create_contacts.rb (date/time prefix must be the time you created the file) with the following content:

require 'active_record'

class CreateContacts < ActiveRecord::Migration[6.1]
  def change
    create_table :contacts do |t|
      t.string     :first_name
      t.string     :last_name
      t.string     :email
      t.string     :phone
      t.string     :street
      t.string     :city
      t.string     :state_or_province
      t.string     :zip_or_postal_code
      t.string     :country
    end
  end
end
Enter fullscreen mode Exit fullscreen mode

5- Add a SQLite database with ActiveRecord

Create a db/db.rb file with the following content under the project root directory to set up the SQLite database and run migrations afterwards using db/migrate.rb:

require 'active_record'
require 'jdbc/sqlite3'
Jdbc::SQLite3.load_driver
require 'activerecord-jdbcsqlite3-adapter' if defined? JRUBY_VERSION
@connection = ActiveRecord::Base.establish_connection(
  adapter: 'sqlite3',
  database: File.join(Dir.home, 'db/contact_manager.sqlite3')
)
require 'db/migrate'
Enter fullscreen mode Exit fullscreen mode

6- Add the Contact ActiveRecord model

Create app/contact_manager/model/contact.rb and add the Contact model code to it:

require 'db/db'

class Contact < ActiveRecord::Base
  STATES = [ 'AK', 'AL', 'AR', 'AZ', 'CA', 'CO', 'CT', 'DC', 'DE', 'FL', 'GA',
           'HI', 'IA', 'ID', 'IL', 'IN', 'KS', 'KY', 'LA', 'MA', 'MD', 'ME',
           'MI', 'MN', 'MO', 'MS', 'MT', 'NC', 'ND', 'NE', 'NH', 'NJ', 'NM',
           'NV', 'NY', 'OH', 'OK', 'OR', 'PA', 'RI', 'SC', 'SD', 'TN', 'TX',
           'UT', 'VA', 'VT', 'WA', 'WI', 'WV', 'WY']
  PROVINCES = ['NL', 'PE', 'NS', 'NB', 'QC', 'ON', 'MB', 'SK', 'AB', 'BC', 'YT', 'NT', 'NU']

  validates :first_name, presence: true
  validates :last_name, presence: true
  validates :email, format: {with: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, message: 'must be a valid email address'}, allow_blank: true
  validates :phone, format: {with: /\A[(]?[0-9]{3}[)]?[ -\.\/0-9]{7,9}\z/, message: 'must be a valid phone number'}, allow_blank: true
  validates :zip_or_postal_code, format: {with: /\A[a-z0-9][0-9][a-z0-9][ 0-9][a-z0-9][a-z0-9]?[0-9]?\z/i, message: 'must be a valid phone number'}, allow_blank: true
  validate :email_or_phone_is_present

  def address
    address_fields = [street, city, state_or_province, zip_or_postal_code, country]
    address_fields.map { |field| field.blank? ? nil : field }.compact.join(', ')
  end

  def country_options
    ['', 'Canada', 'USA']
  end

  def state_or_province_options
    (PROVINCES + [''] + STATES)
  end

  private

  def email_or_phone_is_present
    if email.blank? && phone.blank?
      errors.add(:email, 'must be present unless phone is present')
      errors.add(:phone, 'must be present unless email is present')
    end
  end
end
Enter fullscreen mode Exit fullscreen mode

7- Add the ContactRepository model

Create app/contact_manager/model/contact_repository.rb and add the ContactRepository model code to it:

require 'singleton'
require 'contact_manager/model/contact'

class ContactRepository
  include Singleton

  def all
    Contact.all
  end

  def search(query_value)
    if query_value.present?
      attribute_names = Contact.new.attributes.keys
      conditions = attribute_names.reduce('') do |conditions, attribute|
        if conditions.blank?
          conditions += "lower(#{attribute}) like ?"
        else
          conditions += " OR lower(#{attribute}) like ?"
        end
      end
      Contact.where(conditions, *(["%#{query_value.downcase}%"]*attribute_names.count))
    else
      all
    end
  end

  def destroy_all_contacts
    Contact.destroy_all
  end
end
Enter fullscreen mode Exit fullscreen mode

8- Add the ContactPresenter model

Create app/contact_manager/model/contact_presenter.rb and add the ContactPresenter model code to it:

require 'contact_manager/model/contact'
require 'contact_manager/model/contact_repository'

# ContactPresenter is an enhanced Controller that also
# enables bidirectional data-binding of contact attributes
class ContactPresenter
  attr_accessor :contacts, :query, :current_contact

  def initialize
    renew_current_contact
    self.contacts = ContactRepository.instance.all

    # Monitor Contact collection changes
    # the after_commit hook executes the block under a different object
    # binding, so we must use `this` to access self
    this = self
    Contact.after_commit(on: [:create, :update, :destroy]) do
      this.contacts = ContactRepository.instance.all
    end
  end

  def query=(query_value)
    @query = query_value
    self.contacts = ContactRepository.instance.search(query_value)
  end

  def renew_current_contact
    self.current_contact = Contact.new
  end

  def save_current_contact
    current_contact.save.tap do |saved|
      renew_current_contact if saved
    end
  end

  def destroy_current_contact
    if current_contact&.persisted?
      current_contact.destroy
      renew_current_contact
    end
  end

  def destroy_all_contacts
    ContactRepository.instance.destroy_all_contacts
  end
end
Enter fullscreen mode Exit fullscreen mode

9- Add the ContactForm custom widget view

Create app/contact_manager/view/contact_form.rb and add the contact_form custom widget view code to it:

class ContactManager
  module View
    class ContactForm
      include Glimmer::UI::CustomWidget

      options :contact_presenter

      body {
        composite {
          grid_layout {
            num_columns 2
            make_columns_equal_width true
            margin_width 0
            margin_height 0
            vertical_spacing 0
          }

          form_column {
            form_field(:first_name)
            form_field(:last_name)
            form_field(:email)
            form_field(:phone)
          }

          form_column {
            form_field(:street)
            form_field(:city)
            form_field(:state_or_province, editor: :combo, editor_args: :read_only, property: :selection)
            form_field(:zip_or_postal_code)
            form_field(:country, editor: :combo, editor_args: :read_only, property: :selection)
          }

          composite { # having a composite ensures padding around button
            layout_data {
              horizontal_span 2
              horizontal_alignment :fill
              grab_excess_horizontal_space true
            }

            grid_layout {
              margin_height 0
            }

            button {
              layout_data {
                horizontal_alignment :fill
                grab_excess_horizontal_space true
              }

              text 'Save Contact'

              on_widget_selected do
                save_contact
              end
            }
          }
        }
      }

      def form_column(&content)
        composite { |the_composite|
          layout_data {
            horizontal_alignment :fill
            vertical_alignment :fill
            grab_excess_horizontal_space true
            grab_excess_vertical_space true
          }

          grid_layout {
            num_columns 2
            make_columns_equal_width false
          }

          content.call(the_composite)
        }
      end

      def form_field(field, editor: :text, editor_args: [], property: :text)
        @form_field_labels ||= {}
        @form_field_labels[field] = label {
          layout_data {
            width_hint 120
          }

          text field.to_s.gsub('_', ' ').titlecase
        }

        @form_field_texts ||= {}
        @form_field_texts[field] = send(editor, *editor_args) {
          layout_data {
            width_hint 150
            horizontal_alignment :fill
            grab_excess_horizontal_space true
          }

          # use nested data-binding to monitor change of contact
          # in addition to contact field
          send(property) <=> [contact_presenter, "current_contact.#{field}"]

          on_key_pressed do |event|
            save_contact if event.keyCode == swt(:cr)
          end
        }
      end

      def save_contact
        if contact_presenter.save_current_contact
          reset_validations
        else
          show_validations
        end
      end

      def reset_validations
        contact_presenter.current_contact.attributes.keys.each do |attribute_name|
          @form_field_labels[attribute_name.to_sym]&.foreground = :black
          @form_field_labels[attribute_name.to_sym]&.tool_tip_text = nil
        end
        focus_first_field
      end

      def show_validations
        contact_presenter.current_contact.errors.errors.each do |error|
          @form_field_labels[error.attribute].foreground = :red
          @form_field_labels[error.attribute].tool_tip_text = error.full_message
        end
      end

      def focus_first_field
        @form_field_texts[:first_name].set_focus
      end
    end
  end
end
Enter fullscreen mode Exit fullscreen mode

10- Add the ContactTable custom widget view

Create app/contact_manager/view/contact_table.rb and add the contact_table custom widget view code to it:

class ContactManager
  module View
    class ContactTable
      include Glimmer::UI::CustomWidget

      options :contact_presenter, :reset_validations_action

      body {
        composite {
          grid_layout {
            margin_height 0
          }

          text(:search) {
            layout_data {
              horizontal_alignment :fill
              grab_excess_horizontal_space true
            }

            text <=> [contact_presenter, :query]
          }

          table {
            layout_data {
              height_hint 250
              horizontal_alignment :fill
              grab_excess_horizontal_space true
              vertical_alignment :fill
              grab_excess_vertical_space true
            }

            table_column {
              text 'First Name'
              width 120
            }
            table_column {
              text 'Last Name'
              width 120
            }
            table_column {
              text 'Email'
              width 180
            }
            table_column {
              text 'Phone'
              width 120
            }
            table_column {
              text 'Address'
              width 320
            }

            # Ensure converting to Array on read because contacts is an ActiveRecord collection,
            # but an Array object is required by Glimmer DSL for SWT table data-binding logic
            items <=> [contact_presenter, :contacts, on_read: :to_a, column_properties: [:first_name, :last_name, :email, :phone, :address]]

            selection <=> [contact_presenter, :current_contact, after_write: reset_validations_action]

            menu {
              menu_item {
                text '&Delete...'

                on_widget_selected do
                  result = message_box(:yes, :no) {
                    text 'Delete'
                    message 'Are you sure you want to delete the selected contact?'
                  }.open
                  contact_presenter.destroy_current_contact if result == swt(:yes)
                end
              }
            }
          }
        }
      }
    end
  end
end
Enter fullscreen mode Exit fullscreen mode

11- Add the ContactManagerMenuBar custom widget view

Create app/contact_manager/view/contact_manager_menu_bar.rb and add the contact_manager_menu_bar custom widget view code to it:

class ContactManager
  module View
    class ContactManagerMenuBar
      include Glimmer::UI::CustomWidget

      ACCELERATOR_KEY = OS.mac? ? :command : :ctrl

      options :contact_presenter, :about_action, :save_contact_action, :reset_validations_action

      body {
        menu_bar {
          menu {
            text '&Contact'

            menu_item {
              text '&New'
              accelerator ACCELERATOR_KEY, :n

              on_widget_selected do
                contact_presenter.renew_current_contact
                reset_validations_action.call
              end
            }

            menu_item {
              text '&Save'
              accelerator ACCELERATOR_KEY, :s

              on_widget_selected do
                save_contact_action.call
              end
            }

            menu_item {
              text '&Delete...'
              accelerator ACCELERATOR_KEY, :d

              on_widget_selected do
                result = message_box(:yes, :no) {
                  text 'Delete'
                  message 'Are you sure you want to delete the selected contact?'
                }.open
                contact_presenter.destroy_current_contact if result == swt(:yes)
              end
            }

            menu_item {
              text 'Dele&te All...'

              on_widget_selected do
                result = message_box(:yes, :no) {
                  text 'Delete All'
                  message 'Are you sure you want to delete all your contacts?'
                }.open
                contact_presenter.destroy_all_contacts if result == swt(:yes)
              end
            }
          }

          menu {
            text '&Help'

            menu_item {
              text '&About...'

              on_widget_selected do
                about_action.call
              end
            }
          }
        }
      }

    end
  end
end
Enter fullscreen mode Exit fullscreen mode

12- Update the AppView

Update app/contact_manager/view/app_view.rb by replacing all code with the following:

require 'contact_manager/model/contact_presenter'

require 'contact_manager/view/contact_manager_menu_bar'
require 'contact_manager/view/contact_form'
require 'contact_manager/view/contact_table'

class ContactManager
  module View
    class AppView
      include Glimmer::UI::Application

      before_body do
        @contact_presenter = ContactPresenter.new

        @display = display {
          on_about do
            display_about_dialog
          end

          on_preferences do
            display_about_dialog
          end
        }
      end

      body {
        shell {
          grid_layout

          image File.join(APP_ROOT, 'icons', 'windows', "Contact Manager.ico") if OS.windows?
          image File.join(APP_ROOT, 'icons', 'linux', "Contact Manager.png") unless OS.windows?
          text "Contact Manager"

          @contact_form = contact_form(contact_presenter: @contact_presenter) {
            layout_data {
              horizontal_alignment :fill
              grab_excess_horizontal_space true
            }
          }

          contact_table(
            contact_presenter: @contact_presenter,
            reset_validations_action: @contact_form.method(:reset_validations),
          ) {
            layout_data {
              horizontal_alignment :fill
              grab_excess_horizontal_space true
              vertical_alignment :fill
              grab_excess_vertical_space true
            }
          }

          contact_manager_menu_bar(
            contact_presenter: @contact_presenter,
            about_action: method(:display_about_dialog),
            save_contact_action: @contact_form.method(:save_contact),
            reset_validations_action: @contact_form.method(:reset_validations),
          )
        }
      }

      def display_about_dialog
        message_box(body_root) {
          text 'About'
          message "Contact Manager #{VERSION}\n\n#{LICENSE}"
        }.open
      end
    end
  end
end
Enter fullscreen mode Exit fullscreen mode

13- Update the ContactManager entry point

Update app/contact_manager.rb by replacing all code with the following:

$LOAD_PATH.unshift(File.expand_path('..', __FILE__))
$LOAD_PATH.unshift(File.expand_path('../..', __FILE__))

begin
  require 'bundler/setup'
  Bundler.require(:default)
rescue
  # this runs when packaged as a gem (no bundler)
  require 'glimmer-dsl-swt'
  # add more gems if needed
  require 'active_record'
  require 'activerecord-jdbcsqlite3-adapter'
end

class ContactManager
  include Glimmer

  APP_ROOT = File.expand_path('../..', __FILE__)
  VERSION = File.read(File.join(APP_ROOT, 'VERSION'))
  LICENSE = File.read(File.join(APP_ROOT, 'LICENSE.txt'))
  Display.app_name = 'Contact Manager'
  Display.app_version = ContactManager::VERSION
end

require 'contact_manager/view/app_view'
Enter fullscreen mode Exit fullscreen mode

14- Replace app icons

Replace scaffolded app icons with the files below:

icon

Mac (icons/macosx/Contact%20Manager.icns)

https://github.com/AndyObtiva/contact_manager/raw/master/icons/macosx/Contact%20Manager.icns

Windows (icons/windows/Contact%20Manager.ico)

https://github.com/AndyObtiva/contact_manager/raw/master/icons/windows/Contact%20Manager.ico

Linux (icons/linux/Contact%20Manager.png)

https://github.com/AndyObtiva/contact_manager/raw/master/icons/linux/Contact%20Manager.png

15- Run

Run with the following command from inside the project directory:

glimmer run
Enter fullscreen mode Exit fullscreen mode

Or use the scaffolded binary script:

./bin/contact_manager
Enter fullscreen mode Exit fullscreen mode

Result:

resulting app animation

16- Package Native Executable

Glimmer DSL for SWT supports packaging native executables using the glimmer package command. To get started with it, follow the packaging and distribution documentation.

You can run the following command on the Mac to package a native executable:

glimmer "package[dmg]"
Enter fullscreen mode Exit fullscreen mode

On windows, you can run the following command assuming you have setup the WiX Toolset prerequisite:

glimmer "package[msi]"
Enter fullscreen mode Exit fullscreen mode

On debian based Linux distros, you can run:

glimmer "package[deb]"
Enter fullscreen mode Exit fullscreen mode

On redhat based Linux distros, you can run:

glimmer "package[rpm]"
Enter fullscreen mode Exit fullscreen mode

Software Architecture & Design

Contact Manager follows the Model-View-Presenter flavor of MVC, so the View communicates to the Model via a Presenter, which is an enhanced Controller that enables bidirectional attribute data-binding between the Model and the View.

The View uses contact_form, contact_table, and contact_manager_menu_bar custom widgets (components).

The Contact Manager graphical user interface leverages the Master-Detail Interface Pattern by displaying a master list via contact_table and allowing navigation by selecting a Contact and displaying its details for editing in contact_form.

contact_table leverages the table widget, which has automatic in-memory sort support. contact_table also comes with a 'Delete...' right-click menu item (aka contextual pop up menu item) for deleting a selected Contact row.

contact_manager_menu_bar provides top menu bar actions like 'New', 'Save', 'Delete...', and 'Delete All...'

The Model layer includes a Contact and ContactRepository (DDD Repository Pattern) in addition to ContactPresenter (which is both a Controller and a Model at a higher level).

Contact follows the Active Record Pattern for Object Relational Mapping to store objects in a SQLite relational database table called contacts via a migration. It also implements ActiveRecord Validations for first_name, last_name, email, phone, and zip_or_postal_code fields.

ContactRepository provides the ability to search through all Contacts using the ActiveRecord Query Interface, triggered indirectly by ContactPresenter when typing into a text field that is on top of the contact_table .

The database is stored at File.join(Dir.home, 'db/contact_manager.sqlite3')

Reference Project at GitHub

A canonical version of the Contact Manager app exists on GitHub:

https://github.com/AndyObtiva/contact_manager

Happy Glimmering!

P.S. One caveat to be aware of is there is currently a reported issue in using the activerecord-jdbcsqlite3-adapter gem on a Mac ARM64 machine. So, please avoid that platform until the issue is fixed.

Discussion (0)