Proposal for substitution syntax to ease writing "inline" elements in HAML

[Yaohan Chen]

When writing inline elements in HAML, one usually has to resort to writing raw
HTML or using a filter like markdown. For example to produce the following
HTML:
<p>Please <a href="contact">contact us</a> for any questions!</p>

One can use raw HTML for the inline element, sacrificing some readability:
%p Please <a href="contact">contact us</a> for any questions!

Or one can use markdown, which might lack control or features. Either of these
solutions requires working in "an additional language", which I think almost
undoes HAML's effort in simplifying markup.

I would like to propose a substitution feature to improve this. Below are
three examples using it:

/ Most simple form
%p Please ^contact_us for any questions!
^contact_us %a(href="contact") contact us

/ The substitution place holder can be wrapped in { }
/ Useful when there are word characters following it
%p Please ^{contact_us} for any questions!
^contact_us %a(href="contact") contact us

%p Please ^contact_us for any questions!
^contact_us
/ Multiple lines of substitution content can be written in indentation
%a(href="contact") contact us

This is similar to ReStructuredText's approach with dealing with inline
markup.

What do you think, and has any similar idea been considered or already
implemented?


Yaohan Chen

[Hampton]

While I agree that the inline stuff isn't ideal... every proposal for a solution hasn't
been up to the spec of looking beautiful and readable. Honestly, even
this simple example is confusing syntactically.

Keep thinking on it though. I'm more than happy if someone can make it simple,
easy, and obvious. But, until that point... the other options are servicable and I believe,
better than badly designed syntax.

Sorry. :P

But, keep up the brainstorming!

-hampton.

--

You received this message because you are subscribed to the Google Groups "Haml" group.
To post to this group, send email to ha...@googlegroups.com.
To unsubscribe from this group, send email to haml+uns...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/haml?hl=en.

[Yaohan Chen]

Thanks for your reply, Hampton.

I agree that the syntax I proposed could be confusing. I also
considered letting the substitution pairs be written in YAML format,
indented after the substituted line. However that would break the
convention of "content cannot be both given on the same line and
nested within it" in HAML. On the other hand, without indentation, the
substitution pairs could be confused as plain text.

However I think the substitution approach is good, because it allows
all of HAML's syntactic goodness to be used for the inline elements.

It occurred to me that this feature does not necessarily require
modifying HAML. It can be implemented as a filter, for example:

:substitute
%p {Please} {contact us} for any questions!
---
Please: %em Please
contact us: %a(href="contact") contact us

Basically everything before --- is HAML, with place-holders enclosed
in braces. Everything from --- is YAML, defining a mapping between
place holder names and their substitutions in HAML. When a place-
holder is not defined, I think it should be left as-is, including the
braces, so there is no need to escape them most of the time.


Yaohan Chen

> > haml+uns...@googlegroups.com <haml%2Bunsu...@googlegroups.com>.

[Alex Wallace]

I would find that very confusing, especially if errors or warnings were thrown for missing key/value pairs or an unescaped bracket. I like the approach but I find it pretty confusing. 

My personal method of solving "ugly" inline markup is to use rails helpers inline with ruby interpolated markup. It's not perfectly clean, but it's readable and it allows me to avoid sticking <tag><soup> all over my clean haml files. If storing all key/value pairs separately suits you better, interpolating them as instance variables through basic string concats still fits the bill. e.g.

= "Link to #{ link_to "foo", "bar" } inline!"

Best,

Alex

To unsubscribe from this group, send email to haml+uns...@googlegroups.com.

[Nathan Weizenbaum]

Note that you don't actually need to use quotes here; you can just do

Link to #{link_to "foo", "bar"} inline!

[Yaohan Chen]

Alex,

There would be no error or warning with undefined placeholders. The
idea is that you can still use braces freely, but the presence of both
the braces and the corresponding substitution pair are required to
trigger substitution. Also, the syntax I gave was for a filter, not
direct HAML.

Using helpers could help somewhat, but if it is bad to put control
logic in views, it can be argued that it is bad to put view stuff in
helpers. At least, it can hurt maintainability to put relevant things
in different places, when there is no potential for reuse and code
simplification. Reusable view elements like link_to are fine for me,
but users can't be expected to write a new helper for every inline
markup element they use. link_to seems also limited to plain text
content, so if you need to have more inline elements in the <a> you
would be stuck. First time users would probably also need to read the
framework documentation to know how or whether it is possible to add
extra attributes. Lastly, HAML can be used standalone, rather than
with Rails, Staticmatic, etc.


Yaohan Chen

> > haml%2Bunsu...@googlegroups.com<haml%252Buns...@googlegroups.com>

[Alex Wallace]

I don't have much more to add re: inline substitution haml syntax, but helpers are primarily for simplifying markup generation, and would definitely come in handy in this context. To be honest I use them for both tidying my controllers and my views, but their primary purpose [1] is for "Helper functions to be used from the.. views".

Best,
Alex

[1] http://guides.rubyonrails.org/getting_started.html

To unsubscribe from this group, send email to haml+uns...@googlegroups.com.

[Steve Howell]

On Dec 3, 5:25 pm, Yaohan Chen <yaohan.c...@gmail.com> wrote:
> When writing inline elements in HAML, one usually has to resort to writing raw
> HTML or using a filter like markdown. For example to produce the following
> HTML:
>   <p>Please <a href="contact">contact us</a> for any questions!</p>
>
> One can use raw HTML for the inline element, sacrificing some readability:
>   %p Please <a href="contact">contact us</a> for any questions!
>
> Or one can use markdown, which might lack control or features. Either of these
> solutions requires working in "an additional language", which I think almost
> undoes HAML's effort in simplifying markup.
>
> I would like to propose a substitution feature to improve this. Below are
> three examples using it:
>
>   / Most simple form
>   %p Please ^contact_us for any questions!
>   ^contact_us %a(href="contact") contact us
>

My thoughts are:

p | Please [[a href="contact" | contact us ]] for any questions

Or:

p
| Please \
a href="contact" | contact us \
| for any questions

My thoughts on your syntax is that substitution is unnecessary is if
you can either drop down to more interpolation with [[ foo ]] syntax
or concatenate expressions into one line of HTML with the backslash.

Orthogonal to your problem statement are the ideas that the percent
sign is pure cruft for calling out HMTL tags and that pipe symbols
should call out content. But I wanted to express your HTML in the
cleanest syntax that I could imagine.