Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andyobtiva/glimmer-dsl-xml
Glimmer DSL for XML (& HTML)
https://github.com/andyobtiva/glimmer-dsl-xml
dsl dsl-syntax glimmer ruby ruby-gem ruby-library rubygem xml
Last synced: 4 months ago
JSON representation
Glimmer DSL for XML (& HTML)
- Host: GitHub
- URL: https://github.com/andyobtiva/glimmer-dsl-xml
- Owner: AndyObtiva
- License: mit
- Created: 2020-06-12T00:39:02.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-02-25T03:53:50.000Z (12 months ago)
- Last Synced: 2024-04-25T08:20:36.266Z (10 months ago)
- Topics: dsl, dsl-syntax, glimmer, ruby, ruby-gem, ruby-library, rubygem, xml
- Language: Ruby
- Homepage:
- Size: 59.6 KB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# [
](https://github.com/AndyObtiva/glimmer) Glimmer DSL for XML & HTML 1.4.0
[](http://badge.fury.io/rb/glimmer-dsl-xml)
[](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-xml)
[](https://coveralls.io/github/AndyObtiva/glimmer-dsl-xml?branch=master)
[](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-xml/maintainability)
[](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 XML provides Ruby syntax for building XML (eXtensible Markup Language) and HTML documents, included in [Glimmer DSL for Web](https://github.com/AndyObtiva/glimmer-dsl-web) (Ruby in the Browser Web Frontend Framework) to use in Rails Frontend Development. It used to be part of the [Glimmer](https://github.com/AndyObtiva/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-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](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_GUI_DSL_SYNTAX.md#browser-widget).
Otherwise, it is also used in the development of [Glimmer DSL for Opal](https://github.com/AndyObtiva/glimmer-dsl-opal).
Learn more about the differences between various [Glimmer](https://github.com/AndyObtiva/glimmer) DSLs by looking at the **[Glimmer DSL Comparison Table](https://github.com/AndyObtiva/glimmer#glimmer-dsl-comparison-table)**.
## Setup
Please follow these instructions to make the `glimmer` command available on your system.
### Option 1: Direct Install
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](https://github.com/AndyObtiva/glimmer-dsl-swt) or [Glimmer DSL for Opal](https://github.com/AndyObtiva/glimmer-dsl-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.
### Option 2: Bundler
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](https://github.com/AndyObtiva/glimmer-dsl-swt) or [Glimmer DSL for Opal](https://github.com/AndyObtiva/glimmer-dsl-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.
## XML DSL
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 like `xml` (not having body/head) or full HTML document (having body/head), automatically including doctype (``) and surrounding content by the `` tag
- `xml`: renders XML/XHTML content (e.g. `xml {span {'Hello'}; br}.to_s` renders `Hello
`)
- `name_space`: enables namespacing html tags
- `tag`: enables custom tag creation for exceptional cases (e.g. `acme:window` as 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](https://rubygems.org/gems/glimmer-dsl-xml) gem.
Just make sure to require the library and include Glimmer first:
```ruby
require 'glimmer-dsl-xml'
include Glimmer
```
Example (full HTML document):
```ruby
@html = html {
head {
meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
}
body {
h1 { "Hello, World!" }
}
}
puts @html
```
Output:
```
Hello, World!
```
Example (partial HTML fragment):
```ruby
@html = html {
h1 { "Hello, World!" }
}
puts @html
```
Output:
```
Hello, World!
```
Example (basic XML):
```ruby
@xml = xml {
greeting { "Hello, World!" }
}
puts @xml
```
Output:
```
Hello, World!
```
Example (XML namespaces using `name_space` keyword):
```ruby
@xml = name_space(:acme) {
product(:id => "thesis", :class => "document") {
component(:id => "main") {
}
}
}
puts @xml
```
Output:
```
```
Example (XML namespaces using dot operator):
```ruby
@xml = xml {
document.body(document.id => "main") {
}
}
puts @xml
```
Output:
```
```
Example (custom tag):
```ruby
puts tag(:_name => "acme:window") {"This is a window under acme inc."}
```
Output:
```
This is a window under acme inc.
```
### HTML to Glimmer Converter
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:
[bin/html_to_glimmer](/bin/html_to_glimmer)
Usage:
```
html_to_glimmer path_to_html_file
```
Example:
Suppose we have an HTML file called `input.html`:
```html
Welcome
It is good to have you in our platform!
```
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:
```rb
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_s
```
Note 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.
## Glimmer Config
### `xml_attribute_underscore`
(default value: `'_'`)
Calling the following code enables auto-conversion of xml attribute underscores into dashes in `Symbol` attribute names (but not `String` attribute names):
```ruby
Glimmer::Config.xml_attribute_underscore = '-'
```
Example:
```ruby
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
```
```
```
Note that strings are intentionally ignored to enable using underscores when needed.
Example:
```ruby
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
```
```
```
## Multi-DSL Support
Learn more about how to use this DSL alongside other Glimmer DSLs:
[Glimmer Multi-DSL Support](https://github.com/AndyObtiva/glimmer/tree/master#multi-dsl-support)
## Help
### Issues
You may submit [issues](https://github.com/AndyObtiva/glimmer-dsl-xml/issues) on [GitHub](https://github.com/AndyObtiva/glimmer-dsl-xml/issues).
[Click here to submit an issue.](https://github.com/AndyObtiva/glimmer-dsl-xml/issues)
### Chat
If you need live help, try to [](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
## Feature Suggestions
These features have been suggested. You might see them in a future version of Glimmer. You are welcome to contribute more feature suggestions.
[TODO.md](TODO.md)
## Change Log
[CHANGELOG.md](CHANGELOG.md)
## Contributing
[CONTRIBUTING.md](CONTRIBUTING.md)
## Contributors
* [Andy Maleh](https://github.com/AndyObtiva) (Founder)
[Click here to view contributor commits.](https://github.com/AndyObtiva/glimmer-dsl-xml/graphs/contributors)
## License
[MIT](LICENSE.txt)
Copyright (c) 2020-2023 - Andy Maleh.
--
[](https://github.com/AndyObtiva/glimmer) Built for [Glimmer](https://github.com/AndyObtiva/glimmer) (Ruby Desktop Development GUI Library).