HTML attributes follow the same naming convention except that attributes have an underscore prepended. For example the `class` attribute would be `_class` and the `src` attribute would be `_src` in the `Giraffe.ViewEngine`.

The underscore does not only help to distinguish an attribute from an element, but also avoid a naming conflict between tags and attributes of the same name (e.g. `` vs. ``).

If a HTML attribute has a hyphen in the name (e.g. `accept-charset`) then the equivalent Giraffe attribute would be written in camel case notion after the initial underscore (e.g. `_acceptCharset`).

*Should you find a HTML tag or attribute missing in the `Giraffe.ViewEngine` then you can either [create it yourself](#custom-elements-and-attributes) or send a [pull request on GitHub](https://github.com/giraffe-fsharp/Giraffe.ViewEngine/pulls).*

### Javascript event handlers

It is possible to add JavaScript event handlers to HTML elements using the `Giraffe.ViewEngine`. These event handlers (all prefixed with names starting with `_on`, for example `_onclick`, `_onmouseover`) can either execute inline JavaScript code or can invoke functions that are part of the `window` scope.

This example illustrates how inline JavaScript could be used to log to the console when a button is clicked:

```fsharp
let inlineJSButton =
button [_id "inline-js"
_onclick "console.log(\"Hello from the 'inline-js' button!\");"] [str "Say Hello" ]
```

There are some caveats with this approach, namely that
* ...it is not very scalable to write JavaScript inline in this manner, and more pressing...
* ...the `Giraffe.ViewEngine` HTML-encodes the text provided to the `_onX` attributes.

To get around this, you can write dedicated scripts in your HTML and reference the functions from your event handlers:

```fsharp
let page =
div [] [
script [_type "application/javascript"] [
rawText """
window.greet = function () {
console.log("ping from the greet method");
}
"""
]
button [_id "script-tag-js"
_onclick "greet();"] [str "Say Hello"]
]
```

Here it's important to note that we've included the text of our script using the `rawText` tag. This ensures that our text is not encoded by the `Giraffe.ViewEngine` so that it remains as it was written.

However, writing large quantities of JavaScript in this manner can be difficult, because you don't have access to the large ecosystem of javascript editor tooling. In this case you should write your functions in another script and use a `script` tag element to reference your script, then add the desired function to your HTML element's event handler.

Say you had a JavaScript file named `greet.js` and had configured Giraffe to serve that script from the WebRoot. Let us also say that the content of that script was:

```javascript
function greet() {
console.log("Hello from the greet function of greet.js!");
}
```

Then, you could reference that javascript via a script element, and use `greet` in your event handler like so:

```fsharp
let page =
html [] [
head [] [
script [_type "application/javascript"
_src "/greet.js"] [] // include our `greet.js` function dynamically
]
body [] [
button [_id "greet-btn"
_onclick "greet()"] [] // use the `greet()` function from `greet.js` to say hello
]
]
```

In this way, you can write `greet.js` with all of your expected tooling, and still hook up the event handlers all in one place in the `Giraffe.ViewEngine`.

### Custom Elements and Attributes

Adding new elements or attributes is normally as simple as a single line of code:

```fsharp
open Giraffe.ViewEngine

// If there was a new HTML element:
let foo = tag "foo"

// If is an element which cannot hold any content then create it as voidTag:
let foo = voidTag "foo"

// If has a new attribute called bar then create a new bar attribute:
let _bar = attr "bar"

// if the bar attribute is a boolean flag:
let _bar = flag "bar"
```

Alternatively you can also create new elements and attributes from inside another element:

```fsharp
let someHtml =
div [] [
tag "foo" [ attr "bar" "blah" ] [
voidTag "otherFoo" [ flag "flag1" ]
]
]
```

### Rendering Views

Rendering views with the `Giraffe.ViewEngine` can be done in several ways. The `RenderView` module exposes three sub modules which can be used to specify the desired output format:

- `RenderView.IntoStringBuilder` implements functions to render a view into a `StringBuilder` object which can be used for further processing.
- `RenderView.AsString` implements functions to output a view directly as a `string`.
- `RenderView.AsBytes` implements functions to output a view directly as a `byte array`.

All three sub modules implement the following public functions:

- `htmlDocument`
- `htmlNodes`
- `htmlNode`
- `xmlNodes`
- `xmlNode`

#### Rendering HTML

The `htmlDocument` function takes a single `XmlNode` as input parameter and renders a HTML page with a `DOCTYPE` declaration. This function should be used for rendering a complete HTML document.

The `htmlNodes` function takes an `XmlNode list` as input parameter and will output a single HTML string containing all the rendered HTML code. The `htmlNode` function renders a single `XmlNode` element into a valid HTML string. Both, the `htmlNodes` and `htmlNode` function are useful for use cases where a HTML snippet needs to be created without a `DOCTYPE` declaration (e.g. email templates, etc.).

#### Rendering XML

Views cannot only be rendered into HTML pages but also into other XML based content such as SVG images or other data objects.

The `xmlNodes` and `xmlNode` function are identical to `htmlNodes` and `htmlNode`, except that they will render void elements differently:

```fsharp
let someTag = voidTag "foo"
let someContent = someTag []

// Void tag will be rendered to valid HTML:
let output1 = RenderView.AsString.htmlNode someContent

// Void tag will be rendered to valid XML:
let output2 = RenderView.AsString.xmlNode someContent
```

#### StringBuilder Pools

All functions from the `RenderView.AsString` and `RenderView.AsBytes` modules are using a thread static `StringBuilderPool` to avoid the creation of large `StringBuilder` objects for each render call and dynamically grow/shrink that pool based on the application's needs. However if the application is running into any memory issues then this performance feature can be disabled by setting `StringBuilderPool.IsEnabled` to false:

```fsharp
StringBuilderPool.IsEnabled <- false
```

Additionally the `RenderView.IntoStringBuilder` module can be used if full control of the `StringBuilder` object is required:

```fsharp
open System.Text
open Giraffe.ViewEngine

let someHtml =
div [] [
tag "foo" [ attr "bar" "blah" ] [
voidTag "otherFoo" [ flag "flag1" ]
]
]

// Create your own StringBuilder, which gives the caller
// full control of the lifecycle of the object:
let sb = new StringBuilder()

// Perform actions on the `sb` object...
sb.AppendLine "This is a HTML snippet inside a markdown string:"
.AppendLine ""
.AppendLine "```html" |> ignore

// Using RederView.IntoStringBuilder some HTML content can be written
// directly into the given StringBuilder object:
let sb' = RederView.IntoStringBuilder.htmlNode sb someHtml

// Perform more actions on the `sb` object...
sb'.AppendLine "```" |> ignore

let markdownOutput = sb'.ToString()
```

### Common Patterns

The `Giraffe.ViewEngine` is nothing more but simple F# code dressed up as a DSL which can be used to compose rich HTML content in a structured way. As such it doesn't require any built-in functions to enable common view engine features such as master pages, partial views or model binding. These things can all be accomplished through normal F# coding patterns:

#### Master Pages

Creating a master page is as simple as piping two functions together:

```fsharp
module Views =
open Giraffe.ViewEngine

let master (pageTitle : string) (content: XmlNode list) =
html [] [
head [] [
title [] [ str pageTitle ]
]
body [] content
]

let index =
let pageTitle = "Giraffe Sample"
[
h1 [] [ str pageTitle ]
p [] [ str "Hello world!" ]
] |> master pageTitle
```

... or even have multiple nested master pages:

```fsharp
module Views =
open Giraffe.ViewEngine

let master1 (pageTitle : string) (content: XmlNode list) =
html [] [
head [] [
title [] [ str pageTitle ]
]
body [] content
]

let master2 (content: XmlNode list) =
[
main [] content
footer [] [
p [] [
str "Copyright ..."
]
]
]

let index =
let pageTitle = "Giraffe Sample"
[
h1 [] [ str pageTitle ]
p [] [ str "Hello world!" ]
] |> master2 |> master1 pageTitle
```

#### Partial Views

Partial views can be codified by calling one function from within another:

```fsharp
module Views =
open Giraffe.ViewEngine

let partial =
footer [] [
p [] [
str "Copyright..."
]
]

let master (pageTitle : string) (content: XmlNode list) =
html [] [
head [] [
title [] [ str pageTitle ]
]
body [] content
partial
]

let index =
let pageTitle = "Giraffe Sample"
[
h1 [] [ str pageTitle ]
p [] [ str "Hello world!" ]
] |> master pageTitle
```

#### Model Binding

A view which accepts a model is basically a function with an additional parameter:

```fsharp
module Views =
open Giraffe.ViewEngine

let partial =
footer [] [
p [] [
str "Copyright..."
]
]

let master (pageTitle : string) (content: XmlNode list) =
html [] [
head [] [
title [] [ str pageTitle ]
]
body [] content
partial
]

let index (model : IndexViewModel) =
[
h1 [] [ str model.PageTitle ]
p [] [ str model.WelcomeText ]
] |> master model.PageTitle
```

#### Logical Constructs

Things like if statements, loops and other F# language constructs just work as expected:

```fsharp
let partial (books : Book list) =
ul [] [
yield!
books
|> List.map (fun b -> li [] [ str book.Title ])
]
```

Overall the `Giraffe.ViewEngine` is extremely flexible and more feature rich than any other view engine given that it is just normal compiled F# code.

### Best Practices

Due to the huge amount of available HTML tags and their fairly generic (and short) names (e.g. ``, ``, ``, etc.) there is a significant danger of accidentally overriding a function of the same name in an application's codebase. For that reason the `Giraffe.ViewEngine` becomes only available after opening the `Giraffe.ViewEngine` module.

As a measure of good practice it is recommended to create all views in a separate module:

```fsharp
module MyWebApplication

module Views =
open Giraffe.ViewEngine

let index =
html [] [
head [] [
title [] [ str "Giraffe Sample" ]
]
body [] [
h1 [] [ str "I |> F#" ]
p [ _class "some-css-class"; _id "someId" ] [
str "Hello World"
]
]
]

let other = //...
```

This ensures that the opening of the `Giraffe.ViewEngine` is only contained in a small context of an application's codebase and therefore less of a threat to accidental overrides. In the above example views can always be accessed through the `Views` sub module (e.g. `Views.index`).

## Samples

The following sample code creates and renders a HTML page with the help of the `Giraffe.ViewEngine` and subsequently saves it into a temporary `.html` file before opening it with the default browser:

``` FSharp
module Sample =
open Giraffe.ViewEngine

let bodyTemplate (nameList: string list): XmlNode =
body []
[ h1 [] [ Text "Welcome:" ]
ol [] (nameList |> List.map (fun x -> li [] [ Text x ])) ]

let navTemplate =
nav [] [ a [ _href "./About" ] [ Text "About" ] ]

let documentTemplate (nav: XmlNode) (body: XmlNode) =
html [] [ nav; body ]

let render welcomeUsers =
bodyTemplate welcomeUsers
|> (documentTemplate navTemplate)
|> RenderView.AsString.htmlDocument

[]
let main args =
let tfn =
(System.IO.Path.GetTempFileName()) |> sprintf "%s.html"

args
|> Seq.toList
|> Sample.render
|> fun x -> System.IO.File.WriteAllText(tfn, x)
|> ignore

let p = new System.Diagnostics.Process()
p.StartInfo.FileName <- tfn
p.StartInfo.UseShellExecute <- true
p.Start() |> ignore

0
```

The above code will return the following result:

![alt text][sample-screenshot]

[sample-screenshot]: ./samples/Giraffe.ViewEngine.Sample/sample-screenshot.jpg "Example for Github"

This sample application can also be viewed inside the [Giraffe.ViewEngine.Sample](./samples/Giraffe.ViewEngine.Sample) application.

## Attribution to original authors

This code has been originally ported from [Suave](https://github.com/SuaveIO/suave) and subsequently improved and extended over the years.

The original code has been authored by

- [Henrik Feldt](https://github.com/haf)
- [Ademar Gonzalez](https://github.com/ademar)

You can find the original implementation here:

[https://github.com/SuaveIO/suave/blob/master/src/Suave.Experimental/Html.fs](https://github.com/SuaveIO/suave/blob/master/src/Suave.Experimental/Html.fs)

Huge thanks to [Suave](https://github.com/SuaveIO/suave) for letting us borrow their code and thanks to [Florian Verdonck](https://github.com/nojaf) for originally porting it to Giraffe.

## Nightly builds and NuGet feed

All official release packages are published to the official and public NuGet feed.

Nightly builds (builds from the `develop` branch) produce unofficial pre-release packages which can be pulled from the [project's NuGet feed on GitHub](https://github.com/orgs/giraffe-fsharp/packages).

These packages are being tagged with the Workflow's run number as the package version.

All other builds, such as builds triggered by pull requests produce a NuGet package which can be downloaded as an artifact from the individual GitHub action.

## License