Cuttlefish Docs
  • English

    • Methods and Events

    {% from 'components/codeblock.macro.html' import codeblock %}

    Methods usually refer to invoking the methods of a component through the component element's ID to perform some actions. For example, spz-lightbox is not displayed on the page by default. When we want it to be displayed, we need to call its open method to open it.

    Events usually refer to the automatic triggering of events by a component after completing some operations. We can listen to these events to execute other logic after some actions are completed. For instance, after spz-lightbox is opened, we can listen to the @open event to call the component's methods or global methods to implement some logic.

    Key Takeaways First

    • @tap, @open, etc. map an event to an action/method via a small DSL.
    • The 3 most common patterns are: show/hide, toggle class, and scroll to an element.
    • If an action does not work, check: the target id exists, the method name is valid, and the expression is complete (for example, hello.hide).

    The 3 Most Common Examples

    1) Tap to hide/show

    <h3 id="hello">Hello Lessjs!</h3>
<button @tap="hello.hide">Hide</button>
<button @tap="hello.show">Show</button>

    2) Tap to toggle a class

    <div id="box" class="rounded-xl">Box</div>
<button @tap="box.toggleClass(class='m-bg-black')">Toggle background</button>

    3) Tap to scroll to an element

    <div id="target">Target</div>
<button @tap="target.scrollTo(position='top')">Scroll to target</button>

    Usage

    @eventName is usually used to listen to an element's event handlers. The supported events depend on the element.

    The syntax value is a simple domain-specific language, in the form of:

    @eventName="targetId.methodName[(arg1=value, arg2=value2, ...)]"

    For explanations of each part of the syntax, please refer to the table below.

    Syntax Description Required
    eventName Event name exposed by the element Yes
    targetId The DOM ID of the element, or the global SPZ object Yes
    methodName Applicable to elements with default methods. This is the method exposed by the target element (referred by targetId) that you want to execute when the event is triggered Yes
    arg=value Some methods can accept arguments. These arguments are defined by enclosing the key=value notation in parentheses. Accepted values include:
    • Quoted strings: "string value" or 'string value'
    • Boolean values: true or false
    • Numeric values: 11 or 1.1
    • References to event data in dot notation: event or event.someDataPropertyName
    		 No

    One Event Handling Multiple Methods

    Use a semicolon (;) to separate each method and execute multiple methods in sequence for the same event.

    @eventName="targetId.methodName(arg1=value);targetId2.methodName;"

    Globally Defined Events and Methods

    Lessjs defines a global tap event that you can listen to on any HTML element (including Lessjs elements or native HTML elements).

    Lessjs also defines global show, hide, scrollTo, and toggleClass methods that you can trigger on any HTML element.

    Element-specific Events

    *-All Elements

    EventDescription
    tapTriggered when the element is clicked/tapped

    Input Elements

    Event Description Element Data
    change Triggered when the element is changed and submitted. input
    event.min
    event.max
    event.value
    event.valueAsNumber
    input[type="radio"]
    input[type="checkbox"]
    		 event.checked
    select
    event.min
    event.max
    event.value
    input-debounced Triggered when the element's value changes. This event is similar to the standard change event, but it is only triggered 300ms after the input value stops changing. Elements that can trigger input events Same as change event data
    input-throttled Triggered when the element's value changes. This event is similar to the standard change event, but it triggers at most once every 100ms when the input value changes. Elements that can trigger input events Same as change event data
    input-smooth Triggered when the element's value changes. This event is similar to the standard input event. Elements that can trigger input events Same as input event data

    Element-specific Methods

    *(All Elements)

    MethodDescription
    showShow the target element (remove the hidden attribute from the target element)
    hideHide the target element (add the hidden attribute to the target element)
    toggleClass(class=string, force=boolean)Toggle the class of the target element. force is optional; if defined, it ensures that only the class is added and not removed when set to true, and the class is removed and not added when set to false.
    scrollTo(position=string, duration=integer, target-id=string)Scroll the element with a smooth animation. duration and target-id are optional. duration specifies the duration of the animation (in milliseconds). If not specified, a value no greater than 500 milliseconds relative to the scroll difference will be used. target-id is the ID of the DOM element used to specify the position to scroll to a specific element. If not specified, the default position of the element relative to the viewport after scrolling. position can be one of top, center, or bottom (default is top).
    toggleAttribute(key=string, value=string, force=boolean)
    focus

    Global Methods

    Global methods are mounted on SPZ and invoked using the SPZ.methodName form.

    MethodDescription
    copy(text=string)Copy content to the clipboard.
    scrollTo(id=string)Scroll to the specified element position.
    replaceUrlState([customName=string], reload=boolean)Replace or add URL parameters. All parameters except reload can be custom-named. reload is optional and specifies whether to refresh the page after the parameters are updated.
    navigateTo(url=string)Navigate to the specified page.
    postMessage(id=string, data=any)Send a message to the specified iframe.
    history(type='back', defaultUrl=string)Go back to the previous page. When no previous page exists, navigates to defaultUrl.

    AI Usage Notes (LLM Ready)

    • Section density: detected 7 level-2 headings.
    • Example density: detected 2 code blocks.
    • Read conclusions first: extract definitions, constraints, and boundary conditions.
    • Then verify with examples: rely on executable snippets rather than prose only.
    • Finally cross-check: open related component pages to avoid doc/runtime drift.