Ruby On Rails integration / Helper options

While we've certainly had a chance to look at the helpers provided by webface_rails in the previous sections, we haven't formalized how options passed to those helpers are processed.

The examples below use #define_component to demonstrate how to pass options. However, the same approach can be used when passing options to #component, #component_attr #component_part #component_template helpers as they all, one way or another use #define_component and pass the same options to it. The only difference would be that those helpers have a different set of arguments, but that's kind assumed.

Passing options related to Webface.js

First thing to remember about the options is that you don't need to pass data: {} inside the options hash. You certainly could, if you needed those for things unrelated to Webface.js, but if we're talking about data- attrubutes for html-tags that are used by Webface.js, then those are actually derived from attr-map specified or component name passed to the helper. For example this code:

= define_component :offer, "div", { data: {               |
    component_class: "OfferComponent",                    |
    id: "123"                                             |
    created_at "26 Aug 2019",                             |
    attr_map: "title:data-id,description:data-created-at" |
  }} do                                                   |

is actually equivalent to this:

= define_component :offer, "div", { |
    id: "123"                       |
    created_at "26 Aug 2019",       |
    attr_map: "id,created_at"       |
  } do                              |

Notice how we simplified the attr_map: "id,created_at" option value: this will be automatically expanded to attr-map="title:data-id,description:data-created-at" by webface_rails when generating html. But we could simply even that by using the mapped_attr option:

= define_component :offer, "div", { |
  mapped_attrs: {                   |
    id: "123",                      |
    created_at "26 Aug 2019",       |
  }} do                             |

Internally, mapped_attrs will just add the "title:data-id,description:data-created-at" to the resultion options hash, which will be used to generate html attributes.

The important thing to understand here is that because we specify attribute map this way or another (explicitly with attr_map or implicitly with mapped_attrs), webface_rails will correctly create appropriate html-attriubutes out of the options passed to the helper.

Passing options meant to be html attributes unrelated to Webface.js

Apart from Webface.js related options, you might want to pass some other ones, which are meant to be used as html attributes. And it's just as straightforward, you can just specify it along the other options and everything that's not in the attribute map or isn't a special keyword option (such as component_class) will be used to add html attribute of the same name. For example, here's how we add an inline style:

= define_component :offer, "div", { |
  style: "font-size: 90%;",         |
  mapped_attrs: {                   |
    id: "123",                      |
    created_at "26 Aug 2019",       |
  }} do                             |

or, if you, as we do, think inline styles is bad practice, you van specify a css class:

= define_component :offer, "div", { |
  class: "offer",                   |
  mapped_attrs: {                   |
    id: "123",                      |
    created_at "26 Aug 2019",       |
  }} do                             |

For the class attribute though, there is a nice shortcut:

= define_component :offer, ".offer", { |
  mapped_attrs: {                      |
    id: "123",                         |
    created_at "26 Aug 2019",          |
  }} do                                |


There would be a problem if we wanted to pass id and make it so that it is an html attribute id= because we're already passing a component attribute with the same name. Thus, it'd be best to rename the component attribute in yuor javascript code or manually pass it into the data: {} hash like this (which, really, complicates things, but for demonstrational purposes, let's do it):

= define_component :offer, "div", { |
    id: "123"                       |
    created_at "26 Aug 2019",       |
    data: { id: "123" },            |
    attr_map: "id,created_at",      |
    id: "unique_dom_id_123"         |
  } do                              |

This will, then, generate the following html:

As you can see, this avoids the naming conflict, although we wouldn't recommend having that conflict in the first place.