` tags are typical `ParentNode` elements. They can hold an `XmlAttribute list` and a second `XmlElement list` for their child elements:
93 |
94 | ```fsharp
95 | let someHtml = div [] []
96 | ```
97 |
98 | All `ParentNode` elements accept these two parameters:
99 |
100 | ```fsharp
101 | let someHtml =
102 | div [ _id "someId"; _class "css-class" ] [
103 | a [ _href "https://example.org" ] [ str "Some text..." ]
104 | ]
105 | ```
106 |
107 | Most HTML tags are `ParentNode` elements, however there is a few HTML tags which cannot hold any child elements, such as `
` tags. These are represented as `VoidElement` objects and only accept the `XmlAttribute list` as single parameter:
108 |
109 | ```fsharp
110 | let someHtml =
111 | div [] [
112 | br []
113 | hr [ _class "css-class-for-hr" ]
114 | p [] [ str "bla blah" ]
115 | ]
116 | ```
117 |
118 | Attributes are further classified into two different cases. First and most commonly there are `KeyValue` attributes:
119 |
120 | ```fsharp
121 | a [
122 | _href "http://url.com"
123 | _target "_blank"
124 | _class "class1" ] [ str "Click here" ]
125 | ```
126 |
127 | As the name suggests, they have a key, such as `class` and a value such as the name of a CSS class.
128 |
129 | The second category of attributes are `Boolean` flags. There are not many but some HTML attributes which do not require any value (e.g. `async` or `defer` in script tags). The presence of such an attribute means that the feature is turned on, otherwise it is turned off:
130 |
131 | ```fsharp
132 | script [ _src "some.js"; _async ] []
133 | ```
134 |
135 | There's also a wealth of [accessibility attributes](https://www.w3.org/TR/html-aria/) available under the `Giraffe.ViewEngine.Accessibility` module (needs to be explicitly opened).
136 |
137 | ### Text Content
138 |
139 | Naturally the most frequent content in any HTML document is pure text:
140 |
141 | ```html
142 |
143 |
This is text content
144 |
This is even more text content!
145 |
146 | ```
147 |
148 | The `Giraffe.ViewEngine` lets one create pure text content as a `Text` element. A `Text` element can either be generated via the `rawText` or `encodedText` (or the short alias `str`) functions:
149 |
150 | ```fsharp
151 | let someHtml =
152 | div [] [
153 | p [] [ rawText "
" ]
155 | ]
156 | ```
157 |
158 | The `rawText` function will create an object of type `XmlNode` where the content will be rendered in its original form and the `encodedText`/`str` function will output a string where the content has been HTML encoded.
159 |
160 | In this example the first `p` element will literally output the string as it is (`
`) while the second `p` element will output the value as HTML encoded string `<div>Hello World</div>`.
161 |
162 | Please be aware that the the usage of `rawText` is mainly designed for edge cases where someone would purposefully want to inject HTML (or JavaScript) code into a rendered view. If not used carefully this could potentially lead to serious security vulnerabilities and therefore should be used only when explicitly required.
163 |
164 | Most cases and particularly any user provided content should always be output via the `encodedText`/`str` function.
165 |
166 | ### Naming Convention
167 |
168 | The `Giraffe.ViewEngine` has a naming convention which lets you easily determine the correct function name without having to know anything about the view engine's implementation.
169 |
170 | All HTML tags are defined as `XmlNode` elements under the exact same name as they are named in HTML. For example the `` tag would be `html [] []`, an `