Definitions - Create Renderers and Elements

This module contains helper for defining callables returning HTML elements structures or HTML raw strings directly. They are available in two forms:

  • Macros usable in Hy

  • Decorators usable in both Hy and Python

Definitions Macros

Overview

Use defhtml for defining a callable which wraps its output to html automatically:

;; Use require to import macros
(require [hyccup.defmacros [defhtml]])

(defhtml render-in-div [#* content]
  ['div {'class "container"} (iter content)])
(render-in-div ['ol (gfor x (range 1 4) ['li f"Item {x}"])])
;; "<div class=\"container\">
;;   <ol>
;;     <li>Item 1</li>
;;     <li>Item 2</li>
;;     <li>Item 3</li>
;;   </ol>
;; </div>"

You can pass HTML options:

;; XHTML mode (default)
(defhtml {"mode" "xhtml"} render-in-div [#* content]
  ['div {'class "container"} (iter content)])
(render-in-div ['img {'src "https://foo.bar"}])
;; "<div class=\"container\"><img src=\"https://foo.bar\" /></div>"

;; HTML mode
(defhtml {"mode" "html"} render-in-div [#* content]
  ['div {'class "container"} (iter content)])
(render-in-div ['img {'src "https://foo.bar"}])
;; "<div class=\"container\"><img src=\"https://foo.bar\"></div>"

Use defelem for defining elements. A first optional parameter is added for specifying attributes to merge with returned element’s attributes:

(require [hyccup.defmacros [defelem]])

(defelem link-to [link content]
  ['a {'href link} content])

;; Without attributes dict
(link-to "https://foo.bar" "Awesome link")
;; ['a {'href "https://foo.bar"} "Awesome link"]

;; With attributes
(link-to {'class "some-class"} "https://foo.bar" "Awesome link")
;; ['a {'href "https://foo.bar" 'class "some-class"} "Awesome link"]

API

Source code: hyccup/defmacros.hy

macro(hyccup.defmacros.defelem name #* fbody)

Define a HTML element.

Add to the function signature a first optional dictionary argument. This dictionary will be merged with attributes of the returned element.

macro(hyccup.defmacros.defhtml options name #* fbody)

Define a function passing its output to html implicitely.

HTML Options can be passed as a dict between function name and its arguments list.

Definitions Decorators

Overview

Use defhtml for defining a callable which wraps its output to html automatically:

from hyccup.defdecos import defhtml

@defhtml
def render_in_div(*content):
    return ["div", {"class": "container"}, *content]

render_in_div(["ol", (["li", (f"Item {x}" for x in range(1, 4))])])
# '<div class="container">
#   <ol>
#     <li>Item 1</li>
#     <li>Item 2</li>
#     <li>Item 3</li>
#   </ol>
# </div>'

You can pass HTML options:

# XHTML mode (default)
@defhtml(mode="xhtml")
def render_in_div(*content):
    return ["div", {"class": "container"}, *content]

render_in_div(['img', {'src': 'https://foo.bar'}])
# '<div class="container"><img src="https://foo.bar" /></div>'

# HTML mode
@defhtml(mode="html")
def render_in_div(*content):
    return ["div", {"class": "container"}, *content]

render_in_div(['img', {'src': 'https://foo.bar'}])
# '<div class="container"><img src="https://foo.bar"></div>'

Use defelem for defining elements. A first optional parameter is added for specifying attributes to merge with returned element’s attributes:

from hyccup.defdecos import defelem

@defelem
def link_to(link, content):
    return ['a', {'href': link}, content])

# Without attributes dict
link_to('https://foo.bar', 'Awesome link')
# ['a', {'href': 'https://foo.bar'}, 'Awesome link']

# With attributes
link_to({'class': 'some-class'}, 'https://foo.bar', 'Awesome link')
# ['a {'href': 'https://foo.bar', 'class': 'some-class'} "Awesome link"]

API

Source code: hyccup/defdecos.hy

(hyccup.defdecos.defelem function)

Decorate a function for defining elements using multimethod.

The returned object is a callable with two signature:

  • The original signature of the function

  • The original signature with as first parameter a dict of attributes. This will be merged with attributes of the returned element.

(hyccup.defdecos.defhtml func #** html-options)

Decorate a function for passing its result to html.

Take HTML options as keyword arguments.