Package damsel provides html outlining via css-selectors and common template functionality.

Daniel Skinner

Last update: Oct 23, 2022

Related tags

Template Engines damsel

Overview

Damsel

Markup language featuring html outlining via css-selectors, extensible via pkg html/template and others.

Library

This package expects to exist at $GOPATH/src/dasa.cc/damsel and can be installed with:

go get dasa.cc/damsel

Command Line

A command line utility can be installed with:

go get dasa.cc/damsel/cmd/damsel

View help with:

damsel -h

Documentation

http://godoc.org/dasa.cc/damsel

Package damsel provides html outlining via css-selectors and common template functionality.

Attributes

Attributes can be inlined, line-breaked, or a combination of such. Provide quotes around the attribute value to escape brackets.

%html %body

  %div[a=1][b=2]

  #foo
    [a="1[1]"]
    [b="2[2]"]

  #bar[a=1][b=2]
      [c=3][d=4]

  %span[a][b] Attributes do not require values

Text and Whitespace

Whitespace can be manipulated as described below, but it's worth pointing out that large amounts of content are simply not suitable for such document types (Damsel, Haml, etc).

%p One
  \ Two
  \ Three

%p    One Two Three

Both paragraphs will be rendered the same. Use of a backslash controls whitespace, including inlined text.

%p \ One Two Three

This would insert a space before One.

Whitespace can be preserved using `

%p `this is some
text and all whitespace
    is preserved as-is`

HTML Comments

Supports commenting out blocks of code via html comments with optional text and browser specfic IFs. This also includes DOCTYPE declarations.

!DOCTYPE html
%html %body
  ! %ul
    %li 1
    %li 2

The use of ! as a block element, causing %ul to become inlined, will cause the entire block to become commented out. The ! could also be placed after the body tag in this case. You can also nest items under a comment.

%html %body
  ! here's a comment though it's not required
    %h1 Hello World

  %div
    ! this comment doesn't enclose any tags
    %span Hello World

  ![if IE] %p Internet Explorer

Actions

There is basic support for actions. An action is just another way of calling a function while also preserving indention of the inner content lines, making this suitable for parsing other indention based markup. Once an action has been processed, the lexer will parse the result as though it was part of the original document.

In time, this package will facilitate custom functions. Currently included actions are js, css, include, and extends.

%html %head
  :css /css/
    main.css
    extra.css

This would generate the following document.

%html %head
  %link[type=text/css][rel=stylesheet][href=/css/main.css]
  %link[type=text/css][rel=stylesheet][href=/css/extra.css]

Reusable Templates

Damsel allows any element with an id specified to be overridden. Also required is at least one root node that will serve as the main document output. Additional root nodes are checked against the first for overridable content.

%html %body
  #content
    %p Hello

#content OVERRIDE

The would produce the following output.

<html><body>
  <div id="content">OVERRIDE</div>
</body></html>

This functionality is also facilitated with the action extends.

:extends overlay.dmsl

#content OVERRIDE

If you wish to append child nodes instead of overriding the original content, specify a super attribute.

:extends overlay.dmsl

#content[super]
  %p A second paragraph

The action include uses the whitespace preceding its declaration to insert content from a separate document into the current. For example, given the following document:

%ul
  %li One
  %li Two

included in the following document:

%html %body
  #content
    %h1 My Numbers
    :include numbers.dmsl

would produce the following document:

%html %body
  #content
    %h1 My Numbers
    %ul
      %li One
      %li Two

Other Template Integration

This package should be ok for use with most text templating options. Helpers that provide integration with html/template take the following steps.

- Call dmsl/parse.ActionParse(b []byte)
- Pass the result to package html/template and execute
- Call dmsl/parse.DocParse(b []byte)
- Display result

Calling dmsl.NewHtmlTemplate will return an instance that parses actions and passes the result to html/template.Template. Call Execute(interface{}) to produce the final result. For example, given [10][10]int:

%html %body
  %table {range .}
    %tr {range .}
      %td {.}
{end}{end}

At one-point the {end} was optional with deeper integration of html/template, but in practice this created confusion and errors except for the most trivial of examples (above).

Here's another example.

%html %body
  %table
  {range .}

    {if .}

    %tr
    {range .}
      %td {.}
    {end}

    {else}
    %tr %td None
    {end}

    %p some trailing text
  {end}

⚗ The most advanced CLI template on earth! Featuring automatic releases, website generation and a custom CI-System out of the box.

cli-template ✨ ⚗ A template for beautiful, modern, cross-platform compatible CLI tools written with Go! Getting Started | Wiki This template features

46 Dec 4, 2022

Comments

compile problem

cd github.com/dskinner/damsel/ go install main.go:7:2: import "dasa.cc/damsel/dmsl": cannot find package main.go:8:2: import "dasa.cc/damsel/dmsl/parse": cannot find package

opened by rif 2
is % really necessary?
In the py project, it certainly was for differentiating a line of python from html.

x = 5 %p {x}

It also enabled inlined tags

%html %body %h1 Hello World

The three options in my mind worth considering are

Remove From First Element

Due to how plain text works right now, the line contained by the element needs no special notation, but multiline plain text requires a back slash, mostly to properly control whitespace. It is feasible to not require % except for inlining

html body div %h1 Hello World div a b c d \ e f g

I feel this is a bit hard to distinguish whats going on though. Which brings me to the other option

Swap control needs from elements to text

Essentially, remove the need for % and require something for all text. The example below uses \

html body div \ a b c d \ e f g h

Considering the use case of damsel (discussed below) this wouldn't be a bad option, but I do feel it might become more burdensome to seemingly arbitrarily insert a character to start text mid declaration versus the somewhat easy habit of starting a new line with %. A % also gives each element a distinct look, such %div #id .class

Finally, this brings me back to

Leave it alone

Something like damsel suits a particular need of development, and that need is not for large content writeups. It's ideal for stubbing out an interface that will have most of its content insert by variables, and heavily scripted by javascript, making it easy to reference the dom you've created. I already feel the syntax accomplishes that through my use of it on multiple projects. If the constraints I worked under at the time just happen to produce the best results I can come up with, then it may be best to simply leave it alone.
question
opened by dskinner 1