This repository has been archived on 2023-08-07. You can view files and clone it, but cannot push or open issues or pull requests.
temple/README.md

165 lines
4.1 KiB
Markdown
Raw Normal View History

2019-07-04 04:16:37 +00:00
# ![](temple.png)
2019-04-15 01:44:39 +00:00
2019-07-02 02:48:51 +00:00
[![Build Status](https://travis-ci.com/mhanberg/temple.svg?branch=master)](https://travis-ci.com/mhanberg/temple)
2019-07-04 02:05:50 +00:00
[![Hex.pm](https://img.shields.io/hexpm/v/temple.svg)](https://hex.pm/packages/temple)
2019-06-30 18:39:05 +00:00
2019-07-02 02:48:51 +00:00
Temple is a DSL for writing HTML using Elixir.
2019-06-30 18:39:05 +00:00
2019-07-02 02:48:51 +00:00
You're probably here because you want to use Temple to write Phoenix templates, which is why Temple includes a [Phoenix template engine](#phoenix-templates) and Temple-compatible [Phoenix form helpers](#phoenixhtml).
2019-04-15 01:44:39 +00:00
## Installation
2019-07-04 02:05:50 +00:00
Add `temple` to your list of dependencies in `mix.exs`:
2019-04-15 01:44:39 +00:00
```elixir
def deps do
2019-07-04 02:05:50 +00:00
[{:temple, "~> 0.1.0"}]
2019-04-15 01:44:39 +00:00
end
```
2019-06-30 18:39:05 +00:00
## Usage
2019-07-09 02:29:41 +00:00
Using Temple is a as simple as using the DSL inside of an `temple/1` block. This returns a safe result of the form `{:safe, html_string}`.
2019-07-04 02:05:50 +00:00
See the [documentation](https://hexdocs.pm/temple/0.1.0/Temple.Tags.html) for more details.
2019-06-30 18:39:05 +00:00
```elixir
2019-07-02 02:48:51 +00:00
use Temple
2019-06-30 18:39:05 +00:00
2019-07-09 02:29:41 +00:00
temple do
2019-06-30 18:39:05 +00:00
h2 "todos"
ul class: "list" do
for item <- @items do
li class: "item" do
div class: "checkbox" do
div class: "bullet hidden"
end
div item
end
end
end
script """
function toggleCheck({currentTarget}) {
currentTarget.children[0].children[0].classList.toggle("hidden");
}
let items = document.querySelectorAll("li");
Array.from(items).forEach(checkbox => checkbox.addEventListener("click", toggleCheck));
"""
end
```
### Components
2019-07-02 02:48:51 +00:00
Temple provides an API for creating custom components that act as custom HTML elements.
2019-06-30 18:39:05 +00:00
These components can be given `props` that are available inside the component definition as module attributes. The contents of a components `do` block are available as a special `@children` attribute.
2019-07-04 02:05:50 +00:00
See the [documentation](https://hexdocs.pm/temple/0.1.0/Temple.html#defcomponent/2) for more details.
2019-06-30 18:39:05 +00:00
```elixir
defcomponent :flex do
div id: @id, class: "flex" do
@children
end
end
2019-07-09 02:29:41 +00:00
temple do
2019-06-30 18:39:05 +00:00
flex id: "my-flex" do
div "Item 1"
div "Item 2"
div "Item 3"
end
end
```
### Phoenix.HTML
2019-04-15 01:44:39 +00:00
2019-07-02 02:48:51 +00:00
Temple provides macros for working with the helpers provided by the [Phoenix.HTML](https://www.github.com/phoenixframework/phoenix_html) package.
2019-06-30 18:39:05 +00:00
2019-07-02 02:48:51 +00:00
Most of the macros are purely wrappers, while the semantics of some are changed to work with Temple.
2019-06-30 18:39:05 +00:00
2019-07-04 02:05:50 +00:00
See the [documentation](https://hexdocs.pm/temple/0.1.0/Temple.Form.html#content) for more details.
2019-06-30 18:39:05 +00:00
```elixir
2019-07-09 02:29:41 +00:00
temple do
2019-06-30 18:39:05 +00:00
form_for @conn, Routes.some_path(@conn, :create) do
text_input form, :name
end
end
```
### Phoenix templates
Add the templating engine to your Phoenix configuration.
2019-07-04 02:05:50 +00:00
See the [documentation](https://hexdocs.pm/temple/0.1.0/Temple.Engine.html#content) for more details.
2019-06-30 18:39:05 +00:00
```elixir
# config.exs
2019-07-02 02:48:51 +00:00
config :phoenix, :template_engines, exs: Temple.Engine
2019-06-30 18:39:05 +00:00
# your_app_web.ex
def view do
quote do
# ...
2019-07-02 02:48:51 +00:00
use Temple # Replaces the call to import Phoenix.HTML
2019-06-30 18:39:05 +00:00
end
end
```
```elixir
# app.html.exs
html lang: "en" do
head do
meta charset: "utf-8"
meta http_equiv: "X-UA-Compatible", content: "IE=edge"
meta name: "viewport", content: "width=device-width, initial-scale=1.0"
title "YourApp · Phoenix Framework"
link rel: "stylesheet", href: Routes.static_path(@conn, "/css/app.css")
end
body do
header do
section class: "container" do
nav role: "navigation" do
ul do
li do: a("Get Started", href: "https://hexdocs.pm/phoenix/overview.html")
end
end
a href: "http://phoenixframework.org/", class: "phx-logo" do
img src: Routes.static_path(@conn, "/images/phoenix.png"),
alt: "Phoenix Framework Logo"
end
end
end
main role: "main", class: "container" do
p get_flash(@conn, :info), class: "alert alert-info", role: "alert"
p get_flash(@conn, :error), class: "alert alert-danger", role: "alert"
partial render(@view_module, @view_template, assigns)
end
script type: "text/javascript", src: Routes.static_path(@conn, "/js/app.js")
end
end
```
### Formatter
To include Temple's formatter configuration, add `:temple` to your `.formatter.exs`.
```elixir
[
import_deps: [:temple],
inputs: ["*.{ex,exs}", "priv/*/seeds.exs", "{config,lib,test}/**/*.{ex,exs}"],
]
```