HTML to Hiccup Conversion

Recently I wrote about alternative HTML syntaxes and in-language HTML DSLs like Hiccup. Those posts were about the broad issues. This one is about a boring and practical one.

Hardly any project consists entirely of fresh newly-written HTML. Most projects have snippets of HTML brought in from a (hopefully properly licensed) framework or template. For example, sometimes to start an application page I’ll use some HTML from a Bootstrap example page.

Such examples are written in ordinary HTML, not an alternative syntax or DSL, so I need a way to quickly and mechanically convert HTML to (in this example) Hiccup. A couple of years ago I wondered this, did some research, and put a few answers in the Hiccup repo wiki. It (still unchanged as of this writing) lists these tools capable of converting HTML to Hiccup:

Of those three, I found hiccup-bridge and this workflow quite easy to use:

  1. Add [hiccup-bridge “1.0.0-SNAPSHOT”] to project.clj
  2. Save example HTML snippets or pages in files
  3. lein repl
  4. (require ‘[hiccup-bridge.core :as hicv])
  5. (require ‘clojure.pprint)
  6. (clojure.pprint/pprint (hicv/html->hiccup (slurp “html_source/plain.html”)))
  7. Copy output or portions thereof to source code
  8. Repeat for additional files

Of course this could easily be wrapped in to a one-liner command line operation; but for maximum convenience someone should make an online tool for this conversion, analogous to Html2Jade. Maybe I’ll make such a thing, if no-one else does first.

Separation of Concerns != Separate Languages

A while back I wrote about the merits (and problems) of alternative HTML syntax such as Jade, HAML, etc. Another form of alternative syntax for HTML is an “internal DSL” in a programming language. There are various examples out there, including Domo for JavaScript and Hiccup for Clojure/CLJS.

Screen Shot 2014-10-03 at 10.16.20 PMScreen Shot 2014-10-03 at 10.17.29 PM

Hiccup syntax (which is to say, Clojure syntax) is of particular interest to me. Clojure spans server and web client code very well, and Hiccup data structures can be fed directly to Reagent for a concise and efficient dynamic web application based on React under the hood. Observe this snippet:

…in which ordinary Clojure “for” is used for iteration in a web page. I am experimenting with this tool stack – who knows what might emerge.

Why would anyone want to do this?

The reasons I have heard most often are:

  • Many projects are excessively polyglot without good reason. Even an “all JavaScript” project with a Node server typically has JavaScript, HTML, CSS, perhaps Sass, and various mini-languages (like CSS selectors) embedded inside.
  • Separation of Concerns does not have to mean separation of programming languages; even with separate programming languages, there are countless examples of poor separation of concerns, such as Java logic in a JSP template.
  • Your main programming already has a way to (for example) loop, yet you need a new and different way to loop at each layer.

The main reasons to stick with typical, different languages per layer/concern are more obvious:

  • Developers and non-developers probably already know how to use HTML and CSS; in particular, non-developer designers may have little interest in anything but HTML.
  • There are millions examples online for HTML and CSS.
  • Everyone else uses HTML and CSS as they are, let’s just do the same thing.

So again, why would anyone do this? The answer is as with other choices to use unusual technology – a chance to beat the averages and produce more value per time spent.

Dynamic CSS Manipulation with JavaScript

Last week I attended the Manning’s Powered By JavaScript one-day conference, the day before Strange Loop. Here are some thoughts on the “Powered By” conference as a whole and on one talk:

Dump Less and SASS: Dynamic CSS Manipulation with JavaScript
Speaker: Michael Mikowski

I wrote recently about CSS, so this talk caught my attention more than any other that day.

Powered By JavaScript Mini-Review

Overall this mini-one-day conference was well executed:

  1. Interesting speakers
  2. Good venue
  3. Very convenient to attend the day before Strange Loop

But I would like to call out a few opportunities to improve:

  1. The registration process was slow, and understaffed. The team running the conference should be able to look at the number of attendees and staff the registration process based on it.
  2. The registration process included registration for speakers in the same line as attendees. As a result, when a speaker reached the front of the line there was a long diversion while the staff was excited to greet and visit with the speaker. That is a wonderful way to treat speakers; but they should be diverted out of the way of the hundreds of people standing in line behind them to just pick up a badge.
  3. This one-day conference was co-located with Strange Loop, so the planners should expect a lot of Strange Loop people there – and plan for students at roughly the same skill level. Unfortunately the JavaScript event was targeted toward less sophisticated developers than typically attend Strange Loop.
  4. Please watch the clock. Many of the speakers did not end at the appointed time.

That sounds too negative. This was a very good effort from Manning, and I recommend attending future Manning JavaScript events.

Diversion #1: The Book

The speaker Michael Mikowski is the co-author, with another speaker at this conference (Josh Powell), of the book “Single Page Web Applications: JavaScript end-to-end”. Based on what I heard at the conference, this book is a little behind the times compared with today’s toolsets. I don’t believe it mentions the current competitive tools out there like Ember, AngularJS, React, and so on. Rather it seems to be about good practices for using an older generation of tools. Still, this was a distraction, because the speaker was fantastic!

Diversion #2: The Speaker

I had not met or seen a talk by Mike Mikowski, but from a look at his website he is a sharp fellow with very interesting things to say. In particular, I wish I had been at his “Fog of SPA” talk; the slides are worth reading, and I wish there was a video to watch, those slides were probably backed up by great stories. (I don’t necessarily agree with every idea in it, though. For example, I find it usually is worth having a build process to use higher level tools.)

This Talk: Dynamic CSS Manipulation with JavaScript

To summarize briefly, the message of this talk was that writing Javascript to emit CSS can replace LESS, Sass, and other CSS tools. Instead of adding another language and server-side build process (for Sass or LESS) to address weaknesses in CSS, you can write JavaScript code which emits CSS, and run that JavaScript code on page load or when needed. There are several important bits to get right to make this performant, for example the CSS for a page should be swapped out all at once to avoid the browser repeatedly re-rendering.

I don’t recall if the talk was recorded on video, but if it appears online, watch it.

As is my (unfortunate?) custom, I will first review a couple of nitpicks:

  • The title of the talk was mis-capitalized as “Dump Less and SASS”, which gets the name of Sass wrong. (Until earlier in 2014, Less was called LESS, incidentally.)
  • I waited anxiously for a glorious revelation in which code that would appear on the slides. Unfortunately, code never appeared. Mike convinced me to consider this idea in the first few minutes. I was ready to look. Please show me code!

Now on to the good stuff. Mike’s idea is interesting and appealing, and perhaps compelling for certain types of web applications. Clearly for the application Mike and friends are building at Qualaroo, it is an ideal and very slick application of technology. Particular appealing ideas:

CSS responsiveness by means of media queries can only respond to the narrow-ish set of information available to a media query. This JavaScript CSS approach can respond to any information at all available to the page, including (for example) the current zoom level.

LESS and Sass offer a good set of abstractions, a big improvement over vanilla CSS. But they only offer what is in their respective boxes. With a JavaScript CSS approach, as a developer you can create whatever specific set of abstractions is valuable for the problem at hand in a specific application.

The JavaScript CSS approach does not need a server-side build process, because it simply runs a little bit of JavaScript in the browser on page load.

The JavaScript CSS approach reduces the number of HTTP requests to load content; the CSS arrives (in a “compressed” form, in the sense that JavaScript to write the specific CSS is probably smaller than that CSS) as part of the JavaScript request.

If you generate CSS programmatically, you don’t have to stop at JavaScript. You can use CoffeeScript to generate JavaScript which generates your CSS, for example.

Actual Code!

Fortunately, while this talk did not include code, there are plenty of other people online doing something vaguely similar, who do publish code. Here are some I found. It is great to see this approach is already out there is common use, not a proprietary invention!

http://www.responsivejs.com/

http://absurdjs.com/

The following are also similar, but for Clojure. There are numerous ways to write your CSS in a different language (JS or otherwise), which already have variables and subroutines and other useful features.

https://github.com/paraseba/cssgen

https://github.com/rathwell/clj-style

https://github.com/noprompt/garden

Taking CSS Seriously

At Oasis Digital, we have spent much of our effort over the last several years creating complex “single page” web applications. There is much to say about that, but today I’m writing about one specific sliver: styling the application pages with CSS. To do good work at scale when using CSS to style an application (versus a one-off “webpage”), the only path to success is to take CSS seriously as a language, and study how to use it in an idiomatic, semantic, maintainable way.

Unfortunately, thinking about CSS in this way is considered far into “advanced” CSS territory, and these topics received almost no attention from the countless online and off-line resources to learn CSS.

What does it mean to take CSS seriously? Briefly, it means learning the technology and patterns of use in depth, by studying what others have done and thinking about why and how to solve problems.

Idiomatic CSS

CSS written by experts tends to follow many idioms. These are patterns that have been found useful again and again: a consistent order of selectors, consistent use of white space and other formatting, and so on. There is a popularly cited online resource explaining some of the most common idioms, and A List Apart (which you should probably read extensively) has a busy topic area around CSS.

Robust CSS

Do you always use the same browser, with your window the same size, with the same settings? Then your CSS is probably not robust at all. It is quite easy to accidentally style in such a way that the slightest disruption in the layout causes unexpected unpleasant results.

The way to robustness is exposure to ongoing change. Use multiple browsers, and switch often. Adjust your font size every day up or down, for a good reason or no reason. Change the width and height of your browser window, don’t just always leave it maximized at whatever very common screen size you happen to use. Do you work on a PC? Try a Mac sometimes. You work on a Mac? Your CSS-styled pages probably change in some minor but irritating way if you haven’t looked on a PC.

Good CSS is robust. It is specified sufficiently but not over-specified. A particular anti-pattern to avoid: layout some elements; observe their width on your particular browser and settings; set the width of an element that is supposed to contain them to a hard-coded number based on that single observed width; then watch what happens when some minor difference in font or other matter makes something a little bit wider than you expected.

Appropriate CSS

A hammer is a great tool, but not every problem is a nail. Grid systems are wonderful, but not for every element on every page. To take CSS seriously, we must learn when and where to use grid systems, ad hoc floats, that shiny new flexbox, and even an old-fashioned table.

Layered CSS

Many projects today start with a CSS framework like Bootstrap or Foundation. Working in this context requires a keen awareness of how your CSS interacts with that provided by the framework. It is common to see CSS which randomly and arbitrarily overrides rules set by such a framework, with no regard for what sense those framework provided rules made. The typical result: layer upon layer of overrides, trying to fix a resulting problem by adding layer upon layer of of more overrides.

The key to winning this battle of layers is to stop fighting. To use the delete key extensively, trimming away excess CSS to fix problems rather than adding more. Adjust variables provided by your framework, instead of ad hoc overwriting its calculated class attributes. Understand exactly what layers are needed and why.

Semantic CSS

“Semantic” means “pertaining to the meanings of words”. But the problem many of us have around semantics isn’t so much of wrong meaning, but of applying the wrong names to the right meaning.

It seems everyone is taught, on their CSS journey, about the evil of the in-line style attribute. As a result, we see in the wild many CSS classes like this:

Thus allowing the CSS user to type class=”float-right” instead of style=”float: right;”.

This of course misses the point of the admonition against in-line style completely. It is not the literal use of the style attribute that is the problem, it is that the idea behind CSS is to mark up content with classes which say something about what the content is, then use CSS separately to apply a visual layout and so on.

If you can look at the name of a CSS class and know exactly the style settings it contains, it is probably not a very good name. But if you can look at a piece of content, and tell what CSS class you should apply based on what kind of content it is, you probably have a very good name.

Did I mention, don’t actually write CSS itself?

CSS is lacking critical facilities for abstraction and removal of duplication. There are persuasive arguments floating around that CSS is too broken to ever be fixed; and I would not argue against that. But given that we are mostly stuck with CSS for many types of applications, it is necessary to use a layer on top of CSS. The usual contenders are Sass and LESS. This means that all of these goals mostly apply to the Sass or LESS you write, rather than to the CSS generated from Sass or LESS.

People who have studied both usually conclude that Sass is a better choice than LESS, and indeed the former is what we most often use.

(A helpful tip: if you are using a CSS framework like Bootstrap or Foundation, use a version of those which is supplied using whichever language about CSS you have chose. For example, if you use Sass, use the Bootstrap Sass version – don’t use the normal Bootstrap LESS or the bare Bootstrap CSS files!)

Maintainable CSS

The net result of all of the above is maintainable CSS. CSS which you can keep adding to, in an incremental way, as the application you are styling continues to grow and improve. CSS which you or someone else can understand a year later. CSS which you can be proud of when someone looks under the hood.

Balanced CSS

CSS is not ideal; it has gradually accumulated features since the emergence of the web and therefore has legacy concerns, among other problems. The CSS to solve any particular problem might not be able to meet all of these design qualities at the same time. Therefore, good quality CSS strikes a balance: semantic enough, robust enough, idiomatic enough, and so on.

Rapidly Written CSS

Some of the ideas here sound like they could take a long time to code – but good CSS is faster to complete – bad CSS burns up far more hours than good, in the quest to create a finished system.

Of course, mastering tools can take a long time. The payoff is that a master usually creates code (CSS or otherwise) with high “first time quality”.

</rant>

At Oasis Digital, we are not perfect. We do not yet do all of these things perfectly all the time; there is sometimes a tradeoff between delivery speed and polish. But we do take CSS seriously, and we work hard to move in the right direction along all these axes.

Resources

 

(Cross-posted to the Oasis Digital blog.)

HTML Syntax: Threat or Menace?

Some developers love HTML: its syntax, its angle brackets, its duplicated tag names, its scent, its silky smooth skin. If you are among them, you probably don’t won’t like this post.

I appreciate the practicality of HTML: HTML is ubiquitous, so nearly every developer already knows it. Nearly every editor and IDE already syntax-highlights and auto-formats HTML. But I don’t care for HTML’s syntax. On some projects, I use tools that offer an alternative, simpler syntax for the underlying HTML/DOM data model.

Indentation-Based HTML Alternatives

The most popular HTML alternative syntax is a Python-like indentation-based syntax, in which element nesting in determined by start-of-line white space. Implementations of this idea include Jade, HAML, and Slim.

Of those, Jade seems the most polished, and there are multiple Jade implementations available: the original (JavaScript, for use in Node or the browser), Java, Scala, Python, PHP, and possibly others. Jade looks like this:

html2jade

There is a free, helpful HTML to Jade converter online thanks to Aaron Powell, shown in the above image. It can be used to translate HTML documents or snippets to Jade in a couple of clicks.

Non-HTML HTML Advantages

  1. Jade (and other tools) trivially do lot of things right, like balanced tags, with no need for IDE support.
  2. Generated HTML will automatically be “pretty” and consistent
  3. Generated HTML will always be well formed: Jade doesn’t have a way to express unbalanced tags!
  4. Very concise and tidy syntax.
  5. Cleaner diffs for code changes – less noise in the file means less noise in the diff.

Non-HTML HTML Disadvantages

  1. Another Language to Learn: People already know HTML; any of these tools is a new thing to learn.
  2. Build Step: any of these tools needs a build step to get from the higher level language to browser-ready HTML.
  3. Limited development tool support – you might get syntax highlighting and auto-completion, but you will need to look around and set it up.

Non-Arguments

  1. There is no “lock in” risk – any project using (for example) Jade as an alternative HTML syntax, could be converted to plain HTML templates in a few hours or less.
  2. Since it is all HTML at runtime, there is no performance difference.

Conclusion

On balance, I think it is a minor win (nice, but not indispensable) to use a non-HTML HTML syntax. At work, we do so on many of our projects..

 

Ancient History: JBuilder Open Tools

Some years ago, the Java IDE marketplace looked quite different than it does today. VisualAge was very popular. Borland’s JBuilder was another top contender. Since then, many of the good ideas from VisualAge ended up in Eclipse, while the JBuilder of that era was replaced by a newer, Eclipse-based JBuilder. Not everything ended up on Eclipse, though: NetBeans matured to a slick IDE (with its own plugin ecosystem), as did IDEA.

But this post isn’t about today, it’s about a leftover bit of history. Back in that era, I had a section of this web site dedicated to the numerous JBuilder “Open Tools” (plugins) then available. That content is long obsolete and I removed it years ago. Remarkably, this site still gets hits every day from people (or perhaps bots) looking for it.

I agree strongly that Cool URIs don’t change, but that’s OK, because my old JBuilder Open Tools content just wasn’t very cool anyway.

On the off chance you landed on this page looking for it, here is a Google link for your convenience, or you can take a look at web.archive.org’s snapshot of my old list.