Skip to content

Latest commit

 

History

History
400 lines (338 loc) · 10.2 KB

tutorial.md

File metadata and controls

400 lines (338 loc) · 10.2 KB

← Home

Kioboard Tutorial

Creating Layouts

A layout Object is made of name, layers, actions, icons properties:

const customLayout = {
  name: "custom", // or i.e: "en_US"
  layers: {},
  actions: {},
  icons: {},
};

Layers

Let's create a custom layers-set.
Every layer Object must have a "default" layer name, so let's add one

The default layer

const customLayout = {
  name: "custom",
  layers: { // Layers set
    default: [], // layer
    // more layers here
  },
  actions: {},
  icons: {},
};

populate the array with strings representing the keyboard rows top to bottom.
Delimit your key-names with space:

default: [
  "a b c",
  "d e",
],

Tip: This (arguably less readable) array format is also valid:

default: [
  ["a", "b", "c"],
  ["d", "e"],
],

Congratulations, you made your first layout!
Now you can pass it to the constructor:

const customLayout = {
  name: "custom",
  layers: { 
    default: [
      "a b c",
      "d e",
    ],
  },
  actions: {},
  icons: {},
};

const kio = new Kioboard({
  layout: customLayout
});

Tap a <input data-kioboard> or <textarea data-kioboard></textarea> in order to open your Kioboard!

The shift layer

Let's learn about another special layer, the "shift" layer.
Create a "shift" property and set the uppercase key-names:

default: [
  "a b c",
  "d e",
],
shift: [   //+
  "A B C", //+
  "D E",   //+
],         //+

When the "default" layer opens, we need a way to switch to that special "shift" layer — and back. To do just that, add a special common action-key called "shift" (case-sensitive!) in both layers:

default: [
  "a b c",
  "shift d e", //+
],
shift: [
  "A B C",
  "shift D E", //+
],

Nice! Now you're able to switch back anf forth the "default" and "shift" layers, with caps-lock feature included out of the box!

Tip: Instead of using the action-key "shift" in the "shift" layer, you can also use the "default" action-key, but then you would lose the Caps-lock feature.

Besides the "shift" there are plenty of other common action-keys at your disposition:

Common actions

Action-key Action
default Switch to "default" layer
shift Toggle between "default" and "shift" layers, caps-lock
space Insert a space
enter Submit form, or add a newline in TextArea
backspace Delete selection or character on the left of the caret
delete Delete selection or character on the right of the caret
arrowLeft Move caret to the left
arrowRight Move caret to the right
tab Insert a tab
close Close, hide Kioboard
drag Drag handler to move the Kioboard

Tip: all those common actions are included by default into every layout. Can be overridden.

Let's add some of those common action-keys as well:

default: [
  "a b c backspace", //+
  "shift d e enter", //+
  "space",           //+
],
shift: [
  "A B C backspace", //+
  "shift D E enter", //+
  "space",           //+
],

Custom layers

Let's add a third layer to your set.
You can name any additional layers whatever you like. Let's name one for example: myExtras, and add some keys.

Also, create some keys like i.e: "extras" and add them to the "default" and "shift" layers rows as well. Those buttons will be used to open that "myExtras" layer

default: [
  "a b c backspace",
  "shift d e enter",
  "extras space",    //+
],
shift: [
  "A B C backspace",
  "shift D E enter",
  "extras space",    //+
],
myExtras: [          //+
  "! $ & backspace", //+
  "% # * enter",     //+
  "default space",   //+ Notice the common default action-key
],                   //+

But, how to open that myExtras layer?
Clicking the "extras" buttons the string "extras" is inserted literally into the input. Besides having learned how to output a word pretty easily, this is clearly not what we want. We need to assign to that key-name a custom action.

Actions

As we've seen, every key-name is inserted literally into the target input element as a string. To override such behavior we use actions.
Actions are callback functions which name must be equal (case-sensitive) to the key-name.

Creating actions

Let's create a key-action for that "extras" button. Define a function matching exactly the key-name "extras" in the actions Object.
Inside that function call the Kioboard's .show() method with the desired template name as argument:

const customLayout = {
  name: "custom",
  layers: { 
    default: [
      "a b c backspace",
      "shift d e enter",
      "extras space",
    ],
    shift: [
      "A B C backspace",
      "shift D E enter",
      "extras space",
    ],
    myExtras: [
      "! $ & backspace",
      "% # * enter",
      "default space",
    ],  
  },
  actions: {
    extras() {               //+ must match the key-name case-sensitive
      this.show("myExtras"); //+
    },                       //+
    // More actions here
  },
  icons: {},
};

const kio = new Kioboard({
  layout: customLayout
});

Tip: if you prefer Arrow functions, instead of this use your kio instance:

extras: () => kio.show("myExtras"),

Now, when you tap the "extras" button, your extras layer will show up.

Tip: The common action "space" is used to insert a space into the input element, because we internally use spaces " " as a delimiter, separator for the layer's rows key-names strings.

Icons

There's just a small detail to fix: that funky "extras" icon-text on the button key. Let's change its icon.

Inside the icons: {} Object, create a property name matching exactly your key-action name, and define the desired SVG, text, or emoji for your button:

// ...
icons: {
  extras: `⚙️`, //+ must match the key-name case-sensitive
  // More icons here
},

Tip:

// besides
extras: `⚙️`,
// multiple symbols:
extras: `#%!`,
// you can also use SVG:
extras: `<svg>...</svg>`,
// or Unicode code points:
extras: `\u2699`,

The final code:

const customLayout = {
  name: "custom",
  layers: { 
    default: [
      "a b c backspace",
      "shift d e enter",
      "extras space",
    ],
    shift: [
      "A B C backspace",
      "shift D E enter",
      "extras space",
    ],
    myExtras: [
      "! $ & backspace",
      "% # * enter",
      "default space",
    ],  
  },
  actions: {
    extras() {
      this.show("myExtras");
    },
  },
  icons: {
    extras: `⚙️`,
  },
};

const kio = new Kioboard({
  layout: customLayout
});

You should now have a good understanding on how to create custom Kioboard layouts.

Tip: if you need to add actions to numeric keys or keys starting with a number, use the bracket syntax:

["1"]() {
  console.log("One!"); // Do something here...
  // PS: "1" will not be inserted as value into the input   
}

Tip: Since assigning an action prevents the key's default behavior — return a desired string:

["1"]() {
  console.log("One!"); // Do something here...
  return "1"; // "1" value is inserted at caret position
}

Tip if you want to call a key-action instead, use the .emit() method

["1"]() {
  console.log("One!"); // Do something here...
  this.emit("default"); // Emit a common action (switch to default layer)
  // Just don't use: this.emit("1"); or you'll end up in an endless loop.
}

CSS styling

There's several ways to customize the style of your Kioboard.
The simplest one is to use the JS's .setStyle() method which allows you to modify the CSS Vars directly from your JavaScript code:

kio.setStyle({
  hue: 194,
  saturation: 94,
  lightness: 49,
  alpha: 1,
  radius: 0.3,
  gap: 0.3,
  size: 2, 
})

See more at: Kioboard API docs .setStyle()

For a more granular customization, use the specific kioboard CSS selectors:

.kioboard {
  /* Entire Kioboard styles */
}
.kioboard.is-visible {
  /* Kioboard is visible */
}
.kioboard[data-kioboard-layout="en"] {
  /* Specific layout-name styles */
}
.kioboard[data-kioboard-layer="default"] {
  /* Specific layer-name styles */
}
.kioboard[data-kioboard-theme="flat-dark"] {
  /* Specific theme-name styles */
}
.kioboard[data-kioboard-theme$="-dark"] {
  /* All dark themes styles */
}
.kioboard [data-kioboard-row] {
  /* All rows styles */
}
.kioboard [data-kioboard-row="0"] {
  /* Row with index 0 styles */
}
.kioboard [data-kioboard-key] {
  /* All keys */
}
.kioboard [data-kioboard-key="enter"] {
  /* enter key styles */
}
.kioboard [data-kioboard-key="a" i] {
  /* Keys "a" and "A" styles. (i = case insensitive) */
}
.kioboard .kioboard-icon {
  /* Button's SPAN icon styles */
}