Add .once modifier description for v-on (#627)

* Add `.once` description modifier for v-on

Add `.once` description modifier for v-on and modifiers in render functions

* Update description of .once event modifier

* move event/key modifiers in render functions to that section

* improve styling for tables

Author: KingMario

src/v2/guide/events.md

@@ -164,6 +164,7 @@ To address this problem, Vue provides **event modifiers** for `v-on`. Recall tha
 - `.prevent`
 - `.capture`
 - `.self`
+- `.once`
 
 ``` html
 <!-- the click event's propagation will be stopped -->
@@ -186,6 +187,15 @@ To address this problem, Vue provides **event modifiers** for `v-on`. Recall tha
 <div v-on:click.self="doThat">...</div>
 ```
 
+> New in 2.1.4
+
+``` html
+<!-- the click event will be triggered at most once -->
+<a v-on:click.once="doThis"></a>
+```
+
+Unlike the other modifiers, which are exclusive to native DOM events, the `.once` modifier can also be used on [component events](components.html#Using-v-on-with-Custom-Events). If you haven't read about components yet, don't worry about this for now.
+
 ## Key Modifiers
 
 When listening for keyboard events, we often need to check for common key codes. Vue also allows adding key modifiers for `v-on` when listening for key events:

src/v2/guide/render-function.md

@@ -296,8 +296,8 @@ render: function (createElement) {
       value: self.value
     },
     on: {
-      input: function (e) {
-        self.value = e.target.value
+      input: function (event) {
+        self.value = event.target.value
       }
     }
   })
@@ -306,6 +306,57 @@ render: function (createElement) {
 
 This is the cost of going lower-level, but it also gives you much more control over the interaction details compared to `v-model`.
 
+### Event & Key Modifiers
+
+For the `.capture` and `.once` event modifiers, Vue offers prefixes that can be used with `on`:
+
+| Modifier(s) | Prefix |
+| ------ | ------ |
+| `.capture` | `!` |
+| `.once` | `~` |
+| `.capture.once` or<br>`.once.capture` | `~!` |
+
+For example:
+
+```javascript
+on: {
+  '!click': this.doThisInCapturingMode,
+  '~keyup': this.doThisOnce,
+  `~!mouseover`: this.doThisOnceInCapturingMode
+}
+```
+
+For all other event and key modifiers, no proprietary prefix is necessary, because you can simply use event methods in the handler:
+
+| Modifier(s) | Equivalent in Handler |
+| ------ | ------ |
+| `.stop` | `event.stopPropagation()` |
+| `.prevent` | `event.preventDefault()` |
+| `.self` | `if (event.target !== event.currentTarget) return` |
+| Keys:<br>`.enter`, `.13` | `if (event.keyCode !== 13) return` (change `13` to [another key code](keycode.info) for other key modifiers) |
+| Modifiers Keys:<br>`.ctrl`, `.alt`, `.shift`, `.meta` | `if (!event.ctrlKey) return` (change `ctrlKey` to `altKey`, `shiftKey`, or `metaKey`, respectively) |
+
+Here's an example with all of these modifiers used together:
+
+```javascript
+on: {
+  keyup: function (event) {
+    // Abort if the element emitting the event is not
+    // the element the event is bound to
+    if (event.target !== event.currentTarget) return
+    // Abort if the key that went up is not the enter
+    // key (13) and the shift key was not held down
+    // at the same time
+    if (!event.shiftKey || event.keyCode !== 13) return
+    // Stop event propagation
+    event.stopPropagation()
+    // Prevent the default keyup handler for this element
+    event.preventDefault()
+    // ...
+  }
+}
+```
+
 ### Slots
 
 You can access static slot contents as Arrays of VNodes from [`this.$slots`](http://vuejs.org/v2/api/#vm-slots):

themes/vue/source/css/page.styl

@@ -93,6 +93,29 @@
             margin-left 0
     iframe
         margin 1em 0
+    > table
+        border 1px solid $border
+        margin 1.2em auto
+        padding: 1em
+        border-collapse collapse
+        td, th
+            line-height 1.6em
+            padding .5em
+            border none
+            &:first-child
+                padding-left: 1.4em
+            &:last-child
+                padding-right: 1.4em
+        th
+            padding-top: .85em
+            padding-bottom .85em
+            text-align left
+        tbody
+            tr:nth-child(2n - 1)
+                background-color #fdfdfd
+            tr:last-child
+                td
+                    padding-bottom: 1.2em
     p.tip
         padding 12px 24px 12px 30px
         margin 2em 0