1.2.

martywallace · Aug 24, 2016 · c054d25 · c054d25
1 parent 49d3189
commit c054d25
Show file tree

Hide file tree

Showing 6 changed files with 77 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,12 @@
 
 A simple virtual keyboard for Vue.js.
 
+## Install:
+
+This component is available through [Bower](https://bower.io/search/?q=vue-keyboard):
+
+    $ bower install --save vue-keyboard
+
 ## Usage:
 
 Simply add the `keyboard` component to your Vue application:
@@ -10,12 +16,53 @@ Simply add the `keyboard` component to your Vue application:
 <keyboard chars="abc123|xyz456|{space:space}"></keyboard>
 ```
 
-The `chars` property accepts a pipe `|` delimited string of characters to use as the keyboard buttons. You can include special function characters with the `{text:action}` syntax, where `text` is the text that will be rendered in the button and `action` is the action within the keyboard component to be called when that button is pressed. The actions are:
+The `chars` property accepts a pipe `|` delimited string of characters to use as the keyboard buttons. You can include special function characters with the `{text:action}` syntax, where `text` is the text that will be rendered in the button and `action` is the action within the keyboard component to be called when that button is pressed. The inbuilt actions are:
 
 * `backspace` - Remove one character from the end of the current value.
 * `space` - Insert one whitespace character.
 * `clear` - Clear the entire input value.
 
-> If the `action` does not match any of these inbuilt actions, an event will be dispatched by the keyboard component instead, using the action name. The keyboard component will be provided to the listener as the first argument.
+If the `action` does not match any of these inbuilt actions, an event will be dispatched by the keyboard component instead, using the action name as the event name. The keyboard component will be provided to the listener as the first argument.
+
+> Note: You can simply use `{action}` which will create a button with no text content. This is useful for things like `space` which you may just want to render as a wide empty button.
+
+## Interacting:
+
+In regards to styling and interacting with the component, there are several routes:
+
+* Buttons rendered with the `{text:action}` syntax will include a class name `action-x` where `x` is the name of the action e.g. `action-clear`.
+* General buttons will include a class name `char-x` where `x` is the text content e.g. `char-a`, `char-b`.
+* A `mutate` event is dispatched by the component whenever the `value` changes. The keyboard component will be provided to the listener as the first argument.
+* You can use `:value.sync="x"` to sync the keyboard value with a value in the parent Vue instance.
+
+## Example:
+
+Here is an example application containing a `keyboard` component:
+
+JavaScript:
+
+```
+var app = new Vue({
+	el: 'body',
+	data: {
+		input: ''
+	},
+	events: {
+		mutate: function(keyboard) {
+			// Limit to 16 chars.
+			keyboard.value = keyboard.value.slice(0, 16);
+		},
+		custom: function(keyboard) {
+			console.log('Custom button pressed. The current value is ' + keyboard.value);
+		}
+	}
+});
+```
+
+Markup:
+
+```
+<keyboard chars="qwertyuiop{backspace:backspace}|asdfghjkl|zxcvbnm|{space:space}{custom:custom}" :value.sync="input"></keyboard>
+```
 
-Buttons rendered with this syntax will include a class name `action-<x>` where `<x>` is the name of the action e.g. `action-clear`.
+This keeps the `input` value in the main application in sync with the value of the keyboard, limits that value to 16 characters and triggers the 'custom' function in the main application when the "custom" button in the keyboard is clicked.
diff --git a/bower.json b/bower.json
@@ -1,6 +1,6 @@
 {
   "name": "vue-keyboard",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/MartyWallace/vue-keyboard",
   "main": "dist/vue-keyboard.js",
   "license": "MIT",

diff --git a/demo/basic.html b/demo/basic.html
@@ -5,11 +5,16 @@
 		<title>Keyboard Demo</title>
 	</head>
 	<body>
-		<keyboard chars="qwertyuiop{clear:clear}|asdfghjkl{backspace}|zxcvbnm|{space:space}{test:test}" :value.sync="input"></keyboard>
+		<keyboard chars="qwertyuiop{backspace:backspace}|asdfghjkl|zxcvbnm|{space:space}{custom:custom}" :value.sync="input"></keyboard>
 		<p>${ input }</p>
 
 		<script src="https://cdnjs.cloudflare.com/ajax/libs/vue/1.0.26/vue.min.js"></script>
-		<script>Vue.config.delimiters = ['${', '}'];</script>
+		<script>
+			// Need to have this here so the Keyboard component will know what the delimiters should be. See:
+			// http://stackoverflow.com/questions/39112541/correct-way-to-reference-up-to-date-vue-delimiters-in-a-component
+			// https://github.com/vuejs/vue/issues/918
+			Vue.config.delimiters = ['${', '}'];
+		</script>
 		<script src="../dist/vue-keyboard.js"></script>
 
 		<script>
@@ -19,8 +24,12 @@
 					input: ''
 				},
 				events: {
-					test: function(keyboard) {
-						console.log(keyboard.value);
+					mutate: function(keyboard) {
+						// Limit to 16 chars.
+						keyboard.value = keyboard.value.slice(0, 16);
+					},
+					custom: function(keyboard) {
+						console.log('Custom button pressed. The current value is ' + keyboard.value);
 					}
 				}
 			});

diff --git a/dist/vue-keyboard.js b/dist/vue-keyboard.js
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "vue-keyboard",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"devDependencies": {
 		"gulp": "^3.9.1",
 		"gulp-uglify": "1.5.*",

diff --git a/src/vue-keyboard.js b/src/vue-keyboard.js
@@ -1,6 +1,8 @@
 (() => {
 	window.VueKeyboard = Vue.component('keyboard', {
 		template: (() => {
+			// For this to work correctly, the delimiters need to be changed before the component is
+			// registered on the page.
 			const a =  Vue.config.delimiters[0];
 			const b =  Vue.config.delimiters[1];
 
@@ -66,20 +68,25 @@
 				});
 			},
 
+			mutate(value) {
+				this.value = value;
+				this.$dispatch('mutate', this);
+			},
+
 			append(char) {
-				this.value += char;
+				this.mutate(this.value + char);
 			},
 
 			backspace() {
-				this.value = this.value.slice(0, this.value.length - 1);
+				this.mutate(this.value.slice(0, this.value.length - 1));
 			},
 
 			space() {
-				this.value += ' ';
+				this.append(' ');
 			},
 
 			clear() {
-				this.value = '';
+				this.mutate('');
 			}
 		}
 	});