htmlcore

Documentation

Overview

Package htmlcore converts HTML and MD into Cogent Core 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 GetURLFromFS(fsys fs.FS, rawURL string) (*http.Response, error)
• func HasAttr(n *html.Node, attr string) bool
• func New[T tree.NodeValue](ctx *Context) *T
• func ReadHTML(ctx *Context, parent core.Widget, r io.Reader) error
• func ReadHTMLString(ctx *Context, parent core.Widget, s string) error
• func ReadMD(ctx *Context, parent core.Widget, b []byte) error
• func ReadMDString(ctx *Context, parent core.Widget, s string) error
• type Context
  • func NewContext() *Context
  • func (c *Context) AddWikilinkHandler(h WikilinkHandler)
  • func (c *Context) InlineParent() core.Widget
  • func (c *Context) LinkButton(bt *core.Button, url string) *core.Button
  • func (c *Context) Parent() core.Widget
• type WikilinkHandler
  • func GoDocWikilink(prefix string, pkg string) WikilinkHandler

Variables

var BindTextEditor func(ed *texteditor.Editor, parent *core.Frame, language string)

BindTextEditor is a function set to cogentcore.org/core/yaegicore.BindTextEditor when importing yaegicore, which provides interactive editing functionality for Go code blocks in text editors.

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 core.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 [Context.GetURL] 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 GetURLFromFS

func GetURLFromFS(fsys fs.FS, rawURL string) (*http.Response, error)

GetURLFromFS can be used for [Context.GetURL] to get resources from the given file system.

func HasAttr

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

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

func New

func New[T tree.NodeValue](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 ReadHTML

func ReadHTML(ctx *Context, parent core.Widget, r io.Reader) error

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

func ReadHTMLString

func ReadHTMLString(ctx *Context, parent core.Widget, s string) error

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

func ReadMD

func ReadMD(ctx *Context, parent core.Widget, b []byte) error

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

func ReadMDString

func ReadMDString(ctx *Context, parent core.Widget, s string) error

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

Types

type Context

type Context struct {

	// Node is the node that is currently being read.
	Node *html.Node

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

	// BlockParent is the current parent widget that non-inline elements
	// should be added to.
	BlockParent core.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,
	// which defaults to [system.App.OpenURL].
	OpenURL func(url string)

	// GetURL is the function used to get resources from URLs,
	// which defaults to [http.Get].
	GetURL func(url string) (*http.Response, error)

	// 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.
	ElementHandlers map[string]func(ctx *Context) bool

	// WikilinkHandlers is a list of handlers to use for wikilinks.
	// If one returns "", "", the next ones will be tried instead.
	// The functions are tried in sequential ascending order.
	// See [Context.AddWikilinkHandler] to add a new handler.
	WikilinkHandlers []WikilinkHandler
	// contains filtered or unexported fields
}

Context contains context information about the current state of a htmlcore 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) AddWikilinkHandler

func (c *Context) AddWikilinkHandler(h WikilinkHandler)

AddWikilinkHandler adds a new WikilinkHandler to [Context.WikilinkHandlers]. If it returns "", "", the next handlers will be tried instead. The functions are tried in sequential ascending order.

func (*Context) InlineParent

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

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

func (*Context) LinkButton

func (c *Context) LinkButton(bt *core.Button, url string) *core.Button

LinkButton is a helper function that makes the given button open the given link when clicked on, using [Context.OpenURL]. The advantage of using this is that it does tree.NodeBase.SetProperty of "href" to the given url, allowing generatehtml to create an <a> element for HTML preview and SEO purposes.

func (*Context) Parent

func (c *Context) Parent() core.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.

type WikilinkHandler

type WikilinkHandler func(text string) (url string, label string)

WikilinkHandler is a function that converts wikilink text to a corresponding URL and label text. If it returns "", "", the handler will be skipped in favor of the next possible handlers. Wikilinks are of the form [[wikilink text]]. Only the text inside of the brackets is passed to the handler. If there is additional text directly after the closing brackets without spaces or punctuation, it will be appended to the label text after the handler is run (ex: [[widget]]s).

func GoDocWikilink

func GoDocWikilink(prefix string, pkg string) WikilinkHandler

GoDocWikilink returns a WikilinkHandler that converts wikilinks of the form [[prefix:identifier]] to a pkg.go.dev URL starting at pkg. For example, with prefix="doc" and pkg="cogentcore.org/core", the wikilink [[doc:core.Button]] will result in the URL "https://pkg.go.dev/cogentcore.org/core/core#Button".