Getting started

The code sample

Getting started with vwRtx is super-simple, there's only one mandatory praameter and all the useful defaults are enabled. First lets prepare the setup with some Konva config.

Our html is very simple.

html

<!DOCTYPE html>
<html>

<head>
    <title>vwRtx demo</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>

  <div id="container" class='container'></div>

</body>

<script src="https://unpkg.com/konva@9/konva.js"></script> 

<script type="module" src="main.js"></script>

</html>

For the JavaScript make a file named main.js and paste this into it:


// Import vwRtx
import { vwRtx } from "<your path to>/vwRtx-min.js";

// Set up a Konva stage
stage = new Konva.Stage({
      container: 'container',
      width: containerEle.scrollWidth,
      height: containerEle.offsetHeight
  }),

  // and a layer to draw on
  layer = new Konva.Layer(),

  // and a transformer to do transformations
  transformer = new Konva.Transformer();

// Wire up the hierarchy - this is important!
stage.add(layer)
layer.add(transformer)

Next we will add a custom shape to the layer, then instantiate a new wRtx control. As part of the creation of the wRtx we tell it about the shape - remember the current dev requires Konva. The wRtx then draws whatever text output it needs onto the shape. Note - in Konva a custom shape is created via the new Konva.Shape() approach. All of Konva's shapes use this under the covers. Shape gets all of the built-in features for objectivity, hit testing, transforming, etc. Paste the remainder of the code into main.js.

// Make a Konva custom shape and add it to the layer
const hostShape = new Konva.Shape({
  position: { x: 50, y: 50 },
  size: { width: 300, height: 300 }
});

// !Important - must happen before rtx is created.
layer.add(hostShape); 

// Example of minimal rtx config
const rtx = new vwRtx({
  host: hostShape,
  text: "Wombats rule"
});

// The rtx is set up, so now we enable edit mode
rtx.send({ name: "editMode", value: true });

If you forget to add the shape to the layer and / or the layer to the stage before you call for the new instance then you'll see this in the console.

TIP

Critical error - host shape not linked to stage. Check shape added to layer and layer added to stage.

Automatic behaviours

By default and design, the vwRtx has some automatic behaviors to handle activation and transforming. Here's the list:

2-click activation

When it is in use, the vwRtx uses a 2-click activation UX. Why - because having it go into full edit mode every time you drag it somewhere is frustrating. So it uses a click counter.

Click #1 is counted as selection. When selected the vwRtx instance will put itself into the transformer so it can be sized and dragged, but it won't switch on the caret for typing yet. Dragging is only ever counted as one click, meaning that we can drag and drop repeatedly without flipping into edit mode, then when we finally get to where we need to be another click activates the instance for editing.
Click #2 is counted as activation - this is when we enable editing.

Activation handling

Having explained activation, it's worth mentioning deactivation. Just for a moment consider what a form would look like if every input was showing a blinking cursor at the same time. Bad UX. Therefore we must ensure that if the UI has multiple instances, only one vwRtx instance is activated at any time. And so we must handle deactivation when the user clicks another vwRtx instance, or another shape, or elsewhere on the stage. The vwRtx activation system handles this for you - just don't cancel the bubble of click events because vwRtx is listening for mouse events on the stage.

Transformer interaction

If you have a transformer on the page then when a vwRtx instance is activated it will set itself as the only node in the transformer. And when it is de-activated it will remove itself. When not activated, it can show an unobtrusive boundary rectangle to illustrate its surface space. The boundary rectangle can be set to appear on mouseover, or never. See focus rectangles for more information.

Integration with the transformer means the user can change the width and height of the shape, and scale the text. There are options to manage width and height automatically - see auto sizing for details.

Switching off automatic behaviours

Each of these defaults can be switched off - see the section on handlers. When switched off the developer has to take control. If so you'll need to know about enabling editing with editMode.

Next steps

Try the demo and head over to reference section to familiarise with the possibilities.

Getting started ​

The code sample ​

Automatic behaviours ​

2-click activation ​

Activation handling ​

Transformer interaction ​

Switching off automatic behaviours ​

Next steps ​