html

package
v0.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2021 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

The HTML package includes general functions for manipulating html tags, comments and the like. It includes specific functions for manipulating attributes inside of tags, including various special attributes like styles, classes, data-* attributes, etc.

Many of the routines return a boolean to indicate whether the data actually changed. This can be used to prevent needlessly redrawing html after setting values that had no affect on the attribute list.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddAttributeValue added in v0.0.3 

func AddAttributeValue(originalValues string, newValues string) (string, bool)

AddAttributeValue is a utility function that appends the given space separated words to the end of the given string, if the words are not already in the string. This is primarily used for adding classes to a class attribute, but other attributes use this structure as well, like aria-labelledby and aria-describedby attributes.

Returns the new string, and a value indicating whether it changed or not. The final string returned will have no duplicates. Since the order of a class list in html makes a difference, you should take care in the order of the classes you add if this matters in your situation.

func AttributeString 

func AttributeString(i interface{}) string

AttributeString is a helper function to convert an interface type to a string that is appropriate for the value in the Set function.

func Comment 

func Comment(s string) string

Comment turns the given text into an html comment and returns the rendered comment

func HasWord added in v0.0.3 

func HasWord(words string, testWord string) (found bool)

HasWord searches the list of strings for the given word.

func Indent 

func Indent(s string) (out string)

Indent will add space to the front of every line in the string. Since indent is used to format code for reading while we are in development mode, we do not need it to be particularly efficient. It will not do this for textarea tags, since that would change the text in the tag.

func MergeStyleStrings added in v0.2.0 

func MergeStyleStrings(s1, s2 string) string

MergeStyleStrings merges the styles found in the two style strings. s2 wins conflicts

func RandomString 

func RandomString(n int) string

RandomString generates a pseudo random string of the given length Characters are drawn from legal HTML values that do not need encoding. The distribution is not perfect, so its not good for crypto, but works for general purposes This also works for GET variables

func RemoveAttributeValue added in v0.0.3 

func RemoveAttributeValue(originalValues string, removeValue string) (string, bool)

Use RemoveAttributeValue to remove a value from the list of space-separated values given. You can give it more than one value to remove by separating the values with spaces in the removeValue string. This is particularly useful for removing a class from a class list in a class attribute.

func RemoveClassesWithPrefix 

func RemoveClassesWithPrefix(class string, prefix string) (string, bool)

RemoveClassesWithPrefix will remove all classes from the class string with the given prefix. Many CSS frameworks use families of classes, which are built up from a base family name. For example, Bootstrap uses 'col-lg-6' to represent a table that is 6 units wide on large screens and Foundation uses 'large-6' to do the same thing. This utility removes classes that start with a particular prefix to remove whatever sizing class was specified. Returns the resulting class list, and true if the list actually changed.

Example 
classes, changed := RemoveClassesWithPrefix("col-6 col-brk col4-other", "col-")
fmt.Println(classes + ":" + strconv.FormatBool(changed))

Output:

col4-other:true

func RenderImage 

func RenderImage(src string, alt string, attributes Attributes) string

RenderImage renders an image tag with the given sourc, alt and attribute values.

func RenderLabel 

func RenderLabel(labelAttributes Attributes, label string, ctrlHtml string, mode LabelDrawingMode) string

RenderLabel is a utility function to render a label, together with its text. Various CSS frameworks require labels to be rendered a certain way.

func RenderTag 

func RenderTag(tag string, attr Attributes, innerHtml string) string

RenderTag renders a standard html tag with a closing tag. innerHtml is html, and must already be escaped if needed. The tag will be surrounded with newlines to force general formatting consistency. This will cause the tag to be rendered with a space between it and its neighbors if the tag is not a block tag. In the few situations where you would want to get rid of this space, call RenderTagNoSpace()

Example 
fmt.Println(RenderTagNoSpace("div", NewAttributesFrom(map[string]string{"id": "me", "name": "you"}), "Here I am"))

Output:

<div id="me" name="you">Here I am</div>

func RenderTagNoSpace 

func RenderTagNoSpace(tag string, attr Attributes, innerHtml string) string

RenderTagNoSpace is similar to RenderTag, but should be used in situations where the tag is an inline tag that you want to visually be right next to its neighbors with no space.

func RenderVoidTag 

func RenderVoidTag(tag string, attr Attributes) (s string)

RenderVoidTag renders a void tag using the given tag name and attributes.

Example 
fmt.Println(RenderVoidTag("img", NewAttributesFrom(map[string]string{"src": "thisFile"})))

Output:

<img src="thisFile" />

func StyleString 

func StyleString(i interface{}) string

StyleString converts an interface type that is being used to set a style value to a string that can be fed into the SetStyle* functions

func TextToHtml 

func TextToHtml(in string) (out string)

TextToHtml does a variety of transformations to make standard text presentable as HTML. It escapes characters needing to be escaped and turns newlines into breaks and double newlines into paragraphs.

Example 
s := TextToHtml("This is a & test.\n\nA paragraph\nwith a forced break.")
fmt.Println(s)

Output:

This is a &amp; test.<p>A paragraph<br />with a forced break.

func ToDataAttr 

func ToDataAttr(s string) (string, error)

ToDataAttr is a helper function to convert a name from camelCase to kabob-case for data attributes in particular. data-* html attributes have special conversion rules. Attribute names should always be lower case. Dashes in the name get converted to camel case javascript variable names. For example, if you want to pass the value with key name "testVar" to javascript by printing it in the html, you would use this function to help convert it to "data-test-var", after which you can retrieve in javascript by calling ".data('testVar')". on the object. This will also test for the existence of a camel case string it cannot handle

Example 
s, _ := ToDataAttr("thisIsMyTest")
fmt.Println(s)

Output:

this-is-my-test

func ToDataKey added in v0.2.0 

func ToDataKey(s string) (string, error)

ToDataKey is a helper function to convert a name from kabob-case to camelCase. data-* html attributes have special conversion rules. Key names should always be lower case. Dashes in the name get converted to camel case javascript variable names. For example, if you want to pass the value with key name "testVar" to javascript by printing it in the html, you would use this function to help convert it to "data-test-var", after which you can retrieve in jQuery by calling ".data('testVar')". on the object.

Types

type Attributer 

type Attributer interface {
	Attributes(...interface{}) Attributes
}

Attributer is a general purpose interface for objects that return attributes based on information given.

type Attributes 

type Attributes map[string]string

An html attribute manager. Use SetAttribute to set specific attribute values, and then convert it to a string to get the attributes in a version embeddable in an html tag.

func NewAttributes 

func NewAttributes() Attributes

NewAttributes initializes a group of html attributes.

func NewAttributesFrom 

func NewAttributesFrom(i interface{}) Attributes

NewAttributesFrom creates new attributes from the given string map.

Example 
a := NewAttributesFrom(map[string]string{"id": "1", "name": "test"})
fmt.Println(a.Get("id"))

Output:

1

func (Attributes) AddAttributeValue added in v0.0.3 

func (a Attributes) AddAttributeValue(attr string, value string) Attributes

AddAttributeValue adds space separated values to the end of an attribute value. If a value is not present, the value will be added to the end of the value list. If a value is present, it will not be added, and the position of the current value in the list will not change.

func (Attributes) AddAttributeValueChanged added in v0.0.3 

func (a Attributes) AddAttributeValueChanged(attr string, values string) bool

AddAttributeValueChanged adds the given space separated values to the end of the values in the given attribute, removing duplicates and returning true if the attribute was changed at all. An example of a place to use this is the aria-labelledby attribute, which can take multiple space-separated id numbers.

func (Attributes) AddClass 

func (a Attributes) AddClass(v string) Attributes

AddClass adds a class or classes. Multiple classes can be separated by spaces. If a class is not present, the class will be added to the end of the class list. If a class is present, it will not be added, and the position of the current class in the list will not change.

Example 
a := NewAttributes()
a.AddClass("this")
a.AddClass("that")
fmt.Println(a)

Output:

class="this that"

func (Attributes) AddClassChanged 

func (a Attributes) AddClassChanged(v string) bool

AddClassChanged is similar to AddClass, but will return true if the class changed at all.

func (Attributes) Class 

func (a Attributes) Class() string

Return the value of the class attribute.

func (Attributes) Copy 

func (a Attributes) Copy() Attributes

Copy returns a copy of the attributes.

func (Attributes) DataAttribute 

func (a Attributes) DataAttribute(name string) string

DataAttribute gets the data-* attribute value that was set previously. This does NOT call into javascript to return a value that was set on the browser side. You need to use another mechanism to retrieve that.

func (Attributes) Delete added in v0.2.0 

func (a Attributes) Delete(attr string)

func (Attributes) Get added in v0.2.0 

func (a Attributes) Get(attr string) string

func (Attributes) GetStyle 

func (a Attributes) GetStyle(name string) string

GetStyle gives you the value of a single style attribute value. If you want all the attributes as a style string, use StyleString().

func (Attributes) Has added in v0.2.0 

func (a Attributes) Has(attr string) bool

func (Attributes) HasAttributeValue added in v0.0.3 

func (a Attributes) HasAttributeValue(attr string, value string) bool

HasAttributeValue returns true if the given value exists in the space-separated attribute value.

func (Attributes) HasClass 

func (a Attributes) HasClass(c string) bool

ControlHasClass returns true if the given class is in the class list in the class attribute.

Example 
a := NewAttributes()
if !a.HasClass("that") {
	fmt.Println("Not found")
}
a.SetClass("this that other")
if a.HasClass("that") {
	fmt.Println("found")
}

Output:

Not found
found

func (Attributes) HasDataAttribute 

func (a Attributes) HasDataAttribute(name string) bool

HasDataAttribute returns true if the data attribute is set.

func (Attributes) HasStyle 

func (a Attributes) HasStyle(name string) bool

HasStyle returns true if the given style is set to any value, and false if not.

Example 
a := NewAttributes()
b := []bool{}
var found bool
found = a.HasStyle("height")
b = append(b, found)
a.SetStyle("height", strconv.Itoa(10))
found = a.HasStyle("height")
b = append(b, found)
fmt.Println(b)

Output:

[false true]

func (Attributes) ID 

func (a Attributes) ID() string

ID returns the value of the id attribute.

func (Attributes) IsDisabled 

func (a Attributes) IsDisabled() bool

IsDisabled returns true if the "disabled" attribute is set to true.

func (Attributes) IsDisplayed 

func (a Attributes) IsDisplayed() bool

IsDisplayed returns true if the "display" attribute is not set, or if it is set, if its not set to "none".

func (Attributes) Len added in v0.2.0 

func (a Attributes) Len() int

func (Attributes) Merge added in v0.2.0 

func (a Attributes) Merge(i interface{})

Merge merges the given attributes into the current attributes. Conflicts are won by the passed in map. Styles are merged as well, so that if both the passed in map and the current map have a styles attribute, the actual style properties will get merged together.

func (Attributes) Override 

func (a Attributes) Override(i interface{}) Attributes

Override returns a new Attributes structure with the current attributes merged with the given attributes. Conflicts are won by the given overrides. Styles will be merged as well.

Example 
a := NewAttributes()
a.SetClass("this")
a.SetStyle("height", "4em")

b := NewAttributes()
b.Set("class", "that")
b.SetStyle("width", strconv.Itoa(6))

a = a.Override(b)
fmt.Println(a)

Output:

func (Attributes) Range added in v0.2.0 

func (a Attributes) Range(f func(key string, value string) bool)

func (Attributes) RemoveAttribute 

func (a Attributes) RemoveAttribute(name string) bool

RemoveAttribute removes the named attribute. Returns true if the attribute existed.

func (Attributes) RemoveClass 

func (a Attributes) RemoveClass(v string) bool

Use RemoveClass to remove the named class from the list of classes in the class attribute.

func (Attributes) RemoveClassesWithPrefix 

func (a Attributes) RemoveClassesWithPrefix(v string) bool

Use RemoveClassesWithPrefix to remove classes with the given prefix. Many CSS frameworks use families of classes, which are built up from a base family name. For example, Bootstrap uses 'col-lg-6' to represent a table that is 6 units wide on large screens and Foundation uses 'large-6' to do the same thing. This utility removes classes that start with a particular prefix to remove whatever sizing class was specified. Returns true if the list actually changed.

func (Attributes) RemoveDataAttribute 

func (a Attributes) RemoveDataAttribute(name string) bool

RemoveDataAttribute removes the named data attribute. Returns true if the data attribute existed.

func (Attributes) RemoveStyle 

func (a Attributes) RemoveStyle(name string) (changed bool)

RemoveStyle removes the style from the style list. Returns true if there was a change.

Example 
a := NewAttributes()
a.SetStyle("height", "10")
a.SetStyle("width", strconv.Itoa(5))
a.RemoveStyle("height")
fmt.Println(a)

Output:

style="width:5px"

func (Attributes) Set 

func (a Attributes) Set(name string, v string) Attributes

Set is similar to SetChanged, but instead returns an attribute pointer so it can be chained. Will panic on errors. Use this when you are setting attributes using implicit strings. Set v to an empty string to create a boolean attribute.

func (Attributes) SetChanged 

func (a Attributes) SetChanged(name string, v string) (changed bool, err error)

SetChanged sets the value of an attribute. Looks for special attributes like "class" and "style" to do some error checking on them. Returns changed if something in the attribute structure changed, which is useful to determine whether to send the changed control to the browser. Returns err if the given attribute name or value is not valid.

func (Attributes) SetClass 

func (a Attributes) SetClass(v string) Attributes

SetClass will set the class to the given value, and return the attributes so you can chain calls.

Example 
a := NewAttributes()
a.SetClass("this")
a.SetClass("+ that")
s := a.Class()
fmt.Println(s)

Output:

this that

func (Attributes) SetClassChanged 

func (a Attributes) SetClassChanged(v string) bool

SetClass sets the class attribute to the value given. If you prefix the value with "+ " the given value will be appended to the end of the current class list. If you prefix the value with "- " the given value will be removed from an class list. Otherwise the current class value is replaced. Returns whether something actually changed or not. v can be multiple classes separated by a space

func (Attributes) SetDataAttribute 

func (a Attributes) SetDataAttribute(name string, v string) Attributes

SetDataAttribute sets the given data attribute. Note that data attribute keys must be in camelCase notation and connot be hyphenated. camelCase will get converted to kebab-case in html, and converted back to camelCase when referring to the data attribute using .data().

func (Attributes) SetDataAttributeChanged 

func (a Attributes) SetDataAttributeChanged(name string, v string) (changed bool, err error)

SetDataAttribute sets the given value as an html "data-*" attribute. The named value will be retrievable in jQuery by using 

$obj.data("name");

Note: Data name cases are handled specially. data-* attribute names are supposed to be lower kebab case. Javascript converts dashed notation to camelCase when converting html attributes into object properties. In other words, we give it a camelCase name here, it shows up in the html as a kebab-case name, and then you retrieve it using javascript as camelCase again.

For example, if your html looks like this: 

<div id='test1' data-test-case="my test"></div>

You would get that value in javascript by doing: 

g$('test1').data('testCase');

Conversion to special html data-* name formatting is handled here automatically. So if you SetDataAttribute('testCase') here, you can get it using .data('testCase') in jQuery

func (Attributes) SetDisabled 

func (a Attributes) SetDisabled(d bool) Attributes

SetDisabled sets the "disabled" attribute to the given value.

func (Attributes) SetDisplay 

func (a Attributes) SetDisplay(d string) Attributes

SetDisplay sets the "display" attribute to the given value.

func (Attributes) SetID 

func (a Attributes) SetID(i string) Attributes

SetID sets the id attribute to the given value

func (Attributes) SetIDChanged 

func (a Attributes) SetIDChanged(i string) (changed bool, err error)

SetIDChanged sets the id to the given value and returns true if something changed. In other words, if you set the id to the same value that it currently is, it will return false. It will return an error if you attempt to set the id to an illegal value.

func (Attributes) SetStyle 

func (a Attributes) SetStyle(name string, v string) Attributes

func (Attributes) SetStyleChanged 

func (a Attributes) SetStyleChanged(name string, v string) (changed bool, err error)

SetStyle sets the given style to the given value. If the value is prefixed with a plus, minus, multiply or divide, and then a space, it assumes that a number will follow, and the specified operation will be performed in place on the current value. For example, SetStyle ("height", "* 2") will double the height value without changing the unit specifier. When referring to a value that can be a length, you can use numeric values. In this case, "0" will be passed unchanged, but any other number will automatically get a "px" suffix.

func (Attributes) SetStyles 

func (a Attributes) SetStyles(s Style) Attributes

SetStyle merges the given styles with the current styles. The given style wins on collision.

func (Attributes) SetStylesTo 

func (a Attributes) SetStylesTo(s string) Attributes

SetStylesTo sets the styles using a traditional css style string with colon and semicolon separatators

func (Attributes) String 

func (a Attributes) String() string

String returns the attributes escaped and encoded, ready to be placed in an html tag For consistency, it will use attrSpecialSort to order the keys. Remaining keys will be output in random order.

func (Attributes) StyleMap 

func (a Attributes) StyleMap() Style

Returns a special Style structure which lets you refer to the styles as a string map

func (Attributes) StyleString 

func (a Attributes) StyleString() string

Returns the css style string, or a blank string if there is none

type LabelDrawingMode 

type LabelDrawingMode int

The label drawing mode describes how to draw a label when it is drawn. Various CSS frameworks expect it a certain way. Many are not very forgiving when you don't do it the way they expect. 

const (
	// LabelDefault means the mode is defined elsewhere, like in a config setting
	LabelDefault LabelDrawingMode = iota
	// LabelBefore indicates the label is in front of the control.
	// Example: <label>MyLabel</label><input ... />
	LabelBefore
	// LabelAfter indicates the label is after the control.
	// Example: <input ... /><label>MyLabel</label>
	LabelAfter
	// LabelWrapBefore indicates the label is before the control's tag, and wraps the control tag.
	// Example: <label>MyLabel<input ... /></label>
	LabelWrapBefore
	// LabelWrapAfter indicates the label is after the control's tag, and wraps the control tag.
	// Example: <label><input ... />MyLabel</label>
	LabelWrapAfter
)

type Style 

type Style map[string]string

Style makes it easy to add and manipulate individual properties in a generated style sheet Its main use is for generating a style attribute in an HTML tag It implements the String interface to get the style properties as an HTML embeddable string

func NewStyle 

func NewStyle() Style

NewStyle initializes an empty Style object

func NewStyleFromMap added in v0.2.0 

func NewStyleFromMap(m map[string]string) Style

func (Style) Delete added in v0.2.0 

func (s Style) Delete(prop string)
Example 
s := NewStyle()
s.SetTo("height: 9em; width: 100%; position:absolute")
s.Delete("position")
fmt.Print(s)

Output:

height:9em;width:100%

func (Style) Get 

func (s Style) Get(prop string) string
Example 
s := NewStyle()
s.SetTo("height: 9em; width: 100%; position:absolute")
fmt.Print(s.Get("width"))

Output:

100%

func (Style) Has added in v0.2.0 

func (s Style) Has(prop string) bool
Example 
s := NewStyle()
s.SetTo("height: 9em; width: 100%; position:absolute")
found := s.Has("display")
fmt.Print(found)

Output:

false

func (Style) Len added in v0.2.0 

func (s Style) Len() int

func (Style) Merge added in v0.2.0 

func (s Style) Merge(m Style)

func (Style) RemoveAll 

func (s Style) RemoveAll()

RemoveAll resets the style to contain no styles

Example 
s := NewStyle()
s.SetTo("height: 9em; width: 100%; position:absolute")
s.RemoveAll()
fmt.Print(s)

Output:

func (Style) Set 

func (s Style) Set(n string, v string) Style

Set is like SetChanged, but returns the Style for chaining. It will also allocate a style if passed a nil style, and return it

Example (A) 
s := NewStyle()
s.Set("height", "9")
fmt.Print(s)

Output:

height:9px
Example (B) 
s := NewStyle()
s.SetTo("height:9px")
s.Set("height", "+ 10")
fmt.Print(s)

Output:

height:19px

func (Style) SetChanged 

func (s Style) SetChanged(n string, v string) (changed bool, err error)

func (Style) SetTo 

func (s Style) SetTo(text string) (changed bool, err error)

SetTo receives a style encoded "style" attribute into the Style structure (e.g. "width: 4px; border: 1px solid black")

Example 
s := NewStyle()
s.SetTo("height: 9em; width: 100%; position:absolute")
fmt.Print(s)

Output:

height:9em;position:absolute;width:100%

func (Style) String 

func (s Style) String() string

String returns the string version of the style attribute, suitable for inclusion in an HTML style tag

type StyleCreator added in v0.2.0 

type StyleCreator map[string]string

func (StyleCreator) Create added in v0.2.0 

func (c StyleCreator) Create() Style

type TagBuilder 

type TagBuilder struct {
	// contains filtered or unexported fields
}

Use a TagBuilder to create a tag using a builder pattern, starting out with the tag name and slowly adding parts to it, describing it, until you are ready to print out the entire html tag. The zero value is usable.

func NewTagBuilder 

func NewTagBuilder() *TagBuilder

NewTagBuilder starts a tag build, though you can use a tag builder from its zero value too.

func (*TagBuilder) Class 

func (b *TagBuilder) Class(class string) *TagBuilder

Class sets the class attribute to the value given. If you prefix the value with "+ " the given value will be appended to the end of the current class list. If you prefix the value with "- " the given value will be removed from the class list. Otherwise the current class value is replaced. The given class can be multiple classes separated by a space.

Example 
fmt.Println(NewTagBuilder().Tag("div").Class("bob sam"))

Output:

<div class="bob sam"></div>

func (*TagBuilder) ID 

func (b *TagBuilder) ID(id string) *TagBuilder

ID sets the id attribute

Example 
fmt.Println(NewTagBuilder().Tag("div").ID("bob"))

Output:

<div id="bob"></div>

func (*TagBuilder) InnerHtml 

func (b *TagBuilder) InnerHtml(html string) *TagBuilder

ControlInnerHtml sets the inner html of the tag. Remember this is HTML, and will not be escaped.

Example 
fmt.Println(NewTagBuilder().Tag("div").InnerHtml("<p>A big deal</p>"))

Output:

<div>
  <p>A big deal</p>
</div>

func (*TagBuilder) InnerText 

func (b *TagBuilder) InnerText(text string) *TagBuilder

InnerText sets the inner part of the tag to the given text. The text will be escaped if needed.

Example 
fmt.Println(NewTagBuilder().Tag("div").InnerText("<p>A big deal</p>"))

Output:

<div>
  &lt;p&gt;A big deal&lt;/p&gt;
</div>

func (*TagBuilder) IsVoid 

func (b *TagBuilder) IsVoid() *TagBuilder

By default, tags have inner html. This will make the builder output a void tag instead.

Example 
fmt.Println(NewTagBuilder().Tag("img").IsVoid())

Output:

<img />

func (b *TagBuilder) Link(href string) *TagBuilder

Link is a shortcut that will set the tag to "a" and the "href" to the given destination. This is not the same as an actual "link" tag, which points to resources from the header.

func (*TagBuilder) Set 

func (b *TagBuilder) Set(attribute string, value string) *TagBuilder

Set sets the attribute to the given value

Example 
fmt.Println(NewTagBuilder().Tag("div").Set("me", "you"))

Output:

<div me="you"></div>

func (*TagBuilder) String 

func (b *TagBuilder) String() string

String ends the builder and returns the html.

Example 
s := NewTagBuilder().Tag("div").InnerHtml("<p>A big deal</p>").String()
fmt.Println(s)

Output:

<div>
  <p>A big deal</p>
</div>

func (*TagBuilder) Tag 

func (b *TagBuilder) Tag(tag string) *TagBuilder

Tag sets the tag value

Example 
fmt.Println(NewTagBuilder().Tag("div"))

Output:

<div></div>

type VoidTag 

type VoidTag struct {
	Tag  string
	Attr Attributes
}

VoidTag represents a void tag, which is a tag that does not need a matching closing tag.

func (VoidTag) Render 

func (t VoidTag) Render() string

Render returns the rendered version of the tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.