Skip to content

Manipulating Tags

Jump to bottom
manolo edge edited this page Jun 3, 2025 · 7 revisions

With Cardboard you can manipulate/modify elements. Manually or conditionally.

Quick Reference

Here's a quick example showing both manual and conditional manipulation:

const myElement = tag('button');

// Manual modification
myElement.addClass('primary');
myElement.setAttr('type', 'button');
myElement.setStyle({ color: 'white', backgroundColor: 'blue' });

// Conditional/reactive modification
const isDisabled = state(false);
myElement.disableIf(isDisabled);

const isActive = state(true);
myElement.classIf(isActive, ['active']);

Table of contents

You can use these links to quickly navigate to the respective sections of your README document.

Element Modification Methods

The CTag class provides several methods for modifying the attributes, styles, and classes of the associated HTML element. These methods are designed to make it easy to manipulate the appearance and behaviour of the element.

addClass

  • Description: Adds one or more CSS classes to the element's class list.

  • Parameters:

    • classes (string[]): One or more CSS classes to add to the element.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
myElement.addClass('my-class', 'another-class');
// The element's class attribute is updated: <div class="my-class another-class"></div>

setClassName

  • Description: Sets the element's className attribute to the provided class name, replacing any existing classes.

  • Parameters:

    • className (string): The new class name for the element.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
myElement.setClassName('custom-class');
// The element's class attribute is updated: <div class="custom-class"></div>

setStyle

  • Description: Sets one or more CSS styles for the element.

  • Parameters:

    • styles (StyleMap): A JavaScript object representing a map of CSS properties and their values.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
myElement.setStyle({ color: 'red', fontSize: '16px' });
// The element's style is updated: <div style="color: red; font-size: 16px;"></div>

setAttrs

  • Description: Sets multiple attributes for the element.

  • Parameters:

    • attrs ({ [k: string]: string }): An object where keys are attribute names, and values are attribute values.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('a');
myElement.setAttrs({ href: 'https://example.com', target: '_blank' });
// The element's attributes are updated: <a href="https://example.com" target="_blank"></a>

addAttr

  • Description: Adds a single attribute to the element. If the attribute already exists, it updates the value.

  • Parameters:

    • key (string): The name of the attribute.
    • value (string, optional): The value of the attribute. Default is an empty string.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('input');
myElement.addAttr('type', 'text');
// The element's attribute is updated: <input type="text">

rmAttr

  • Description: Removes one or more attributes from the element.

  • Parameters:

    • attrs (string[]): One or more attribute names to remove.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('a');
myElement.rmAttr('href', 'target');
// The element's attributes are removed: <a></a>

hasAttr

  • Description: Checks if the element has one or more attributes.

  • Parameters:

    • attr (string[]): One or more attribute names to check.

  • Returns: true if all specified attributes are present, false otherwise.

  • Example:

const myElement = tag('input');
myElement.addAttr('type', 'text');
const hasTypeAttribute = myElement.hasAttr('type'); // true
const hasValueAttribute = myElement.hasAttr('value'); // false

getAttr

  • Description: Gets the value of a specific attribute of the element.

  • Parameters:

    • attr (string): The name of the attribute to retrieve.

  • Returns: The value of the specified attribute or undefined if the attribute is not present.

  • Example

const myElement = tag('a');
myElement.addAttr('href', 'https://example.com');
const hrefValue = myElement.getAttr('href');

console.log(hrefValue); // Output: "https://example.com"

hide

  • Description: Hides the element from the DOM.

  • Returns: The CTag instance for method chaining.

  • Example

const myElement = tag('a');
myElement.hide();
// myElement will not be in the DOM

show

  • Description: The show() method is used to display the element associated with a CTag instance. If the element was previously hidden, it will be added back to the DOM in its correct position. This method returns a promise that resolves once the element is successfully shown.

  • Returns: The CTag instance for method chaining.

  • Example

const myElement = tag('a');
myElement.show();
// myElement will be in the DOM

disable

  • Description: The disable() method is used to disable the element associated with a CTag instance. It sets the 'disabled' attribute on the element, preventing user interaction.

  • Returns: The CTag instance for method chaining.

  • Example

const myElement = tag('input');
myElement.disable();
// myElement will be disabled

enable

  • Description: The enable() method is used to enable the element associated with a CTag instance. It removes the 'disabled' attribute from the element, allowing it to be interacted with.

  • Returns: The CTag instance for method chaining.

  • Example

const myElement = tag('input');
myElement.disable();
// myElement will be enabled

setDisabled

  • Description: The setDisabled(disabled: boolean) method allows you to explicitly set whether the element should be disabled or enabled based on the value of the disabled parameter.

  • Returns: The CTag instance for method chaining.

  • Example

const myElement = tag('input');
myElement.setDisabled(true);
// myElement will be disabled

Conditional Element Manipulation Methods

The CTag class provides a set of methods for conditionally (or reactively) modifying the appearance and behaviour of the associated HTML element based on specified conditions. These methods make it easy to add or remove classes, styles, text, and attributes to the element when certain conditions are met.

All methods that can be reactivelly modified end with If or IfNot. These methods work by listening to the Observable that's passed in as an argument. Whenever the consumable changes, the properties/conditions will update.

There's a list of premade conditionals, but you can create them by yourself by using consume.

consume

Description: Takes in a Observable and a callback. The callback will be called any time the consumable changes. This is useful if there's no built-in condition available.

  • Parameters:

    • consumable (Observable<T>): A consumable object that represents a condition.
    • consumer ((self: CTag, newValue: T) => void): A callback that will be called whenever the consumable changes.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isActive = state(true);

myElement.consume(isActive, (self, active) => {
    if(active) {
        console.log('active!');
    } else {
        console.log('not active!');
    }
});

classIf

Description: Add one or more CSS classes to the element when a specified consumable is truthy. Updates whenever the consumable changes.

  • Parameters:

    • consumable (Observable<any>): A consumable object that represents a condition.
    • classes (string[] | ((self: CTag) => string[])): An array of CSS classes or a function that returns an array of CSS classes to be added when the consumable is truthy.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isActive = state(true);

myElement.classIf(isActive, ['active', 'highlighted']);
// The "active" and "highlighted" classes are added to the element because the condition is truthy.

classIfNot

Description: Remove one or more CSS classes from the element when a specified consumable is truthy. This is the opposite of classIf.

  • Parameters:

    • consumable (Observable<any>): A consumable object that represents a condition.
    • classes (string[] | ((self: CTag) => string[])): An array of CSS classes or a function that returns an array of CSS classes to be removed when the consumable is truthy.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isActive = state(true);

myElement.classIfNot(isActive, ['active', 'highlighted']);
// The "active" and "highlighted" classes are added to the element because the condition is false.

styleIf

Description: Add one or more CSS styles to the element when a specified consumable is truthy. Updates whenever the consumable changes.

  • Parameters:

    • consumable (Observable<any>): A consumable object that represents a condition.
    • styles (StyleMap | ((self: CTag) => StyleMap)): A map of CSS styles or a function that returns a map of CSS styles to be added when the consumable is truthy.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isHighlighted = state(true);

myElement.styleIf(isHighlighted, { color: 'blue', fontWeight: 'bold' });
// The specified styles are added to the element because the condition is truthy.

styleIfNot

Description: Remove one or more CSS styles from the element when a specified consumable is truthy. This is the opposite of styleIf.

  • Parameters:

    • consumable (Observable<any>): A consumable object that represents a condition.
    • styles (StyleMap | ((self: CTag) => StyleMap)): A map of CSS styles or a function that returns a map of CSS styles to be removed when the consumable is truthy.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isHighlighted = state(true);

myElement.styleIfNot(isHighlighted, { color: 'blue', fontWeight: 'bold' });
// The specified styles are added to the element because the condition is false.

stylesIf

Description: Add multiple CSS styles to the element when a specified consumable is truthy. Updates whenever the consumable changes.

  • Parameters:

    • consumable (Observable<any>): A consumable object that represents a condition.
    • styles (StyleMap | ((self: CTag) => StyleMap)): A map of CSS styles or a function that returns a map of CSS styles to be added when the consumable is truthy.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isActive = state(true);

myElement.stylesIf(isActive, {
  color: 'green',
  backgroundColor: 'yellow',
});
// The specified styles are added to the element because the condition is truthy.

stylesIfNot

Description: Remove multiple CSS styles from the element when a specified consumable is truthy. This is the opposite of stylesIf.

  • Parameters:

    • consumable (Observable<any>): A consumable object that represents a condition.
    • styles (StyleMap | ((self: CTag) => StyleMap)): A map of CSS styles or a function that returns a map of CSS styles to be removed when the consumable is truthy.

  • Returns: The CTag instance for method chaining.

  • Example:

const myElement = tag('div');
const isHighlighted = state(true);

myElement.stylesIfNot(isHighlighted, {
  color: 'green',
  backgroundColor: 'yellow',
});
// The specified styles are added to the element because the condition is false.

hideIf

  • Description: The hideIf() method hides the element associated with a CTag instance based on a condition. It takes a consumable as a condition, which determines whether to hide the element each time the consumable changes. If invert is set to true, the condition is inversed.

  • Parameters:

  • Returns: The CTag instance for method chaining.

  • Example

const hide = state(true);

const myTag = tag('div');
myTag.hideIf(hide);          // Hides when the condition is met
myTag.hideIf(hide, true);    // Hides when the condition is NOT met
// There is also a method for the inverse
myTag.hideIfNot(hide);       // Hides when the condition is NOT met

hideIfNot

  • Description: The hideIfNot() method displays the element based on a condition. It takes a consumable as a condition, which determines whether to show the element each time the consumable changes. If invert is set to true, the condition is inversed.

  • Parameters:

  • Returns: The CTag instance for method chaining.

  • Example

const show = state(true);
const myTag = tag('div');
myTag.hideIfNot(show);

disableIf

  • Description: The disableIf() method disables the element based on a condition. It takes a consumable as a condition, which determines whether to disable the element each time the consumable changes. If invert is set to true, the condition is inversed.

  • Parameters:

  • Returns: The CTag instance for method chaining.

  • Example

const disabled = state(true);
const myTag = tag('div');
myTag.disableIf(disable);       // Disable element when the condition is true
myTag.disableIf(disable, true); // Disable element when the condition is false
// There is also a method for the inverse
myTag.disableIfNot(disable);    // Disable element when the condition is false

disableIfNot

  • Description: The disableIfNot() method disables the element based on a condition. It takes a consumable as a condition, which determines whether to disable the element each time the consumable changes.

  • Parameters:

  • Returns: The CTag instance for method chaining.

  • Example

const disabled = state(true);
const myTag = tag('div');
myTag.disableIfNot(disable);    // Disable element when the value is NOT false

This Wiki is a work in progress, and your help is greatly appreciated!

If you have some free time and are interested in contributing to the wiki or the project in general, please don't hesitate to reach out. All contributions are welcome!

Cardboard

Dip your toes

Up to the waste!

Develop

Clone this wiki locally