DEV Community: Alexander Zaytsev

Velo: Server Side Rendering and Warmup Data APIs

Alexander Zaytsev — Fri, 22 Jul 2022 12:47:43 +0000

Learn how to optimize data receiving and reduce the Wix site load time

In Velo, we use the $w.onReady() method as a start point for interacting with the page. This method ensures that all the page elements have finished loading and we can interact with them. The life cycle of the Velo site includes two runs of the $w.onReady() method.

The first run of the $w.onReady() callback happens on the server-side when the server builds the HTML page. The server executes a Velo code and puts a result into HTML (if it's possible).

The second run goes on the client-side in the browser when a site page has loaded.

Velo API Reference: Rendering

When possible, the rendering process is split in two in order to improve performance. The first cycle in the process happens in the server-side code and the second cycle happens in the client-side code. If not possible on the server-side, all rendering happens client-side.

Let's playing with SSR for understanding how it works.

For example, we have the below code:

$w.onReady(function () {
  $w('#text1').text = 'Hello!';
});

Code will be executed on the server-side then a result will be added to the HTML page. And the page will send to the client-side with inserted data.

Rendering API

We can control the step of the render cycle with wixWindow.rendering.env API.

env property returns backend when rendering on the server-side and browser when rendering on the client-side.

Let's update the code to see it. It's a string with env value and timestamp.

import { rendering } from 'wix-window';

$w.onReady(function () {
  $w('#text1').text = `${rendering.env}: ${Date.now()}`;
});

Now, when we reload the page we can see that HTML content has backend value. When the page finished loading then we see the browser value, it's the second run of $w.onReady() on the client-side updates a value of text.

SSR & browser runtime

It looks easy.

Asynchronous operation

What about async operations?

If we want to add SSR with some async operation, we should wait for the promise to be fulfilled.

Let's have a look at an example. Creates a query for retrieving items from a database and prints them as a string.

import wixData from 'wix-data';

$w.onReady(function () {
  // Async request to database
  wixData.query('goods').find()
    .then((data) => {
      $w('#text1').text = JSON.stringify(data.items);
    });
});

As we can see, the SSR doesn't work with any async operations. When we reload the page, we see a default text that the Text element contains in the editor. And after a while, we see database items. It's the second run of the $w.onReady() callback on the client-side.

A site without server-side render with dynamic data

I'm using the throttling of the network in Chrome DevTools to reduce Internet speed. It may be helpful for debugging.

It happened because $w.onReady() doesn't wait for a promise fulfilled on the server-side. The server doesn't wait for a query result and sends the HTML page with default content.

To fix is very simple, we should wait for a promise result. The $w.onReady() supports the async callback functions. Let's update the code with async/await operators.

import wixData from 'wix-data';

$w.onReady(async function () {
  const data = await wixData.query('goods').find();

  $w('#text1').text = JSON.stringify(data.items);
});

Now, we can see the SSR starts to work. And the server has rendered the HTML page with the database items.

A site with server-side render for dynamic data

❗ don't forget to turn off the throttling of the network after testing 😉

Long async calls slow down site performance

We should be careful using $w.onReady() with an async callback. Long async tasks slow down the render the the page.

For example, we add a promise with a delay of 5 seconds into the callback.

$w.onReady(async function () {
  // a delay for 5 seconds
  await new Promise((r) => setTimeout(r, 5000));

  $w('#text1').text = Date.now().toString();
});

If we run this code, we will see that the server will wait for 5 seconds to complete. And after the HTML page has loaded on the client, we again wait for 5 seconds before seeing the result.

We wait twice for the promise to be fulfilled on the server and on the client.

Network inspector, time to load the HTML page from the server with a delay of 5 seconds

The Warmup Data API

Using the Warmup Data API, we are able to transfer data with a page code from the server and read this data on the client.

Velo API Reference:

The Warmup Data API is used to optimize data loading for sites that render both on the server and in the browser, allowing costly data fetching operations to be done only once.

Velo: The Warmup Data API example

import { warmupData, rendering } from 'wix-window';

// Set data on the server-side
if (rendering.env === 'backend') {
  warmupData.set('my-key', 'server data');
}

// Get data on the client-side
if (rendering.env === 'browser') {
  const data = warmupData.get('my-key');

  console.log(data); // -> "server data"
}

We can use the Warmup Data to reduce requests to a database. There we save the query response to warmupData on the server and read it on the client without additional database request.

Implement Warmup Data util function

We'll implement a feature that will enable server-side rendering and use the Warmup Data to prevent second data request on the client-side, it reduces a time of waiting.

Create a file for util function.

Add file to public section on the sidebar

public
└── warmupUtil.js

It is a wrapper function. It has two arguments:

First argument - key: It's a unique key corresponding to data for the Warmup Data
Second argument - func: It's an async function which result we want to use with the Warmup Data.

public/warmupUtil.js

import { warmupData, rendering } from 'wix-window';

export const warmupUtil = async (key, func) => {
  // On the server-side
  if (rendering.env === 'backend') {
    // Get data
    const data = await func();

    // Set the warmup data on the server-side
    warmupData.set(key, data);

    return data;
  }

  // On the client-side

  // Get the warmup data on the client-side
  const data = warmupData.get(key);

  // Checking a cached data exist
  if (data) {
    return data;
  }

  // If we don't have cache data from the server,
  // then we do a backup call on the client
  return func();
};

On the server, it waits for the async function result and sets it to the Warmup Data.

On the client, it uses data from the Warmup Data. If it has no data (some glitch on the server), it will call func on the client.

Parallel execution for a few async tasks

We should remember the $w.onReady() effect of page loading. If we want to use a few async functions in $w.onReady() callback then we should avoid using them in queue one by one.

For example, if each of these async functions executes at 100 milliseconds, the $w.onReady() will need to wait for 300 milliseconds for complete execution all of them.

// ❌ wrong approach!!
$w.onReady(async function () {
  const one = await warmupUtil('one-async-func', oneAsyncFunc); // ⏳ 100 ms
  const two = await warmupUtil('two-async-func', twoAsyncFunc); // ⏳ 100 ms
  const three = await warmupUtil('three-async-func', threeAsyncFunc); // ⏳ 100 ms

  // ⏳ wait one by one (100 ms * 3) = 300 ms

  $w('#text1').text = JSON.stringify({ one, two, three });
});

We are able to aggregate a bunch of promises with Promise.all(), execute them in parallel, and wait until all of them are ready.

// ✅ parallel asynchronous execution
$w.onReady(async function () {
  const [one, two, three] = await Promise.all([
    warmupUtil('one-async-func', oneAsyncFunc),
    warmupUtil('two-async-func', twoAsyncFunc),
    warmupUtil('three-async-func', threeAsyncFunc),
  ]);

  // ⏳ wait 100 ms. Parallel execution of all promises

  $w('#text1').text = JSON.stringify({ one, two, three });
});

Code Snippets

Here is a code snippet with JSDoc annotation. And an example of use.

public/warmupUtil.js

import { warmupData, rendering } from 'wix-window';

/**
 * @template T
 * @param {string} key
 * @param {() => Promise<T>} func
 * @returns {Promise<T>}
 */
export const warmupUtil = async (key, func) => {
  if (rendering.env === 'backend') {
    const data = await func();

    warmupData.set(key, data);

    return data;
  }

  const data = warmupData.get(key);

  if (data) {
    return data;
  }

  return func();
};

Page Code Tab

import { warmupUtil } from 'public/warmupUtil';

const getGoods = async () => {
   const { items } = await wixData.query('goods').find();

   return items;
};

$w.onReady(async function () {
  const items = await warmupUtil('goods-items', getGoods);

  $w('#text1').text = JSON.stringify(items);
});

Resources

Posts

Velo by Wix: Download your Velo code files to your computer

Alexander Zaytsev — Sun, 10 Jul 2022 15:48:35 +0000

Chrome extensions for downloading Velo code directly from the web editor to your computer.

Here is a Chrome Browser extension that provides a way to download Velo files from the web editor. You can install it in Chrome Web Store:

Add to Chrome

After installing, you should open the Wix editor and turn on dev mode. The extension asks you to pick a folder that the extension could use for saving files.

Download Velo code

This extension use File System Access API.

Posts

Velo by Wix: Type safety your code with JSDoc

Alexander Zaytsev — Tue, 01 Feb 2022 15:35:02 +0000

Built-in code checker, JSDoc annotations, and TypeScript compiler in Velo

From time to time, I can see in the big Velo projects how a part of the page code moves to the public files. In most, it's the projects with a few hundred/thousand lines of code per page. I understand why developers do it. Also, sometimes we want to reuse some part of the code for a few site pages. It looks like a good idea to move repeated code to a public file, and reuse it.

The main problem with this pattern is that doesn't work autocomplete and ID validation of $w() selectors in the public files. For example, we want to move a button handler to the public file. And init it on the page code.

public/initPage.js

// Filename: public/initPage.js

export const initPage = () => {
  const button = $w('#button1');

  button.onClick(() => { /* ... */ });
}

Page code

import { initPage } from 'public/initPage.js';

$w.onReady(() => {
  // Init page code from the public file.
  initPage();
});

In the public files, we can see a missing type inference. There don't work hints for $w() selector and don't work page elements autocomplete.

public/initPage.js

// Filename: public/initPage.js

export const initPage = () => {
  // 1. Autocomplete for ID suggestions doesn't work
  // 2. The checking of an element ID doesn't work.
  // 3. If the element with this ID doesn't exist on the page
  //    we don't have any error messages in editor.
  // 4. button mark as `any` type
  const button = $w('#button1');

  // 1. Autocomplete for button's method/properties doesn't work
  // 2. Type checking doesn't work.
  button.onClick(() => { /* ... */ });
}

For me, it's the main reason for don't use this pattern. The element could be removed or renamed at any time, and we don't have any editor hints, errors, or warnings to catch it. We could get a runtime error and, we should debug it with console or site logs.

However, this pattern is very commonly used. So, let's do it a little bit safer.

Why does it happen?

Firstly, the public files don't design for using the $w() selector. Velo code checker doesn't know how we plan to use a public file. Because we can import public files to any files on any pages, also we can import a public file to the backend files, other public files, or custom web-component code.

How Velo autocomplete works?

Velo uses a TypeScript compiler for autocomplete and code validations. Each page code file has built-in types of all elements on the current page.

Velo currently uses a TypeScript compiler for autocomplete and code validations

Page element types are generated automatically, when we add/remove any element on the page, Velo adds/removes a property for this target element in PageElementsMap type. The PageElementsMap type is unique on each page. So, each page code file has its own map of elements for autocompletion.

We to able to use this type with JSDoc types annotation. For example, we can use a TypeScript JSDoc syntax to describe types.

Page code

/**
 * @template {keyof PageElementsMap} T
 *
 * @param {T} selector
 * @param {$w.EventHandler} eventHandler
 * @returns {PageElementsMap[T]}
 */
const clickHandler = (selector, eventHandler) => {
  const element = $w(selector);

  element.onClick(eventHandler);

  return element;
}

// You can see this function has type checking for arguments and return value
clickHandler('#button1', (event) => {
  console.log(event);
});

If you try to use the code snippet above on your page code file, you can see that it has all type checking and autocomplete for arguments and a returned value. It's amazing, but we still can't use it on the public files, because the PageElementsMap type available only on the page code files.

How can we use a JSDoc on public files?

As we can see above, the autocomplete of the $w() selector doesn't work on the public files because TypeScript doesn't know about the context of the public file use. We can import public files anywhere in the code. So, we should describe the types.

Variable annotations with `@type` tag

Let's start with the simple use case. We can add variable annotations with the @type tag.

Syntax

JSDoc it's a block comment that starts with /** and ends with */. Inside block comment, we use a tag keyword that starts with @ symbol after tag keyword inside curly braces {} we put a type.

/** @tag {type} */

Velo provides autocomplete and syntax validation for JSDoc annotations. Just try to write the next snippet code in Velo editor without copy-pasting.

Velo: simple example of @type tag

/** @type {$w.Button} */
const button = $w('#button1');

$w.Button it's a built-in type. Velo has built-in types for all page elements. You can find it here: Wix element types

The main benefits of the element types, we can use it on the public files. In the simple use case, we add the type annotations to all elements that we start to use in a public file.

public/initPage.js

// Filename: public/initPage.js

export function initPage() {
  /** @type {$w.Button} */
  const button = $w('#button1');

  /** @type {$w.TextInput} */
  const input = $w('#input1');

  /** @type {$w.Text} */
  const text = $w('#text1');

  // your code goes here ...
}

Now, TypeScript understands what kind of elements we want to use. But TS still can check it.

Here, we just say to TypeScript - "Hey TS, I know it is the button. Just trust me and work with this element as the button".

We solve a problem with autocomplete suggestions for elements methods and properties in the public files. But we don't solve the issue when an element is removed or renamed from the page. TypeScript compiler can check $w() selectors only on the page code files.

Arguments annotation with `@param` tag

So, if we want to get autocomplete for elements and validation for $w() selectors, we should pass the elements explicitly from the page code to the public file as function arguments.

@param tag uses the same type syntax as @type, but adds a parameter name.

Syntax: JSDoc function arguments

/**
 * @param {type} name
 */

Let's update initPage() function for two arguments:

public/initPage.js

// Filename: public/initPage.js

/**
 * @param {$w.Button} button
 * @param {$w.TextInput} input
 */
export function initPage(button, input) {
  // your code goes here ...

  button.onClick(() => { /*...*/ });

  input.onInput(() => { /*...*/ });
}

Now, when we start using the initPage() function on the page code file, we can see autocomplete list.

Velo: autocomplete suggestion list

After typing the first $ symbol, we see a list of the suggestions. We can move on the list with ↑ ↓ keys and select one with ↵ Enter key.

Also, we can see the initPage() function has arguments types validation.

Velo: type error, a function expect an $w.TextInput type instead $w.Page

It's very cool! Now, I can sleep calmly 😀

Interface as a function param

Suppose, we want to use more than 2 arguments in the initPage() function. In this case, I guess better to use an object as an argument and put elements to object property. With object argument, we don't depend on the order of params. An object has more flexibility if we want to add or remove a new element.

Here we can use an interface syntax. It's similar to CSS syntax, where we describe a key name and types inside curly braces

@param { { name1: type; name2: type; … } } paramName

public/initPage.js

// Filename: public/initPage.js

/**
 * @param {{
 * button: $w.Button;
 * input: $w.TextInput;
 * text: $w.Text;
 * box: $w.Box;
 * }} elements
 */
export function initPage({
  button,
  input,
  text,
  box,
}) {
  // your code goes here ...

  button.onClick(() => { /*...*/ });

  input.onInput(() => { /*...*/ });
}

We have the autocomplete for the object keys and values. Very useful.

Velo: autocomplete and type validation

Resources

Posts

Velo by Wix: Repeated item event handlers v2.0

Alexander Zaytsev — Sat, 22 Jan 2022 13:43:28 +0000

It's my third post about event handling in repeated items. I show you a way that always has been in the documentation. I'm surprised why I hadn't noticed that before?

Yes, and again the event handling in Repeater. For me, the event handling of the repeated items was maybe the first confusion in my Velo projects.

I wrote two articles about it, you can find them in this blog:

Event handling of Repeater Item - here we considered how to handle events in the repeated items and we created a primitive helper function.
The utils for repeated item scope event handlers - here we created a more smart code snippet that can automatically receive parent Repeater item data from the event.

The main idea of these two articles, we shouldn't nest an event handler in any Repeater loop. It could be a reason when a callback function runs a few times by one event.

The Velo documentation is supposed to use the next way for handling events using event context.

Velo: Understanding the Scope of Selector Functions

$w.onReady(function () {
  $w('#myRepeatedImage').onClick((event) => {
    const $item = $w.at(event.context);

    $item('#myRepeatedText').text = 'Selected';
  });
});

In most cases, it's enough. But, if we need to receive an item data object or index of the fired item, the documentation provides something like this:

Velo API Reference: Retrieve Repeater item data when clicked

$w.onReady(function () {
  $w('#repeatedContainer').onClick((event) => {
    const $item = $w.at(event.context);
    const data = $w('#myRepeater').data;

    const clickedItemData = data.find((i) => i._id === event.context.itemId);
    const clickedItemIndex = data.findIndex((i) => i._id === event.context.itemId);

    console.log('itemData', clickedItemData);
    console.log('index', clickedItemIndex);
  });
});

It does not look bad. But we want to have a better 😊

Method forItems()

The Repeater has the forItems() method that allows us to run specific repeated items with the given list of IDs. I have never used it before. Previously, if I wanted to rerender some Repeater items then I just used the forEachItem() method. forItems() allows us to run the callback function for specific items, not all.

Velo API Reference:

Use the forItems() function to run a function on a specified list of repeated items. You can use the callback function to update or pull information from the specified repeated items

In the documentation, we can see the next example, which runs changes for two items by IDs.

Velo: Update data in some of a repeater's repeated items

$w('#myRepeater').forItems(['item1', 'item4'], ($item, itemData, index) => {
  $item('#repeatedImage').src = itemData.img;
  $item('#repeatedText').text = itemData.description;
});

Really, it's a very cool opportunity. It's always has been in the documentation. Why I hadn't noticed that before?

For example, we can solve our current issue with receiving item data.

Velo: Retrieve items scope selector function, item data, and index

$w.onReady(function () {
  $w('#repeatedButton').onClick((event) => {
    // Run callback for item ID from event context
    $w('#myRepeater').forItems([event.context.itemId], ($item, itemData, index) => {
      $item('#myRepeatedText').text = 'Selected';

      console.log('itemData', itemData);
      console.log('index', index);
    });
  });
});

Magic. For me, it's a very expressive code. And it's a good alternative to all known methods that I use before, like: repeater-scope npm package.

Resources

Posts

Velo by Wix: Query selector for child elements

Alexander Zaytsev — Sat, 08 Jan 2022 21:27:39 +0000

Get the child elements inside a parent node. In this post, we take a look deeper at $w() selector and try to filter children elements by the specific parent node

Let's suppose we have a few containers with checkboxes in each of them. We don't know how many checkboxes will be in each container at the final design.

Each container has a "select all" named checkbox that allows us to check on/off all checkboxes into a current target container.

We want to provide a good abstract solution for avoiding hard coding of elements' ID. And ensure scaling for any count of the elements in the future.

In general, we need to find a way to query select all child elements into a specific parent node. There are exist similar selectors in DOM and CSS.

More: Blog Post

Velo by Wix: Promise Queue

Alexander Zaytsev — Tue, 28 Sep 2021 10:32:13 +0000

In this post, we look at concurrent hide/show animation behavior in Velo APIs. When one of the animation effects can't start because a previous one isn't finished yet.

What is the issue?

Let's suppose that we have to animate an image by mouse event. For example, we want to create a hover effect that combines mouse in/out events.

Our realization will be very trivial. We have an image that has two event listeners on onMouse{In/Out} and a vector image that will be shown or hidden.

It's the next code snippet:

$w.onReady(() => {
  const fadeOptions = {
    duration: 300,
  };

  $w('#imageParrot')
    .onMouseIn(() => {
      $w('#vectorHat').show('fade', fadeOptions);
    })
    .onMouseOut(() => {
      $w('#vectorHat').hide('fade', fadeOptions);
    });
});

As you can see above, the animation has a duration of 300 ms. What happens if we move the cursor through in/out the image faster than 300 ms?

Yes, there is an issue. The next in the queue animation doesn't run if the previous one is going at the moment.

Why does it happen?

Let's visualize a timeline of the animation's execution. For example, we have three events, in -> out -> in. The first animation starts at 0 it will be finishing at 300 ms. The second animation starts at 200 ms, but it will be skip because this element is animating at this moment. The third one starts at 300 ms that will successfully run because the first one has finished, the second one skipped so the element can animate again.

Visualization of mouse events in a timeline

0 ms -- 100 ms -- 200 ms -- 300 ms -- 400 ms -- 500 ms -- 600 ms -- 700 ms
----------------------------------------------------------------------------

 .show() -------------------│ ✅ Done
                            │
              .hide() ......│ ❌ 🪲 Skipped
                            │
                            │ .show() -------------------│ ✅ Done

The Wix elements can't be animating with two concurrent (hide/show) animations on the same element at one time.

How can we fix it?

We have to wait for the animation's end before running a new one. For this, we create a queue. We push each animation request to this queue, where animations will be calling one by one.

Visualization of the Promise queue in a timeline

0 ms -- 100 ms -- 200 ms -- 300 ms -- 400 ms -- 500 ms -- 600 ms -- 700 ms
----------------------------------------------------------------------------

 .show() -------------------│ ✅ Done
                            │
              .hide() ......└--------------------│ ✅ Done
                                                 │
                             .show() ............└--------------------│ ✅ Done

Create a queue

Create a queue.js file in the public folder. In this file, we implement the queue logic.

First, we implement a mechanism for adding actions to the queue.

public/queue.js

export const createQueue = () => {
  // Action list
  const actions = [];

  return (action) => {
    // Adds action to the end of the list
    actions.push(action);
  };
};

Тurn your attention we don't run animation when mouse event fired. Instead, we wrap it to function and push it to the array.

Let's upgrade the code on the page to see how it works.

HOME Page (code)

import { createQueue } from 'public/queue.js';

$w.onReady(() => {
  // Initializing queue
  const queue = createQueue();

  const fadeOptions = {
    duration: 300,
  };

  $w('#imageParrot')
    .onMouseIn(() => {
      // Add actions to queue
      queue(() => $w('#vectorHat').show('fade', fadeOptions));
    })
    .onMouseOut(() => {
      // Add actions to queue
      queue(() => $w('#vectorHat').hide('fade', fadeOptions));
    });
});

Great, we have a list of actions. The next step, run the queue.

It will be an auxiliary function for the queue start.

public/queue.js

export const createQueue = () => {
  const actions = [];

  const runQueue = () => {
    // Check: are we have any actions in queue
    if (actions.length > 0) {
      // Removes the first action from the queue
      // and returns that removed action
      const action = actions.shift();
      // Waits the promise
      action().then(() => {
        // When the Promise resolves
        // then it runs the queue to the next action
        runQueue();
      });
    }
  };

  return (action) => {
    actions.push(action);
    // Runs the queue when adding a new action
    runQueue();
  };
};

The runQueue() is the recursive function it runs itself after the promise has been resolved. Also, we trigger runQueue() by adding a new action. We have to limit the trigger it should run only once at the queue start.

Further, we add the flag for closing the runQueue() if the queue is active.

public/queue.js

export const createQueue = () => {
  // Flag
  let isActive = false;

  const actions = [];

  const runQueue = () => {
    // Check: if the queue is running
    if (isActive) {
      // Stop this call
      return;
    }

    if (actions.length > 0) {
      const action = actions.shift();
      // Before: closes the queue
      isActive = true;

      action().then(() => {
        // After: opens the queue
        isActive = false;
        runQueue();
      });
    }
  };

  return (action) => {
    actions.push(action);
    runQueue();
  };
};

When a new action is adding to the list, we check the queue is active. If the queue is not active, we run it. If the queue is active, we do nothing.

Queue length

The last thing we need is control of the queue length. We can create a lot of animation actions that could lead to a blink effect.

Velo: blink effect by a long Promise queue

The algorithm is simple. If the queue has a max length then we remove the last action before adding a new one.

Visualization of removing queue actions in a timeline

0 ms -- 100 ms -- 200 ms -- 300 ms -- 400 ms -- 500 ms -- 600 ms -- 700 ms
----------------------------------------------------------------------------

 .show() -------------------│ ✅ Done
                            │
      .hide() ..............│ 🗑️ Removed
                            │
          .show() ..........│ 🗑️ Removed
                            │
                .hide() ....└--------------------│ ✅ Done

Let's set a max length by default as one. I think it covered 99% of use cases.

public/queue.js

// By default, the queue has one action
export const createQueue = (maxLength = 1) => {
  let isActive = false;

  const actions = [];

  const runQueue = () => {…};

  return (action) => {
    // Check: if the queue has max length
    if (actions.length >= maxLength) {
      // Removes the last action from the queue
      // before adds a new one
      actions.pop();
    }

    actions.push(action);
    runQueue();
  };
};

Check how it works on Live Demo

That's it! I hope it could be helpful to your projects. Thanks for reading.

Code Snippets

Here are the whole code snippet plus JSDoc types.

public/queue.js

/**
 * Create a promise queue
 *
 * @typedef {() => Promise<unknown>} Action
 *
 * @param {number} [maxLength] - max count actions in the queue
 * @returns {(action: Action) => void}
 */
export const createQueue = (maxLength = 1) => {
  /** @type {boolean} */
  let isActive = false;

  /** @type {Action[]} */
  const actions = [];

  const runQueue = () => {
    if (isActive) {
      return;
    }

    if (actions.length > 0) {
      const action = actions.shift();

      isActive = true;

      action().then(() => {
        isActive = false;
        runQueue();
      });
    }
  };

  return (action) => {
    if (actions.length >= maxLength) {
      actions.pop();
    }

    actions.push(action);
    runQueue();
  };
};

Example of using:

HOME Page (code)

import { createQueue } from 'public/queue.js';

$w.onReady(() => {
  const queue = createQueue();

  const fadeOptions = {
    duration: 300,
  };

  $w('#imageParrot')
    .onMouseIn(() => {
      queue(() => $w('#vectorHat').show('fade', fadeOptions));
    })
    .onMouseOut(() => {
      queue(() => $w('#vectorHat').hide('fade', fadeOptions));
    });
});

Resources

Posts

Short links to create a new Wix / Editor X site editor

Alexander Zaytsev — Mon, 27 Sep 2021 20:39:36 +0000

A set of short links for creating a new site on Wix, Velo, and Editor X. Just type the below links to your browser address bar.

wix.new - Creates a new Wix site editor from a blank template
velo.new - Creates a new Wix site editor with enabled Velo from a blank template
editorx.new - Creates a new Editor X site editor from blank template

Velo by Wix: The utils for repeated item scope event handlers

Alexander Zaytsev — Wed, 23 Jun 2021 09:42:40 +0000

npm library with utils for event handlers in Repeater

In the article "Event handling of Repeater Item", we considered how to handle events in the repeater items and why we shouldn't nest event handler inside the Repeater loop. There we created a code snippet that encapsulates the logic for receiving item selector and item data.

Copying and pasting the snippet of code isn't comfortable. Therefore I moved these little helpers to npm package repeater-scope. You can install this package using Package Manager

Velo Package Manager

There is available a method that can automatic find the parent Repeater by the fired event object.

Retrieve Repeater item data when clicked

import { useScope } from 'repeater-scope';

$w.onReady(() => {
  $w('#repeatedButton').onClick((event) => {
    const { $item, itemData, index, data } = useScope(event);

    $item('#repeatedText').text = itemData.title;
  });
});

Returns parameters

$item - A selector function with repeated item scope.
itemData - The object from the repeater's data array that corresponds to the repeated item being created.
index - The index of the itemData object in the data array.
data - A repeater's data array

How it works

The useScope(event) accepts Event object. With the Event object, we can get the target element. It's the element that the event was fired on. Also, we can get a type and parent element for any editor element.

// Gets the element that the event was fired on.
const targetElement = event.target;

// Gets the element's parent element.
const parentElement = event.target.parent;

// Gets the element's type.
const elementType = event.target.type;

In the first, let's find the parent repeater where the child item was handle. We will climb up the parent's elements until we will get the $w.Repeater element.

let parentElement = event.target.parent;

// Check the parent element type.
// If it isn't a Repeater take the next parent of the parent element.
while (parentElement.type !== '$w.Repeater') {
  parentElement = parentElement.parent;
}

We get the repeater data array directly from the repeater property.

const data = parentElement.data;

We have itemId in the event context object. With this ID we can found the current itemData and index where the event was fired from.

// ID of the repeater item where the event was fired from
const itemId = event.context.itemId;

// Use the Array methods to find the current itemData and index
const itemData = data.find((i) => i._id === itemId);
const index = data.findIndex((i) => i._id === itemId);

And the last, we create a selector function for the target element. We can use the event context with $w.at() to get a selector function.

// Gets a selector function
// which selects items from a specific repeater item
const $item = $w.at(event.context);

Any questions?

If you have any issues as bugs, feature requests, and more, please contact me GitHub Issue, or my personal Twitter.

I hope this small library will helpful in your projects too.

Resources

Posts

Velo by Wix: Imitating hover event on repeater container

Alexander Zaytsev — Sat, 16 Jan 2021 11:16:23 +0000

Velo API doesn't provide a hover event on the repeater container. In this post, we look at one way how we can imitate the hover event.

Motivation

We have a $w.Repeater component with items of users' cards. When we point with the mouse cursor over some item we want to change background color of this item to light blue color #CCE4F7 and when the cursor moves off of item we want to return the initial white color.

For this, we're going to use two other events that provide repeater API:

onMouseIn() runs when the mouse pointer is moved onto the element.
onMouseOut() runs when the mouse pointer is moved off of the element

Also, repeater items don't have property style.backgroundColor for changing the background color of an element. But we can use background.src property for changing the background image. So in this way, we're going to use a one-pixel image.

Here is one-pixel image

Event handlers

To start with, set handlers to onMouse{In/Out} events. We will use one function for two events by repeaters containers. We declare the handler function above and pass the function's name as an argument to container methods.

function imitateHover(event) {
  // our handler for containers
}

$w.onReady(function () {
  $w("#container1").onMouseIn(imitateHover); // set handler
  $w("#container1").onMouseOut(imitateHover);
});

Please pay attention, we don't nest any containers item into the repeater for adding handlers. Like here:

// In this way, each time when onItemReady starts
// would be set a new handler for containers.
$w("#repeater1").onItemReady( ($item, itemData, index) => {
  $item("#container1").onMouseIn(imitateHover);
  $item("#container1").onMouseOut(imitateHover);
});

We set globally our handler on all #container1 with $w() selector. And it works well!

Velo by Wix: Event handling of Repeater Item

Imitate hover

We use one function for two events, therefore we need to listen to which type of event is going. We're expecting two event types:

event.type === "mouseenter" when onMouseIn() is running.
event.type === "mouseleave" when onMouseOut() is running.

Let's see the code:

function imitateHover(event) {
  if (event.type === "mouseenter") {
    console.log("we have mouseenter if onMouseIn() is running");
  }

  if (event.type === "mouseleave") {
    console.log("we have mouseleave if onMouseOut() is running");
  }
}

$w.onReady(function () {
  $w("#container1").onMouseIn(imitateHover);
  $w("#container1").onMouseOut(imitateHover);
});

The object event always will be consistent with the current container item, which we point mouse cursor. And we can change the background.src property of the container by event.target.

// link to one pixel image
const HOVER_PNG = "https://static.wixstatic.com/media/e3b156_df544ca8daff4e66bc7714ebc7bf95f1~mv2.png";

function imitateHover(event) {
  // when the cursor over container then set image.
  if (event.type === "mouseenter") {
    event.target.background.src = HOVER_PNG;
  }
  if (event.type === "mouseleave") {
    // when the cursor is gone then remove the pixel image.
    event.target.background.src = "";
  }
}

$w.onReady(function () {
  $w("#container1").onMouseIn(imitateHover);
  $w("#container1").onMouseOut(imitateHover);
});

Great! It works: Live Demo

One-pixel image

We used the direct link to the one-pixel image. The size of this image is only 70 bytes. For example, the link of this image has 82 chars length, it's 82 bytes. The link takes up more memory than the image. ¯\_(ツ)_/¯

data:URL

Data URLs, it's a protocol that allows embedded small files inline in documents as a string. It means we can convert a one-pixel PNG image to string and pass it to background.src.

We can create needed images by 1x1 PNG generator #cce4f7ff.

// one-pixel image encoded to base64
const HOVER_PNG = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mM88+R7PQAIUwMo5M6pSAAAAABJRU5ErkJggg==';

function imitateHover(event) {
  if (event.type === "mouseenter") {
    event.target.background.src = HOVER_PNG;
  }
  if (event.type === "mouseleave") {
    event.target.background.src = "";
  }
}

$w.onReady(function () {
  $w("#container1").onMouseIn(imitateHover);
  $w("#container1").onMouseOut(imitateHover);
});

The data:URL image is a little longer than the direct link for this image. And other reason to use data:URL with the small image we don't send HTTP request for fetching this image.

Resources

Posts

A tiny event-based state manager Storeon for Velo

Alexander Zaytsev — Mon, 11 Jan 2021 08:42:53 +0000

A tiny event-based state manager Storeon for Velo

In this article, we explain how to manage a state in Velo with a light-weight and robust solution: Storeon, an event-based state manager.

Motivation

In the article, “State management in Corvid”, Shahar Talmi brings up a question about controlling app states in Velo. If you’re not familiar with Velo, it’s a development platform running on Wix that allows you to quickly and easily develop web applications.

Accurately controlling the state of any app is a really big problem. If you have many component dependencies or need to handle constant user interactions, you're going to suffer a bit when you want to eventually add a new feature or scale your application.

In this article, I share my solution — a very tiny library called Storeon (it’s only 180 bytes) that features an easy interface. So, I wrote a wrapper for integration with Velo. As a result, we have the state manager storeon-velo, and it’s less than 90 lines of code.

How it works

We will create a traditional study app with counters. I will use two counters to help provide a better demonstration.

At first, we need to install the library from Package Manager

and create one more file for store initialization in the public folder.

public
└── store.js

We will write our business logic in public/store.js.

Storeon's state is always an object; it canʼt be anything else. Itʼs a small limitation and not too important to us, but we have to remember it.

public/store.js

// The store should be created with createStoreon() function.
// It accepts a list of the modules.
import { createStoreon } from 'storeon-velo';

// Each module is just a function,
// which will accept a store and bind their event listeners.
const counterModule = (store) => {
  // @init will be fired in createStoreon.
  // The best moment to set an initial state.
  store.on('@init', () => ({ x: 0, y: 0 }));

  // Reducers returns only changed part of the state
  // You can dispatch any other events.
  // Just do not start event names with @.
  store.on('INCREMENT_X', (state) => ({ x: state.x + 1 }));
  store.on('DECREMENT_X', (state) => ({ x: state.x - 1 }));

  store.on('INCREMENT_Y', (state) => ({ y: state.y + 1 }));
  store.on('DECREMENT_Y', (state) => ({ y: state.y - 1 }));
}

// createStoreon() returns 4 methods to work with store
export const {
  getState, // <- will return current state.
  dispatch, // <- will emit an event with optional data.
  connect, // <- connect to state by property key.
  connectPage, // <- wrapper around $w.onReady()
} = createStoreon([counterModule]);

So, we created a store in the public folder and exported from there with four methods. In the second part, we will create our UI, and we will write logic to change the state.

Letʼs add two text elements to display our counter value and four buttons for event increments/decrements.

Of course, we have to import the store methods from the public file to the page's code.

import { dispatch, connect, connectPage } from 'public/store';

With connect("key", callback), we can subscribe to any store properties, and the callback function will be run when the page is loaded and each time when the listed property changes.

The connectPage(callback) is a wrapper around the $w.onReady(callback). With dispatch(event, [data]), we will emit events.

Page Code

import { getState, dispatch, connect, connectPage } from 'public/store';

// Connect to property "x".
// The callback function will be run when the page loads ($w.onReady())
// and each time when property "x" would change.
connect('x', (state) => {
  console.log('counter X is changed', state);

  $w('#textX').text = String(state.x);
});

// Connect to "y"
connect('y', (state) => {
  console.log('counter Y is changed', state);

  $w('#textY').text = String(state.y);
});

// Wrapper around $w.onReady()
// The callback function will be run once.
connectPage((state) => {
  // Here we also have an object with initial state
  console.log('onReady runs', state);

  // X counter events
  $w('#buttonIncX').onClick(() => {
    dispatch('INCREMENT_X');
  });

  $w('#buttonDecX').onClick(() => {
    dispatch('DECREMENT_X');
  });

  // Y counter events
  $w('#buttonIncY').onClick(() => {
    dispatch('INCREMENT_Y');
  });

  $w('#buttonDecY').onClick(() => {
    dispatch('DECREMENT_Y');
  });
});

Live Demo

Modules

The function, createStoreon(modules), accepts a list of modules. We can create different functions to split business logic into our app. Letʼs see a few examples:

Synchronization the App state with the wix-storage memory API:

// https://www.wix.com/velo/reference/wix-storage/memory
import { memory } from 'wix-storage';

export const memoryModule = (store) => {
  // @changed will be fired every when event listeners changed the state.
  // It receives object with state changes.
  store.on('@changed', (state) => {
    memory.setItem('key', JSON.stringify(state));
  });
}

Tracking an event to external analytics tools with wixWindow.trackEvent():

import wixWindow from 'wix-window';

export const trackEventModule = (store) => {
  // @dispatch will be fired on every `dispatch(event, [data])` call.
  // It receives an array with the event name and the event’s data.
  // Can be useful for debugging.
  store.on('@dispatch', (state, [event, data]) => {
    if (event === 'product/add') {
      // Sends a tracking event to external analytics tools.
      wixWindow.trackEvent('CustomEvent', { event, data });
    }
  });
}

Combining modules

const store = createStoreon([
  coutnerModule,
  memoryModule,
  trackEventModule,
]);

Conclusion

As you can see, we were able to quickly implement our state management solution with a minimal amount of code. Of course, due to data binding in Velo, you normally don’t have to worry about state management. However, in more complex applications, the issue can become more difficult, and state management will become more challenging to handle.

State management can be a tricky problem, but Storeon offers a simple, yet robust solution. In addition, Velo allows us to quickly implement this in our application, all while focusing on code and not having to spend time dealing with other issues.

Resources

Demo

Also

“State management in Corvid” by Shahar Talmi

Velo by Wix: Event handling of Repeater Item

Alexander Zaytsev — Sat, 09 Jan 2021 23:50:15 +0000

In this post, we consider why we shouldn't nest event handler inside the Repeater loop and how we can escape it.

At first, sight the adding event handling for repeated items looks easy.
You just handling events of repeated items inside Repeater loop methods there you have all needed data and scope with selector $item().

$w("#repeater").onItemReady(($item, itemData, index) => {
  // it look easy
  $item("#repeatedButton").onClick((event) => {
    // we have all we need
    console.log(
      $item("#repeatedContainer"),
      itemData,
      index,
    );
  });
});

What's wrong with this approach?

Sometimes the loop may set a few event handlers for the same item when you change order or filter or sort Repeater Items.
Each iteration of the loop may add a copy of the callback function to the handler when it starts again. You may don't pay attention to twice running code if you just hide or show some component by an event.
But if you work with APIs or wixData, then you can get a lot of problems.

My team and I consider this approach as an anti-pattern and we don't use it more.
For the "static" Repeaters which fill up once and don't change anymore during a user session, this approach can be used.

But if you would like to do dynamic fill up your Repeater or change its items, you shouldn't set a handler function inside the loop. Let's see another way.

Selector Scope

In the Velo, we have two types of selector functions.

The Global Scope Selectors it's $w(). We can use it anywhere in the frontend part of Wix site.
If we use $w() with Repeater Items, then it changes all items

// will change a text in all items
$w("#repeatedText").text = "new";

Repeated Item Scope

A selector with repeated item scope can be used to select a specific instance of a repeating element.

We can get repeated-item-scope selector in a few ways.

In the loop, selector as the first argument in callback function for .forEachItem(), .forItems(), and .onItemReady() methods.

Deprecated way, selector as the second argument in an event handler.
It still works but you don't have to use it

// 🙅‍♀️ DON'T USE IT 🙅‍♂️
$w("#repeatedButton").onClick((event, $item) => {
  // deprecated selector function (could be removed in the future)
  $item("#repeatedText").text = "new";
});

And with an event context. We can get the selector function with $w.at(context).

$w("#repeatedButton").onClick((event) => {
  // accepts an event context and
  // returns repeated items scope selector
  const $item = $w.at(event.context);

  $item("#repeatedText").text = "new";
});

Let's try to reproduce how we can use event.context instead of Repeater loop methods.

// we use global selector `$w()`, it provides handling all repeated items
$w("#repeatedButton").onClick((event) => {
  // get repeated item scope
  const $item = $w.at(event.context);

  // get the ID of the repeated item which fired an event
  const itemId = event.context.itemId;
  // get all repeater's data, it's stored as an array of objects
  const data = $w("#repeater").data;
  // use the array methods to find the current itemData and index
  const itemData = data.find((item) => item._id === itemId);
  const index = data.findIndex((item) => item._id === itemId);

  // we have all we need
  console.log(
    $item('#repeatedContainer'),
    itemData,
    index,
  );
});

In this way, we have only one callback for all elements with the specific ID.
Using context we can get the active item scope, its itemData, and index

Now, we see how to do more careful handling of events in the Repeater.
But this code not good enough for reuse.
Let's move the scope selector logic out event handler to the separate method.

Create hook

Our hook will have next steps:

#1 Implementation

// here will be all logic
const createScope = (getData) => (event) => {
  // TODO: Implement hook
}

#2 initialize

// sets callback function, it has to return the repeater data
const useScope = createScope(() => {
  return $w("#repeater").data;
});

#3 using

// using with repeated items
$w("#repeatedButton").onClick((event) => {
  // returns all we need
  const { $item, itemData, index } = useScope(event);
});

We create a hook with createScope(getData) it will be work with a specific Repeater. The argument getData it's a callback, it has to return the Repeater data.

The createScope will return a new function useScope(event) that has a connection with the specific Repeater data. The useScope(event) accepts an event object and return the data of the current scope.

For the realization of createScope(getData) function, we will create a public file public/util.js

We can get Repeater data with getData(), and we have the event context. All we need just return Scope selector and item data as an object. We will use getter syntax for returning itemData, index, and data.

public/util.js

export const createScope = (getData) => (event) => {
  const itemId = event.context.itemId;
  const find = (i) => i._id === itemId;

  return {
    $item: $w.at(event.context),

    get itemData() {
      return getData().find(find);
    },

    get index() {
      return getData().findIndex(find);
    },

    get data() {
      return getData();
    },
  };
};

Code Snippet on GitHub

If you don't work with getter/setter for property accessors you can look here how it works.

Let's see how we can use the hook on the page with static or dynamic event handlers.

HOME Page Code

import { createScope } from "public/util";

const useScope = createScope(() => {
  return $w("#repeater").data;
});

$w.onReady(() => {
  // sets static data
  $w("#repeater").onItemReady(($item, itemData) => {
    $item('#repeatedText').text = itemData.title;
  });

  // use a dynamic event handler
  $w("#repeatedButton").onClick((event) => {
    const { $item, itemData, index, data } = useScope(event);
  });
});

// or a static event handler
export function repeatedButton_click(event) {
  const { $item, itemData, index, data } = useScope(event);
}

Now, we can reuse the selector hook with all Repeater in all site pages.

JSDoc

Update (12.05.2020)

The Velo code editor supports JSDocs, it's a markup language that is used inside JS block comments. JSDocs provides static type checking, adds the autocomplete, and making good documentation of your code. I recommend using JSDocs.

Code snippet with JSDocs:

/**
 * Create Repeated Item Scope
 * https://github.com/shoonia/repeater-scope
 *
 * @typedef {{
 *  _id: string;
 *  [key: string]: any;
 * }} ItemData;
 *
 * @typedef {{
 *   $item: $w.$w;
 *   itemData: ItemData;
 *   index: number;
 *   data: ItemData[];
 * }} ScopeData;
 *
 * @param {() => ItemData[]} getData
 * @returns {(event: $w.Event) => ScopeData}
 */
export const createScope = (getData) => (event) => {
  const itemId = event.context.itemId;
  const find = (i) => i._id === itemId;

  return {
    // @ts-ignore
    $item: $w.at(event.context),

    get itemData() {
      return getData().find(find);
    },

    get index() {
      return getData().findIndex(find);
    },

    get data() {
      return getData();
    },
  };
};

Don't remove JSDocs in your code! In the building process, all comments will be removed automatically from the production bundle.

Also

Velo by Wix: The utils for repeated item scope event handlers

DEV Community: Alexander Zaytsev

Velo: Server Side Rendering and Warmup Data APIs

Rendering API

Asynchronous operation

Long async calls slow down site performance

The Warmup Data API

Implement Warmup Data util function

Parallel execution for a few async tasks

Code Snippets

Resources

Posts

Velo by Wix: Download your Velo code files to your computer

Posts

Velo by Wix: Type safety your code with JSDoc

Why does it happen?

How Velo autocomplete works?

How can we use a JSDoc on public files?

Variable annotations with @type tag

Syntax

Arguments annotation with @param tag

Interface as a function param

Resources

Posts

Velo by Wix: Repeated item event handlers v2.0

Method forItems()

Resources

Posts

Velo by Wix: Query selector for child elements

Velo by Wix: Promise Queue

What is the issue?

Why does it happen?

How can we fix it?

Create a queue

Queue length

Code Snippets

Resources

Posts

Short links to create a new Wix / Editor X site editor

Velo by Wix: The utils for repeated item scope event handlers

Returns parameters

How it works

Any questions?

Resources

Posts

Velo by Wix: Imitating hover event on repeater container

Motivation

Event handlers

Imitate hover

One-pixel image

data:URL

Resources

Posts

A tiny event-based state manager Storeon for Velo

A tiny event-based state manager Storeon for Velo

Motivation

How it works

Modules

Conclusion

Resources

Demo

Also

Velo by Wix: Event handling of Repeater Item

Selector Scope

Repeated Item Scope

Create hook

JSDoc

Also

Resources

Variable annotations with `@type` tag

Arguments annotation with `@param` tag