KeepWrapper

v2 and above

The keepWrapper attribute, introduced in CitronJS v2, changes how developers interact with sample elements in their web apps! Unlike the default behavior where inserting a sample replaces the <sample> element entirely with its content, keepWrapper allows the original element to remain intact, enabling post-insertion edits to variables and the sample content itself.

Default Behavior Without keepWrapper

When you insert a sample into your HTML using CitronJS without the keepWrapper attribute, the <sample> element is replaced by the content defined for that sample. For example:

<sample name="Hello World"></sample>

Becomes:

<h1>Hello, World!</h1>

Using keepWrapper

To change this behavior, include the keepWrapper attribute when inserting your sample into the body of your HTML document. This instructs CitronJS to insert the sample content inside the original <sample> element rather than replacing it.

<sample name="Hello World" keepWrapper></sample>

Now, the insertion results in:

<sample name="Hello World" keepWrapper>
    <h1>Hello, World!</h1>
</sample>

Editing Variables After Insertion

With keepWrapper, you can easily modify the attributes of variables after the sample has been inserted. For instance, if "World" is a variable named "username", you can update its value by changing the attribute:

<sample name="Hello World" username="John" keepWrapper>
    <h1>Hello, World!</h1>
</sample>

Will update to:

<sample name="Hello World" username="John" keepWrapper>
    <h1>Hello, John!</h1>
</sample>

This capability allows for dynamic content updates by simply modifying the variable attribute.

Changing the sample

Additionally, keepWrapper enables you to change the sample content on-the-fly by modifying the name attribute to load a different sample in the same location.

Removing keepWrapper

If you decide to revert to the default behavior of loading the sample without the wrapper, you can simply remove the keepWrapper attribute. This option is useful when you want to refresh the sample content without maintaining the original <sample> element.