SharpTemplar 0.5.2

There is a newer version of this package available.
See the version list below for details.

dotnet add package SharpTemplar --version 0.5.2

NuGet\Install-Package SharpTemplar -Version 0.5.2

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="SharpTemplar" Version="0.5.2" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add SharpTemplar --version 0.5.2

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: SharpTemplar, 0.5.2"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

// Install SharpTemplar as a Cake Addin
#addin nuget:?package=SharpTemplar&version=0.5.2

// Install SharpTemplar as a Cake Tool
#tool nuget:?package=SharpTemplar&version=0.5.2

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

SharpTemplar

SharpTemplar is a library for making HTML webpages in C#. SharpTemplar allows any tag to be placed nearly anywhere, and it is therefor up to the developer to ensure that tags are placed in a context that makes sense. A table row does, for example, not make sense outside of a table, but SharpTemplar woundn't mind.

Terminology

Term	Description
tag	a HTML tag
element	an object representing a HTML tag

How to use

To use SharpTemplar instantiate a TemplarDocument. This object contains two elements, namely a Head and a Body.

These elements contain methods to add other elements into them (Methods beginning with "Add") or apply attributes (Methods beginning with "With").

For example

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.AddDiv().AddParagraph("bar");

string page = doc.GeneratePage();

Results in this page:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <div></div>
        <p>bar</p>
    </body>
</html>

Applying attributes

Attributes are applied to the just added element, or the element the method is called on in case there was not just added an element.

Note that applying the same attribute multiple times, will append the new value with a whitespace in front. The exception is the "id" attribute, which will simply override the previous value.

Nesting tags

Notice that in the first example, the two added elements have the same parent. This happens because the methods were both called on the Body element. To change what element is being called methods upon, use Enter or Exit. Enter will change to the just added element, or, if no element was just added, it does nothing. Exit will change to the parent of the current element, or do nothing when the element has no parent, i.e. the body element.

For example

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.AddDiv().Enter
            .AddParagraph("1")
            .AddParagraph("2")
        .Exit
        .AddParagraph("3");


string page = doc.GeneratePage();

Results in:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <div>
            <p>1</p>
            <p>2</p>
        </div>
        <p>3</p>
    </body>
</html>

Switching between elements might result in elements being added, and attributes applied, to elements that was not intended. This happens when an element has not been reset, i.e. there is still some element, that has just been added to it.

For example:

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.AddDiv();

doc.Body.WithAttribute("class","container");'

string page = doc.GeneratePage();

In this case the Div that was added to Body, has still just been added, when the class attribute is applied. Therefor the resulting page is:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <div class="container"></div>
    </body>
</html>

This can be fixes by resetting the body, with End.

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.AddDiv().End();

doc.Body.WithAttribute("class","container");'

string page = doc.GeneratePage();

Which will give:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body class="container">
        <div></div>
    </body>
</html>

Note that calling Enter, Exit or End on any element, will reset it. Although Enter and Exit cannot be the end of a call chain.

Outing

Most methods for adding elements are overloaded with an out. If used, the added element is saved in the supplied variable. This could for example be used if some elements need to be added to the outed element in a loop or conditionally.

For example

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

HTMLBodyElement div;
doc.Body.AddDiv(out div).AddParagraph("3");
for (int i = 1; i <= 2; i++) div.AddParagraph($"{i}");

string page = doc.GeneratePage();

Results in:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <div>
            <p>1</p>
            <p>2</p>
        </div>
        <p>3</p>
    </body>
</html>

Conditional/Loop

As an alternative to using the C# loops and conditionals, SharpTemplar offers the Conditional- and Loop-element.

The Conditional element is used with the If method, and takes a condition. To get out of the conditional, Exit is used. For example:

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.If(() => 1 == 2)
            .AddParagraph("1")
        .Exit
        .AddParagraph("2");

string page = doc.GeneratePage();

Would result in this page:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <p>2</p>
    </body>
</html>

While this:

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.If(() => 1 == 1)
            .AddParagraph("1")
        .Exit
        .AddParagraph("2");

string page = doc.GeneratePage();

Would result in this page:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <p>1</p>
        <p>2</p>
    </body>
</html>

The Loop element is used via the While method, which takes a condition and a change. Just like the Conditional, Exit is used to get out of the loop. Elements added to the loop, will be rendered as many times as the loop runs.

For example:

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

int i = 0;
doc.Body.While(() => i < 2, () => i++)
            .AddParagraph("1")
        .Exit
        .AddParagraph("2");

string page = doc.GeneratePage();

Results in:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <p>1</p>
        <p>1</p>
        <p>2</p>
    </body>
</html>

Templates

If you have some reaccuring HTML structure, then using a template might be a good solution.

Templates are written in .sthtml files, which essentially just contains standart HTML. The only difference being the addition of replacement tags. Replacement tags have the following form: <x!>. Where x > 0.

Example of a template, template.sthtml:

<div class="messagecontainer">
    <p>This is a message</p>
    <p><1!></p>
</div>

When placeing a template in a TemplarDocument, any number of string parameters can be given, after the path to the template file. These will be used as replacements. All <1!> tags would for instance be replaced with the first parameter given. If the integer in the replacement tag is larger than the amount of given parameters, the replacement tag is replaced with the empty string.

Example:

var doc = new TemplarDocument("test");
            
doc.Head.AddMeta().WithAttribute("charset","utf-8");

doc.Body.PlaceTemplate("path-to-template\template.sthtml", "foobar");

string page = doc.GeneratePage();

The resulting page in this example would be:

<!DOCTYPE html>
<html>
    <head>
        <title>test</title>
        <meta charset="utf-8"></meta>
    </head>
    <body>
        <div class="messagecontainer">
            <p>This is a message</p>
            <p>foobar</p>
        </div>
    </body>
</html>

Supported tags

Head

Link <link>
Meta <meta>
Script <script>
Style <style>
Title <title>

Body

Anchor <a>
Break <br>
Button <button>
DescriptionList <dl>
Div <div>
Form <form>
Header <h1> .. <h6>
Idiomatic <i>
Image <img>
Input <input>
Label <label>
ListItem <li>
Option <option>
OrderedList <ol>
Paragraph <p>
Select <select>
Small <small>
Span <span>
Strong <strong>
Table <table>
TableData <td>
TableHead <th>
TableRow <tr>
Term <dt>
TermDescription <dd>
TextArea <textarea>
UnorderedList <ul>

Product	Compatible and additional computed target framework versions.
.NET	net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net6.0
- No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last updated
1.0.5	181	6/21/2023
1.0.4	359	11/6/2022
1.0.3	333	11/5/2022
1.0.2	347	11/5/2022
1.0.1	358	11/4/2022
1.0.0	341	11/3/2022
0.5.2	430	3/23/2022
0.5.1	396	2/25/2022
0.5.0	403	2/24/2022
0.4.1	337	7/2/2021
0.4.0	294	7/2/2021
0.3.0	308	6/12/2021
0.2.2	336	5/20/2021
0.2.1	350	5/20/2021
0.2.0	302	4/20/2021
0.1.1	310	4/19/2021
0.1.0	305	4/19/2021

SharpTemplar 0.5.2

SharpTemplar

Terminology

How to use

Applying attributes

Nesting tags

Outing

Conditional/Loop

Templates

Supported tags

Head

Body

net6.0

NuGet packages

GitHub repositories