Glimmer DSL for XML provides Ruby syntax for building XML (eXtensible Markup Language) and HTML documents, included in Glimmer DSL for Web (Ruby in the Browser Web Frontend Framework) to use in Rails Frontend Development. It used to be part of the Glimmer library (created in 2007), but eventually got extracted into its own project. The Ruby gem also includes an HTML to Glimmer Converter (html_to_glimmer) to automatically convert legacy HTML code into Glimmer DSL syntax.
Within the context of desktop development, Glimmer DSL for XML is useful in providing XML data for the SWT Browser widget.
Otherwise, it is also used in the development of Glimmer DSL for Opal.
Learn more about the differences between various Glimmer DSLs by looking at the Glimmer DSL Comparison Table.
Please follow these instructions to make the glimmer command available on your system.
Run this command to install directly:
gem install glimmer-dsl-xml -v 1.4.0
Note: When using JRuby, jgem is JRuby's version of gem command. RVM allows running gem as an alias in JRuby. Otherwise, you may also run jruby -S gem install ...
Add require 'glimmer-dsl-xml' to your code.
When using with Glimmer DSL for SWT or Glimmer DSL for Opal, make sure it is added after require glimmer-dsl-swt and require glimmer-dsl-opal to give it a lower precedence than them when processed by the Glimmer DSL engine.
That's it! Requiring the gem activates the Glimmer XML DSL automatically.
Add the following to Gemfile (after glimmer-dsl-swt and/or glimmer-dsl-opal if included too):
gem 'glimmer-dsl-xml', '~> 1.4.0'
And, then run:
bundle install
Note: When using JRuby, prefix with jruby -S
Require in your code via Bundler (e.g. require 'bundler'; Bundler.require) or add require 'glimmer-dsl-xml' to your code.
When using with Glimmer DSL for SWT or Glimmer DSL for Opal, make sure it is loaded after glimmer-dsl-swt and glimmer-dsl-opal to give it a lower precedence than them when processed by the Glimmer DSL engine.
That's it! Requiring the gem activates the Glimmer XML DSL automatically.
Simply start with the html, xml, name_space, or tag keyword and add XML/HTML inside its block using Glimmer DSL for XML syntax.
Once done, you may call to_s, to_xml, or to_html to get the formatted XML/HTML output.
Here are all the Glimmer XML DSL top-level keywords:
html: renders partial HTML just likexml(not having body/head) or full HTML document (having body/head), automatically including doctype (<!DOCTYPE html>) and surrounding content by the<html></html>tagxml: renders XML/XHTML content (e.g.xml {span {'Hello'}; br}.to_srenders<span>Hello</span><br />)name_space: enables namespacing html tagstag: enables custom tag creation for exceptional cases (e.g.acme:windowas reserved Ruby keyword) by passing tag name as '_name' attribute
Element properties are typically passed as a key/value hash (e.g. section(id: 'main', class: 'accordion')) . However, for properties like "selected" or "checked", you must leave value nil or otherwise pass in front of the hash (e.g. input(:checked, type: 'checkbox') )
You may try the following examples in IRB after installing the glimmer-dsl-xml gem.
Just make sure to require the library and include Glimmer first:
require 'glimmer-dsl-xml'
include GlimmerExample (full HTML document):
@html = html {
head {
meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
}
body {
h1 { "Hello, World!" }
}
}
puts @htmlOutput:
<!DOCTYPE html><html><head><meta name="viewport" content="width=device-width, initial-scale=2.0" /></head><body><h1>Hello, World!</h1></body></html>
Example (partial HTML fragment):
@html = html {
h1 { "Hello, World!" }
}
puts @htmlOutput:
<h1>Hello, World!</h1>
Example (basic XML):
@xml = xml {
greeting { "Hello, World!" }
}
puts @xmlOutput:
<greeting>Hello, World!</greeting>
Example (XML namespaces using name_space keyword):
@xml = name_space(:acme) {
product(:id => "thesis", :class => "document") {
component(:id => "main") {
}
}
}
puts @xmlOutput:
<acme:product id="thesis" class="document"><acme:component id="main"></acme:component></acme:product>
Example (XML namespaces using dot operator):
@xml = xml {
document.body(document.id => "main") {
}
}
puts @xmlOutput:
<document:body document:id="main"></document:body>
Example (custom tag):
puts tag(:_name => "acme:window") {"This is a window under acme inc."}Output:
<acme:window>This is a window under acme inc.</acme:window>
The Ruby gem includes a HTML to Glimmer converter (html_to_glimmer) to automatically convert legacy HTML code into Glimmer DSL syntax.
Prerequisite: the nokogiri Ruby gem. If not already installed, run gem install nokogiri before using html_to_glimmer.
Script:
Usage:
html_to_glimmer path_to_html_file
Example:
Suppose we have an HTML file called input.html:
<html style='max-height: 100%'>
<body style="max-height: 100%; font: 'Times New Roman', Arial;">
<h1 id="top-header" class="header" data-owner='John "Bonham" Doe'>Welcome</h1>
<p>It is good to have <strong>you</strong> in our <strong><em>platform</em></strong>!</p>
<form action="/owner" method="post">
<input type="text" value="you" />
</form>
</body>
</html>We can run this command:
html_to_glimmer input.html
Printout:
Converting from HTML syntax to Glimmer DSL Ruby syntax for input file: input.html
Converted output file: input.html.glimmer.rb
Output file (input.html.glimmer.rb) is a runnable Ruby file containing Glimmer DSL for XML & HTML syntax:
require 'glimmer-dsl-xml'
include Glimmer
html_document = xml {
html(style: 'max-height: 100%') {
body(style: "max-height: 100%; font: 'Times New Roman', Arial;") {
h1(id: 'top-header', class: 'header', 'data-owner': 'John "Bonham" Doe') {
"Welcome"
}
p {
span {
"It is good to have "
}
strong {
"you"
}
span {
" in our "
}
strong {
em {
"platform"
}
}
span {
"!"
}
}
form(action: '/owner', method: 'post') {
input(type: 'text', value: 'you')
}
}
}
}
puts html_document.to_sNote that text nodes are converted into span nodes as that is the recommended way of including them in Glimmer DSL for XML at the moment.
(default value: '_')
Calling the following code enables auto-conversion of xml attribute underscores into dashes in Symbol attribute names (but not String attribute names):
Glimmer::Config.xml_attribute_underscore = '-'Example:
require 'glimmer-dsl-xml'
Glimmer::Config.xml_attribute_underscore = '-'
include Glimmer
document = html {
body {
video(:data_loop, data_src: "http://videos.org/1.mp4")
}
}
puts document<!DOCTYPE html><html><body><video data-src="http://videos.org/1.mp4" data-loop /></body></html>
Note that strings are intentionally ignored to enable using underscores when needed.
Example:
require 'glimmer-dsl-xml'
Glimmer::Config.xml_attribute_underscore = '-'
include Glimmer
document = html {
body {
video('data_loop', 'data_src' => "http://videos.org/1.mp4")
}
}
puts document<!DOCTYPE html><html><body><video data_src="http://videos.org/1.mp4" data_loop /></body></html>
Learn more about how to use this DSL alongside other Glimmer DSLs:
You may submit issues on GitHub.
Click here to submit an issue.
If you need live help, try to
These features have been suggested. You might see them in a future version of Glimmer. You are welcome to contribute more feature suggestions.
- Andy Maleh (Founder)
Click here to view contributor commits.
Copyright (c) 2020-2023 - Andy Maleh.
--
Built for Glimmer (Ruby Desktop Development GUI Library).