coredom

Documentation

Overview

Package coredom converts HTML and MD into Cogent Core DOM widget trees.

Index

• Variables
• func ExtractText(ctx *Context) string
• func Get(ctx *Context, url string) (*http.Response, error)
• func GetAttr(n *html.Node, attr string) string
• func HandleElement(ctx *Context)
• func HandleLabel(ctx *Context) *gi.Label
• func HandleLabelTag(ctx *Context) *gi.Label
• func HasAttr(n *html.Node, attr string) bool
• func HighlightingWrapperRenderer(w util.BufWriter, context highlighting.CodeBlockContext, entering bool)
• func IsText(n *html.Node) bool
• func IsURL(u *url.URL) bool
• func New[T gi.Widget](ctx *Context) T
• func NewValue(ctx *Context, val any) giv.Value
• func NodeString(n *html.Node) (start, end string)
• func NormalizeURL(u *url.URL)
• func ParseRelativeURL(rawURL, base string) (*url.URL, error)
• func ParseURL(rawURL string) (*url.URL, bool)
• func PkgGoDevWikilink(url string) func(w *wikilink.Node) (destination []byte, err error)
• func ReadHTML(ctx *Context, par gi.Widget, r io.Reader) error
• func ReadHTMLNode(ctx *Context, par gi.Widget, n *html.Node) error
• func ReadHTMLString(ctx *Context, par gi.Widget, s string) error
• func ReadMD(ctx *Context, par gi.Widget, b []byte) error
• func ReadMDString(ctx *Context, par gi.Widget, s string) error
• func RootNode(n *html.Node) *html.Node
• type Context
  • func NewContext() *Context
  • func (c *Context) AddStyle(style string)
  • func (c *Context) Config(w gi.Widget)
  • func (c *Context) InlineParent() gi.Widget
  • func (c *Context) Parent() gi.Widget
  • func (c *Context) ResolveWikilink(w *wikilink.Node) (destination []byte, err error)

Variables

var ElementHandlers = map[string]func(ctx *Context) bool{}

ElementHandlers is a map of handler functions for each HTML element type (eg: "button", "input", "p"). It is empty by default, but can be used by anyone in need of behavior different than the default behavior defined in HandleElement (for example, for custom elements). If the handler for an element returns false, then the default behavior for an element is used.

var TextTags = []string{
	"a", "abbr", "b", "bdi", "bdo", "br", "cite", "code", "data", "dfn",
	"em", "i", "kbd", "mark", "q", "rp", "rt", "ruby", "s", "samp", "small",
	"span", "strong", "sub", "sup", "time", "u", "var", "wbr",
}

TextTags are all of the node tags that result in a true return value for IsText.

var UserAgentStyles string

UserAgentStyles contains the default user agent styles.

Functions

func ExtractText

func ExtractText(ctx *Context) string

ExtractText recursively extracts all of the text from the children of the given *html.Node, adding any appropriate inline markup for formatted text. It adds any non-text elements to the given gi.Widget using ReadHTMLNode. It should not be called on text nodes themselves; for that, you can directly access the html.Node.Data field. It uses the given page URL for context when resolving URLs, but it can be omitted if not available.

func Get

func Get(ctx *Context, url string) (*http.Response, error)

Get is a helper function that calls http.Get with the given URL, parsed relative to the page URL of the given context. It also checks the status code of the response and closes the response body and returns an error if it is not http.StatusOK. If the error is nil, then the response body is not closed and must be closed by the caller.

func GetAttr

func GetAttr(n *html.Node, attr string) string

GetAttr gets the given attribute from the given node, returning "" if the attribute is not found.

func HandleElement

func HandleElement(ctx *Context)

HandleElement calls the handler in ElementHandlers associated with the current node using the given context. If there is no handler associated with it, it uses default hardcoded configuration code.

func HandleLabel

func HandleLabel(ctx *Context) *gi.Label

HandleLabel creates a new label from the given information, setting the text and the label click function so that URLs are opened according to [Context.OpenURL].

func HandleLabelTag

func HandleLabelTag(ctx *Context) *gi.Label

HandleLabelTag creates a new label from the given information, setting the text and the label click function so that URLs are opened according to [Context.OpenURL]. Also, it wraps the label text with the NodeString of the given node, meaning that it should be used for standalone elements that are meant to only exist in labels (eg: a, span, b, code, etc).

func HasAttr

func HasAttr(n *html.Node, attr string) bool

HasAttr returns whether the given node has the given attribute defined.

func HighlightingWrapperRenderer

func HighlightingWrapperRenderer(w util.BufWriter, context highlighting.CodeBlockContext, entering bool)

HighlightingWrapperRenderer is the highlighting.WrapperRenderer for markdown rendering that enables webcore runnable Go code examples to work correctly.

func IsText

func IsText(n *html.Node) bool

IsText returns true if the given node is a html.TextNode or an html.ElementNode designed for holding text (a, span, b, code, etc), and false otherwise.

func IsURL

func IsURL(u *url.URL) bool

IsURL returns whether the given url.URL is probably a URL (as opposed to just a normal string of text)

func New

func New[T gi.Widget](ctx *Context) T

New adds a new widget of the given type to the context parent. It automatically calls Context.Config on the resulting widget.

func NewValue

func NewValue(ctx *Context, val any) giv.Value

NewValue adds a new giv.Value with the given value to the context parent. It automatically calls Context.Config on the resulting value widget.

func NodeString

func NodeString(n *html.Node) (start, end string)

NodeString returns the given node as starting and ending strings in the format:

<tag attr0="value0" attr1="value1">

and

</tag>

It returns "", "" if the given node is not an html.ElementNode

func NormalizeURL

func NormalizeURL(u *url.URL)

NormalizeURL sets the scheme of the URL to "https" if it is unset.

func ParseRelativeURL

func ParseRelativeURL(rawURL, base string) (*url.URL, error)

ParseRelativeURL parses the given raw URL relative to the given base URL.

func ParseURL

func ParseURL(rawURL string) (*url.URL, bool)

ParseURL parses and normalized the given raw URL. If the given RawURL is actually a URL (as specified by IsURL), it returns the URL and true. Otherwise, it returns nil, false.

func PkgGoDevWikilink

func PkgGoDevWikilink(url string) func(w *wikilink.Node) (destination []byte, err error)

PkgGoDevWikilink returns a wikilink resolver that points to the pkg.go.dev page for the given project URL (eg: cogentcore.org/core)

func ReadHTML

func ReadHTML(ctx *Context, par gi.Widget, r io.Reader) error

ReadHTML reads HTML from the given io.Reader and adds corresponding Cogent Core widgets to the given gi.Widget, using the given context.

func ReadHTMLNode

func ReadHTMLNode(ctx *Context, par gi.Widget, n *html.Node) error

ReadHTMLNode reads HTML from the given *html.Node and adds corresponding Cogent Core widgets to the given gi.Widget, using the given context.

func ReadHTMLString

func ReadHTMLString(ctx *Context, par gi.Widget, s string) error

ReadHTMLString reads HTML from the given string and adds corresponding Cogent Core widgets to the given gi.Widget, using the given context.

func ReadMD

func ReadMD(ctx *Context, par gi.Widget, b []byte) error

ReadMD reads MD (markdown) from the given bytes and adds corresponding Cogent Core widgets to the given gi.Widget, using the given context.

func ReadMDString

func ReadMDString(ctx *Context, par gi.Widget, s string) error

ReadMDString reads MD (markdown) from the given string and adds corresponding Cogent Core widgets to the given gi.Widget, using the given context.

func RootNode

func RootNode(n *html.Node) *html.Node

RootNode returns the root node of the given node.

Types

type Context

type Context struct {
	// Node is the node that is currently being read.
	Node *html.Node

	// Styles are the CSS styling rules for each node.
	Styles map[*html.Node][]*css.Rule

	// Widgets are the gi widgets for each node.
	Widgets map[*html.Node]gi.Widget

	// NewParent is the current parent widget that children of
	// the previously read element should be added to, if any.
	NewParent gi.Widget

	// BlockParent is the current parent widget that non-inline elements
	// should be added to.
	BlockParent gi.Widget

	// InlinePw is the current parent widget that inline
	// elements should be added to; it must be got through
	// [Context.InlineParent], as it may need to be constructed
	// on the fly. However, it can be set directly.
	InlinePw gi.Widget

	// PageURL, if not "", is the URL of the current page.
	// Otherwise, there is no current page.
	PageURL string

	// OpenURL is the function used to open URLs.
	OpenURL func(url string)

	// WikilinkResolver, if specified, is the function used to convert wikilinks into full URLs.
	WikilinkResolver func(w *wikilink.Node) (destination []byte, err error)
}

Context contains context information about the current state of a coredom reader and its surrounding context. It should be created with NewContext.

func NewContext

func NewContext() *Context

NewContext returns a new Context with basic defaults.

func (*Context) AddStyle

func (c *Context) AddStyle(style string)

AddStyle adds the given CSS style string to the page's compiled styles.

func (*Context) Config

func (c *Context) Config(w gi.Widget)

Config configures the given widget. It needs to be called on all widgets that are not configured through the New pathway.

func (*Context) InlineParent

func (c *Context) InlineParent() gi.Widget

InlineParent returns the current parent widget that inline elements should be added to.

func (*Context) Parent

func (c *Context) Parent() gi.Widget

Parent returns the current parent widget that a widget associated with the current node should be added to. It may make changes to the widget tree, so the widget must be added to the resulting parent immediately.

func (*Context) ResolveWikilink

func (c *Context) ResolveWikilink(w *wikilink.Node) (destination []byte, err error)

ResolveWikilink implements wikilink.Resolver.