Component Custom HTML Properties/Attributes

The data-based formatting of the content of the bound component can be configured by custom HTML attributes, which can be specified in several ways. By default, custom ichigo attributes begin with the string "i5_" as in the example i5_html, but as a shortcut you might prefer to use the colon ":" in place of "iv_" as in :html.

Both those attribute schemas are valid HTML, but to purists, attributes not in the HTML standard should be avoided. I can totally relate to the purist point of view, so you can also use data attributes (e.g. data-i5_html) or the properties or attributes of the component constructor (e.g. new BoundComponent(vm, { properties: { i5_html: "someField" } }). The colon (which isn't valid in JS properties) can be replaced by underscore. The minus sign can be replaced by zero.

The value of the custom attribute is the field on the view model that should be used to provide the value. There are a few variations. For more information, see the page on component value sources, once it has been written.

world ... nonmatching
A copy:
Some styled content
Some red bold content
Some red content
Some bold content
Visible (shouldn't see the text "Invisible" below)
Invisible (shouldn't see this)
.
Link to the demo script

API

Code Detail
id

Sets the id of a component. This is just the normal HTML id, not actually part of ichigo at all. It deserves to be called out here though if you nest components.

If you have a very simple case, one component by itself, then you are OK just using i-v replacements by themselves. But in most use cases, components are nested inside other components, and if you are applying components to areas static HTML, it's necessary to indicate which component a given tag references, otherwise the wrong component will be updated. This is handled by referencing the id of the component, using #id, component="id", or data-component="id" (pick your favorite syntax). This check is case-insensitive.

See the following example: <div id="the_name"> <i-v #the_name>updated_prop</i-v> <i-v #something_else>not_updated_prop</i-v> </div>. Here, only i-v #the_name is updated, not i-v #something else.

If you intend to have nested components, you should assign ids to all replacements. It's easy to create a scenario like this obviously bad one: <some-outer-component id="outer"> <div id="the_inner_component"> <i-v>accidentally_updated_prop</i-v> <i-v #outer>prop</i-v> </div></some-outer-component>. In this scenario, some-outer-component will replace both i-v tags.

If you are nesting components, always bind from outermost to innermost. When you create a component, its innerHTML is replaced, meaning that any previous components having references to elements in that HTML are now referencing nonexistent elements.

i5_text

Sets the innerHTML, escaping HTML.

i5_html

Sets the innerHTML, not escaping HTML.

i5_value

Sets the value of the form field (only works for form fields). It works even on form fields, such as textarea, that don't have a value attribute.

i5_input

Binds input events on the form field to the BoundComponent.write() method. If the view model property (which is optional) is set, it indicates the field that should be updated.

i5_target

Sets additional properties to be updated by BoundComponent.write().

:input: or i5_input: or i5_input_value

Sets up two-way binding on a view model property. A shortcut for :input="prop" :value="prop".

i5_target

Binds input events on the form field to the BoundComponent.write() method.

i5_attr:some_attribute_name or i5_attr_some_attribute_name

Sets the attribute named some_attribute_name.

i5_bool:some_attribute_name or i5_bool_some_attribute_name

Adds the boolean attribute named some_attribute_name if the view model property is truthy, else removes it.

i5_bool-:some_attribute_name or i5_bool0_some_attribute_name

Removes the boolean attribute named some_attribute_name if the view model property is truthy, else adds it.

i5_style

Sets the style string.

i5_class

Sets the className string.

i5_switch:some_class_name or i5_switch_some_class_name

Adds the class named some_class_name if the view model property is truthy, else removes it.

i5_switch-:some_class_name or i5_switch0_some_class_name

Removes the class named some_class_name if the view model property is truthy, else adds it.

i5_if

Hides the object (using CSS display:none) if the view model property is truthy, else shows it. If it was previously set to, for example, display:block, then that will be restored. If it wasn't, then Ichigo can't read your mind so hopefully you don't need a specific display property. You could complain to the W3C to split visibility and blocking into two properties, but you'd do better to just use a class.

i5_if- or i5_if0

Hides the object (using CSS display:none) if the view model property is falsy, else shows it.

i5_loop

Repeat the contents of the element once for every item in the view model iterable. After each item is added, the method loopPostProcess() is called taking these inputs: (row: ItemIterated, addedContent: Node[], allRows: Iterable, previousContent: DocumentFragment). LoopPostProcess is intended to convert the added HTML to a component.

i5_loop:null or i5_loop_null

Repeat the contents of the element once for every item in the view model iterable. After each item is added, the method loopPostProcess() is NOT called.

i5_item

(optional) After content has been repeated using i5_loop, the i5_loop selector indicates the HTML object that should be converted to a component by loopPostProcess(). The property of the i5_item attribute does not matter.

If not included, then loopPostProcess() grabs the first, topmost level element. In 99.9% of cases, this is a fine, so i5_item is not needed.

i5_event (eventName)="method"

Calls addEventListener(eventName, component[method].bind(component)).

Type definitions