With Cardboard you can manipulate/modify elements. [Manually](https://github.com/nombrekeff/cardboard-js/wiki/Manipulating-Tags/_edit#element-modification-methods) or [conditionally](https://github.com/nombrekeff/cardboard-js/wiki/Manipulating-Tags/_edit#conditional-element-manipulation-methods). ## Quick Reference Here's a quick example showing both manual and conditional manipulation: ```typescript 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 - [Element Modification Methods](#element-modification-methods) - [`addClass`](#addclass) - [`setClassName`](#setclassname) - [`setStyle`](#setstyle) - [`setAttrs`](#setattrs) - [`addAttr`](#addattr) - [`rmAttr`](#rmattr) - [`hasAttr`](#hasattr) - [`getAttr`](#getattr) - [`hide`](#hide) - [`show`](#show) - [`disable`](#disable) - [`enable`](#enable) - [`setDisabled`](#setdisabled) - [Conditional Element Manipulation Methods](#conditional-element-manipulation-methods) - [`consume`](#consume) - [`classIf`](#classif) - [`classIfNot`](#classifnot) - [`styleIf`](#styleif) - [`styleIfNot`](#styleifnot) - [`stylesIf`](#stylesif) - [`stylesIfNot`](#stylesifnot) - [`hideIf`](#hideif) - [`hideIfNot`](#hideifnot) - [`disableIf`](#disableif) - [`disableIfNot`](#disableifnot) 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**: ```typescript const myElement = tag('div'); myElement.addClass('my-class', 'another-class'); // The element's class attribute is updated:
``` #### `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**: ```typescript const myElement = tag('div'); myElement.setClassName('custom-class'); // The element's class attribute is updated:
``` #### `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**: ```typescript const myElement = tag('div'); myElement.setStyle({ color: 'red', fontSize: '16px' }); // The element's style is updated:
``` #### `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**: ```typescript const myElement = tag('a'); myElement.setAttrs({ href: 'https://example.com', target: '_blank' }); // The element's attributes are updated: ``` #### `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**: ```typescript const myElement = tag('input'); myElement.addAttr('type', 'text'); // The element's attribute is updated: ``` #### `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**: ```typescript const myElement = tag('a'); myElement.rmAttr('href', 'target'); // The element's attributes are removed: ``` #### `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**: ```typescript 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** ```ts 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** ```ts 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** ```ts 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** ```ts 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** ```ts 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** ```ts 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](./Observables) 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](./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`](./Observables)): 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**: ```typescript 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`](./Observables)): 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**: ```typescript 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`](./Observables)): 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**: ```typescript 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`](./Observables)): 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**: ```typescript 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`](./Observables)): 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**: ```typescript 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`](./Observables)): 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`](./Tags) instance for method chaining. - **Example**: ```typescript 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`](./Observables)): 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`](./Tags) instance for method chaining. - **Example**: ```typescript 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**: - `consumable` ([`Observable`](./Observables)): A consumable object that represents a condition. - **Returns**: The [`CTag`](./Tags) instance for method chaining. - **Example** ```ts 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**: - `consumable` ([`Observable`](./Observables)): A consumable object that represents a condition. - **Returns**: The [`CTag`](./Tags) instance for method chaining. - **Example** ```ts 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`](./Observables) 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**: - `consumable` ([`Observable`](./Observables)): A consumable object that represents a condition. - **Returns**: The [`CTag`](./Tags) instance for method chaining. - **Example** ```ts 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`](./Observables) as a condition, which determines whether to disable the element each time the consumable changes. - **Parameters**: - `consumable` ([`Observable`](./Observables)): A consumable object that represents a condition. - **Returns**: The [`CTag`](./Tags) instance for method chaining. - **Example** ```ts const disabled = state(true); const myTag = tag('div'); myTag.disableIfNot(disable); // Disable element when the value is NOT false ```