fluent-tag-api.md

Razor Blade Fluent Tag API v3.0

The Tag Objects

The Tag objects generate Html tags inside RazorBlade and provide a powerfull API will let you build html from code. These docs will give you what you need to leverage the object. Here you'll find:

1. a Quick-Reference for the common API
2. more instructions for doing specific things
3. advanced API for special stuff

To see this in action with many examples, visit the RazorBlade Tutorials on 2sxc.org.

How to get Tag Objects

The following APIs will get you Tag objects:

1. Tag.*() where * is any standard HTML5 term, like Div, Hr, IFrame etc. - returns a typed object with more methods like Src(url) on Tags.Img() v2.2
2. Tag.*(content) same thing like above, but with content in the constructor
3. Tags.*(content1, content2, ...) same thing like above, but with much content in the constructor
4. Tag.Custom(string tagName) (more)

Fluent API for Tag (Chaining)

All these methods of a Tag change the object, and return the object itself again. This fluent-API allows chaining them together, like

someTag.Id("someId").Class("float-right")

Below we'll explain the methods that all Tag objects have, but many have custom commands as well. For example, an Img Tag also has a Src(...) while anA Tag also has href. Some of the additional commands are extra-smart and automatically URI encode the value if not yet encoded.

Modifying Tag Attributes

1. Attr(name, [value], [separator])
   add an attribute - if it already exists, it will replace the value, unless a separator is specified which will then append the new value.
   • name: string, required
   • value: string | object | null, optional
     Objects will be JSON serialized; null will result in the attribute being added without a value, like disabled
   • separator: string, default is ""
     Separation character if we have to append to an existing value. If null, will replace instead of append.
2. Class(value)
   set / add a class to the tag; if called multiple times, will append with a space between the original and new value. When calling with null, will reset the class to empty.
3. Data(name, [value])
   will add a data-{name}='value' attribute.
4. Id(value)
   set the id attribute - if called multiple times, will always replace previous id
5. On(name, jsCode)
   add an event-attribute like onclick
6. Style(value)
   set / add a class to the tag; if called multiple times, will append with a semicolon ; between the original and new value. When calling with null, will reset the id to empty.
7. Title(value)
   set the title attribute - if called multiple times, will always replace previous title

Modifying the Tag Contents

1. Add(value)
   Add something to contents - at the end of existing content.
   • value: string | Tag | IEnumerable<string|Tag>
2. Add(value, value, ...) v2.2
   Add a many items to contents - at the end of existing content.
   • value: string | Tag
3. Wrap(value)
   Replaces the content
   • value: string | Tag | IEnumerable<string|Tag>
4. Wrap(value, value, ...) v2.2
   Replaces the content with many items
   • value: string | Tag

Output/Render API

A Tag object and the two properties .Open and .Close all support IHtmlString, so you can output them directly:

1. @myTag
   will render the tag into the html. Implements IHtmlString and will not be encoded.
2. @myTag.TagStart
   will render the opening tag to html. Implements IHtmlString and will not be encoded.
3. myTag.TagEnd
   will render the close-tag to html. Implements IHtmlString and will not be encoded.

_Note: the TagStart and TagEnd have unusually long names, to ensure that the terms won't collide with future attribute names like Open etc.

@using ToSic.Razor.Blade;
@Tags.Tag("br")
@Tags.Tag("div").Wrap("this is my message")
@{
  var myStyle = Tags.Tag("style");
}
@myStyle.Open
  .red { color: red};
@myStyle.Close

All Html5 Tags and Attributes

The Tag object provides access to all known Html5 tags. Read the full API