https://github.com/michaeltelford/yart
Yet Another Ruby Templater (YART) turns plain Ruby into HTML, making it fun to write webpages
https://github.com/michaeltelford/yart
html ruby template-engine
Last synced: about 1 month ago
JSON representation
Yet Another Ruby Templater (YART) turns plain Ruby into HTML, making it fun to write webpages
- Host: GitHub
- URL: https://github.com/michaeltelford/yart
- Owner: michaeltelford
- License: mit
- Created: 2021-07-27T14:28:20.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-11T13:32:00.000Z (almost 5 years ago)
- Last Synced: 2024-04-25T05:40:40.062Z (about 2 years ago)
- Topics: html, ruby, template-engine
- Language: Ruby
- Homepage:
- Size: 43 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# YART
*Yet Another Ruby Templater* turns plain Ruby into HTML making it fun to write webpages.
- YART provides an intuitive DSL that feels natural to use and removes the boiler plate from writing HTML
- YART has zero runtime dependencies and around 120 lines of code
- YART is fully unit tested
## Example Usage
> login.html
```ruby
require "yart"
YART.parse do
form action: "/auth" do
input type: :email, placeholder: "Email Address", required: true, close: true
input type: :password, placeholder: "Password", required: true, close: true
button(type: :submit, id: :login) { "Login" }
end
end
```
Which renders:
```html
Login
```
Note that the above HTML snippet is *prettified* for demonstration. The actual generated HTML will be *minified*.
## Installation
Requires Ruby `>= 2.7`
### RubyGems
$ gem install yart
### Bundler
$ bundle add yart
## API
The best way to fully demonstrate the YART API is with a more complex example:
```ruby
require 'yart'
YART.parse do
element "!DOCTYPE", html: true, close: true # Or just call `doctype`
html lang: :en do
head do
title { "YART API" }
end
body do
h1 { "Use a block to return a String of innerText or more elements" }
div data_test_id: "String attribute values will be parsed as is" do
h2(data_x: :sub_heading) { "Symbol attribute keys/values will be kebab-cased" }
text { "Set the div's innerText, before and/or after its child elements" }
p(class: [:content, :italic_text], id: :paragraph) do
"You can pass an array of attribute values and they will be space separated"
end
end
footer # Render an empty element
end
end
end
```
Which renders, minifies and returns the following HTML5 from `YART.parse`:
```html
YART API
Use a block to return a String of innerText or more elements
Symbol attribute keys/values will be kebab-cased
Set the div's innerText, before and/or after its child elements
You can pass an array of attribute values and they will be space separated
```
Main points to note:
- Pass a block to `YART.parse` and it will render and return a HTML `String`.
- Create the HTML document hierarchy using element calls and blocks.
- Call the element as it's named in HTML, e.g. `h1`, `div`, `p` etc. This works as long as it's lowercase.
- Call `element` when you need to render the *raw* element name (case insensitive) e.g. `!DOCTYPE`.
- Pass the element's attributes as a `Hash` argument.
- Pass a block to return a `String` of `innerText` or more DSL calls (which will eventually return a `String`).
- An element doesn't require attributes or even a block. Where a block is absent, an empty element will be rendered.
- Use the `text` method to render the `innerText` of the element when it consists of *both* inner text *and* child elements.
- An attribute key or value of type `Symbol` will be parsed, converting `snake_case` to `kebab-case`.
- An attribute *value* of type `String` will be parsed as is (not modified in any way).
- An attribute *value* of `true` renders the attribute key without a value e.g. `input required: true` renders ``.
- Several attibute *values* can be rendered by passing an `Array` e.g. `p class: [:para, :italic]`. The values will be rendered space separated.
- Attribute *values* containing illegal characters (like quotes etc.) will be escaped in the rendered HTML.
- The attribute `close: true` is special and tells the parser to auto-close the element (because it's empty).
- Use the convenience methods `doctype`, `javascript`, `stylesheet` and `br` as needed.
## Markdown
If you're creating a site with a lot of static textual content, check out the [static_site_builder](https://github.com/michaeltelford/static_site_builder) gem. It can render HTML sites built using Markdown and it fully supports YART; meaning you can write your text in Markdown and your forms etc in YART, never needing to touch HTML.
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/michaeltelford/yart. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/michaeltelford/yart/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
Everyone interacting in the YART project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/michaeltelford/yart/blob/master/CODE_OF_CONDUCT.md).