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
Mitchell Hanberg c6d29e592b Bump v0.8.0
2021-08-29 18:11:24 -04:00

5.3 KiB

Actions Status Hex.pm

You are looking at the README for the main branch. The README for the latest stable release is located here.

Temple is a DSL for writing HTML and EEx using Elixir.

You're probably here because you want to use Temple to write Phoenix templates, which is why Temple includes a Phoenix template engine.

Installation

Add temple to your list of dependencies in mix.exs:

def deps do
  [
    {:temple, "~> 0.8.0"},
    {:phoenix_live_view, "~> 0.16"} # if you are using Phoenix LiveView
  ]
end

Goals

Currently Temple has the following things on which it won't compromise.

  • Will only work with valid Elixir syntax.
  • Should always work with normal EEx, as well as Phoenix and Phoenix LiveView.

Usage

Using Temple is as simple as using the DSL inside of an temple/1 block. This returns an EEx string at compile time.

See the documentation for more details.

use Temple

temple do
  h2 do: "todos"

  ul class: "list" do
    for item <- @items do
      li class: "item" do
        div class: "checkbox" do
          div class: "bullet hidden"
        end

        div do: item
      end
    end
  end

  script do: """
  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

Temple components provide an ergonomic API for creating flexible and reusable views. Unlike normal partials, Temple components can take slots, which are similar Vue.

For example, if I were to define a Card component, I would create the following module.

defmodule MyAppWeb.Components.Card do
  import Temple.Component

  render do
    section do
      div do
        slot :header
      end

      div do
        slot :default
      end

      div do
        slot :footer
      end
    end
  end
end

And we could use the component like so

# lib/my_app_web/views/page_view.ex
alias MyAppWeb.Components.Card

# lib/my_app_web/templates/page/index.html.exs
c Card do
  slot :header do
    @user.full_name
  end

  @user.bio

  slot :footer do
    a href: "https://twitter.com/#{@user.twitter}" do
      "@#{@user.twitter}"
    end
    a href: "https://github.com/#{@user.github}" do
      "@#{@user.github}"
    end
  end
end

Phoenix templates

To use temple as a Phoenix Template engine, you'll need to configure the right file extensions with the right Temple engine.

# config.exs
config :phoenix, :template_engines,
  exs: Temple.Engine
  # or for LiveView support
  # this will work for files named like `index.html.lexs`
  # you can enable Elixir syntax highlighting in your editor
  lexs: Temple.LiveViewEngine

# If you're going to be using live_view, make sure to set the `:mode` to `:live_view`.
# This is necessary for Temple to emit markup that is compatible.
config :temple, :mode, :live_view # defaults to normal

# config/dev.exs
config :your_app, YourAppWeb.Endpoint,
  live_reload: [
    patterns: [
      ~r"lib/myapp_web/(live|views)/.*(ex|exs|lexs)$",
      ~r"lib/myapp_web/templates/.*(eex|exs|lexs)$"
    ]
  ]
# app.html.exs

"<!DOCTYPE html>"
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 do: "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 href: "https://hexdocs.pm/phoenix/overview.html"), do: "Get Started"
            end
          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 class: "alert alert-info", role: "alert", do: get_flash(@conn, :info)
      p class: "alert alert-danger", role: "alert", do: get_flash(@conn, :error)

      render @view_module, @view_template, assigns
    end

    script type: "text/javascript", src: Routes.static_path(@conn, "/js/app.js")
  end
end

Tasks

temple.gen.layout

Generates the app layout.

temple.gen.html

Generates the templates for a resource.

Formatter

To include Temple's formatter configuration, add :temple to your .formatter.exs.

[
  import_deps: [:temple],
  inputs: ["*.{ex,exs}", "priv/*/seeds.exs", "{config,lib,test}/**/*.{ex,exs,lexs}"],
]