Hiccup Server Components: Built in components

:ux/css-classes

;; Component signatures

[:ux/css-classes & css-classes]
[:ux/css-classes variable-substitution-map & css-classes]

Constructs a list of one or more css classes that can be used as the "class" attribute of HTML elements.

Optionally, if the first parameter (variable-substitution-map) is a map, it will be used for variable substitution in subsequent parameters which represent css classes.

Variable substitution supports the same options as the :ux/string-template component.

The variable list of css classes provided can be keywords (single or period seperated) or strings (space, comma or period seperated) and result in a consistent, space separated string that represents the css classes of an HTML element.

Ignores nils and blank strings allowing for conditional construction of css classes.

Examples:

Dot seperated strings:

[:div {:class [:ux/css-classes "one.two.three.four"]} "This is a test"]

HTML:

<div class="one two three four">This is a test</div>

Comma seperated strings:

[:div
 {:class [:ux/css-classes "one, two, three, four"]}
 "This is a test"]

HTML:

<div class="one two three four">This is a test</div>

Ignores nils and blank strings:

[:a
 {:class
  [:ux/css-classes
   :sidebar-link
   :menu-link
   nil
   ""
   " "
   "   "
   :site-link]}
 "This is a test"]

HTML:

<a class="sidebar-link menu-link site-link">This is a test</a>

Conditional css classes:

(let
 [selected? true confirming-delete? true]
 [:a
  {:class
   [:ux/css-classes
    :sidebar-link
    :menu-link
    (when selected? :active)
    (when confirming-delete? :danger-link)]}
  "This is a test"])

HTML:

<a class="sidebar-link menu-link active danger-link">This is a test</a>

Space seperated strings:

[:div {:class [:ux/css-classes "one two three"]} "This is a test"]

HTML:

<div class="one two three">This is a test</div>

Variable substituion with keywords:

[:div
 {:class
  [:ux/css-classes {:colour "red"} :bg-<colour>-300.text-<colour>-600]}
 "This is a test"]

HTML:

<div class="bg-red-300 text-red-600">This is a test</div>

Dot seperated keywords:

[:div {:class [:ux/css-classes :one.two.three.four]} "This is a test"]

HTML:

<div class="one two three four">This is a test</div>

Space seperated keywords:

[:div {:class [:ux/css-classes :one :two :three]} "This is a test"]

HTML:

<div class="one two three">This is a test</div>

Multiple dot seperated keywords:

[:div
 {:class [:ux/css-classes :one.two.three.four :five.six.seven]}
 "This is a test"]

HTML:

<div class="one two three four five six seven">This is a test</div>

Variable substituion with strings:

[:div
 {:class
  [:ux/css-classes
   {:colour "blue"}
   "bg-{{colour}}-300 text-{{colour}}-600 shadow-{{colour}}"]}
 "This is a test"]

HTML:

<div class="bg-blue-300 text-blue-600 shadow-blue">This is a test</div>

Multiple strings:

[:div {:class [:ux/css-classes "one" "two" "three"]} "This is a test"]

HTML:

<div class="one two three">This is a test</div>

:ux/fragment

;; Component signatures

[:ux/fragment & elements]

Allows for returning multiple child elements without the need for a parent element.

Examples:

Multiple paragraphs:

[:ux/fragment [:p "one"] [:p "Two"] [:p "Three"]]

HTML:

<p>one</p>
<p>Two</p>
<p>Three</p>

Multiple list items without parent ol or ul:

[:ux/fragment [:li "one"] [:li "Two"] [:li "Three"]]

HTML:

<li>one</li>
<li>Two</li>
<li>Three</li>

Multiple table cells:

[:ux/fragment [:td "one"] [:td "Two"] [:td "Three"]]

HTML:

<td>one</td>
<td>Two</td>
<td>Three</td>

:ux/html

;; Component signatures

[:ux/html & html]

Used for including strings that contain HTML markup, this component converts the provided html into an unescaped string, allowing the HTML to be rendered by the browser.

Warning: Never provide strings that come from external sources or user defined input as they could include malicious JavaScript and cause cross-site scripting (XSS) attacks - those strings should remain escaped.

Examples:

Single HTML string:

[:ux/html "This is a <strong>test</strong> with <em>embeded html</em>."]

HTML:

This is a <strong>test</strong> with <em>embeded html</em>.

Multiple HTML strings:

[:ux/html
 "This is a <strong>test</strong> with <em>embeded html</em>."
 "Another line with a <h1>Header element</h1> and link"
 "<a href=\"https://example.com\">Test link</a>"]

HTML:

This is a <strong>test</strong> with <em>embeded html</em>. Another line with a <h1>Header element</h1> and link <a href="https://example.com">Test link</a>

:ux/html-template

;; Component signatures

[:ux/html-template variable-substitution-map & html-string-template]

Returns an unescaped HTML string where interpolated variables are replaced using values in the map provided by variable-substitution-map allowing for templated HTML strings.

Interpolated variables can be tags enclosed as follows (where my-value is the name of the variable to replace):

  • "Hello {{my-value}}"
  • "Hello {my-value}"
  • "Hello <<my-value>>"
  • "Hello <my-value>"
  • "Hello !!my-value!!"
  • "Hello !my-value!"
  • "Hello $$my-value$$"
  • "Hello $my-value$"

Warning: Never provide strings that come from external sources or user defined input as they could include malicious JavaScript and cause cross-site scripting (XSS) attacks - those strings should remain escaped.

Examples:

Single template string:

[:ux/html-template
 {:name "Bob Smith", :email-address "bobsmith@mailinator.com"}
 "Your name is <strong>{{name}}</strong> and your email address is <em>{{email-address}}</em>"]

HTML:

Your name is <strong>Bob Smith</strong> and your email address is <em>bobsmith@mailinator.com</em>

Variable template string:

[:div
 [:ux/html-template
  {:name "Bob Smith", :email-address "bobsmith@mailinator.com"}
  "Your name is <strong>{{name}}</strong> and"
  "your email address is <em>{{email-address}}</em>"]]

HTML:

<div>Your name is <strong>Bob Smith</strong> and your email address is <em>bobsmith@mailinator.com</em></div>

:ux/html5-doc

;; Component signatures

[:ux/html5-doc & document]

Constructs a HTML5 document with the correct DOCTYPE using the given document as child elements (e.g head, body) of the <html> tag.

Examples:

[:ux/html5-doc
 [:head [:title "Test HTML document"]]
 [:body [:h1 "Hello world"]]]

HTML:

<!DOCTYPE html>
<html>

<head>
    <title>Test HTML document</title>
</head>

<body>
    <h1>Hello world</h1>
</body>

</html>

:ux/include-javascripts

;; Component signatures

[:ux/include-javascripts & javascript-urls]

Includes one or more <script> tags that link to external javascript files through the src attribute. Accepts a variable list of javascript-urls.

Examples:

Single javascript file:

[:ux/include-javascripts "/css/base.js"]

HTML:

<script src="/css/base.js"></script>

Multiple javascript files:

[:ux/include-javascripts "/css/base.js" "/css/app.js"]

HTML:

<script src="/css/base.js"></script>
<script src="/css/app.js"></script>

:ux/include-stylesheets

;; Component signatures

[:ux/include-stylesheets & stylesheet-urls]

Includes one or more <link> tags that link to external style sheets. Accepts a variable list of stylesheet-urls.

Examples:

Single stylesheet link:

[:ux/include-stylesheets "/css/base.css"]

HTML:

<link href="/css/base.css" rel="stylesheet" />

Multiple stylesheet links:

[:ux/include-stylesheets "/css/base.css" "/css/theme.css"]

HTML:

<link href="/css/base.css" rel="stylesheet" />
<link href="/css/theme.css" rel="stylesheet" />

:ux/javascript

;; Component signatures

[:ux/javascript & javascript-lines]

Used for including unescaped, executable javascript in Hiccup data.

Converts provided javascript-lines (one or more strings) into an unescaped string, allowing the javascript to be executed by the browser if wrapped in a <script> tag.

Warning: Never provide strings that come from external sources or user defined input as they could include malicious JavaScript and cause cross-site scripting (XSS) attacks - those strings should remain escaped.

Examples:

Single line:

[:ux/javascript "alert('Hello world');"]

HTML:

alert('Hello world');

Multiple lines:

[:ux/javascript "alert('Hello world');" "alert('Goodbye world');"]

HTML:

alert('Hello world'); alert('Goodbye world');

Confirm example:

[:ux/javascript
 "if (confirm('Press a button!') == true) {
    alert('You pressed OK!);
  } else {
    alert('You canceled!');
  }"]

HTML:

if (confirm('Press a button!') == true) { alert('You pressed OK!); } else { alert('You canceled!'); }

:ux/javascript-tag

;; Component signatures

[:ux/javascript-tag & javascript-lines]

Wraps the supplied javascript-lines in a <script> tag which executes the javascript in the web browser.

Warning: Never provide strings that come from external sources or user defined input as they could include malicious JavaScript and cause cross-site scripting (XSS) attacks - those strings should remain escaped.

Examples:

Single line:

[:ux/javascript-tag "alert('Hello world');"]

HTML:

<script>
    alert('Hello world');
</script>

Multiple lines:

[:ux/javascript-tag "alert('Hello world');" "alert('Goodbye world');"]

HTML:

<script>
    alert('Hello world');
    alert('Goodbye world');
</script>

:ux/string-template

;; Component signatures

[:ux/string-template variable-substitution-map & string-template]

Returns a string where interpolated variables are replaced using values in the map provided by variable-substitution-map allowing for templated strings.

Interpolated variables can be tags enclosed as follows (where my-value is the name of the variable to replace):

  • "Hello {{my-value}}"
  • "Hello {my-value}"
  • "Hello <<my-value>>"
  • "Hello <my-value>"
  • "Hello !!my-value!!"
  • "Hello !my-value!"
  • "Hello $$my-value$$"
  • "Hello $my-value$"

Examples:

Single template string:

[:ux/string-template
 {:name "Bob", :email-address "bobsmith@mailinator.com"}
 "Hello {{name}}, your email address is {{email-address}}."]

HTML:

Hello Bob, your email address is bobsmith@mailinator.com.

Variable template string:

[:ux/string-template
 {:name "Bob", :email-address "bobsmith@mailinator.com"}
 "Hello {{name}}, your "
 "email address is {{email-address}}."]

HTML:

Hello Bob, your email address is bobsmith@mailinator.com.

:ux/style-tag

A <style> tag used to define style information (CSS) for a document.

Examples:

Single line:

[:ux/style-tag ".danger {color: red;}
.success {color: green;}"]

HTML:

<style>
    .danger {
        color: red;
    }

    .success {
        color: green;
    }
</style>

Multiple lines:

[:ux/style-tag
 ".danger {color: red;}"
 ".success {color: green;}"
 ".info {color: blue;}"]

HTML:

<style>
    .danger {
        color: red;
    }

    .success {
        color: green;
    }

    .info {
        color: blue;
    }
</style>