diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | Makefile | 12 | ||||
| -rw-r--r-- | vue-notes.md | 172 |
3 files changed, 123 insertions, 62 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2d19fc7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.html diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..37326fa --- /dev/null +++ b/Makefile @@ -0,0 +1,12 @@ +PANDOC_FLAGS = --toc --number-sections +all: vue-notes.html + +%.html: %.md + pandoc --standalone -f markdown -t html $(PANDOC_FLAGS) < $< > $@ + +clean: + rm -f -- *.html + +.PHONY: all clean +.SECONDARY: +.DELETE_ON_ERROR: diff --git a/vue-notes.md b/vue-notes.md index 4c8fe41..9eadaf8 100644 --- a/vue-notes.md +++ b/vue-notes.md @@ -1,22 +1,25 @@ --- LocalWords: Vue DOM JS +title: "LukeShu's Guide to Vue" +author: + - Luke T. Shumaker +abstract: | + There are 4 primary pieces to the official Vue documentation: + + 1. Guide + 2. API + 3. Style Guide + 4. Examples + + The "Guide" is where concepts get introduced and explained; but fairly + little of the underlying machinery or details are explained; or it is + hard to find. The "API" is where the machinery and details are + explained, but the concepts of how that fits together is missing; it + links to the Guide. + + I think it's silly that those are 2 separate documents. --- -There are 4 primary pieces to the official Vue.js documentation: - - 1. Guide - 2. API - 3. Style Guide - 4. Examples - -The "Guide" is where concepts get introduced and explained; but fairly -little of the underlying machinery or details are explained; or it is -hard to find. The "API" is where the machinery and details are -explained, but the concepts of how that fits together is missing; it -links to the Guide. - -I think it's silly that those are 2 separate documents. - # Introduction import Vue from 'vue'; @@ -49,11 +52,10 @@ In addition to those objects: us to write markup such that Vue knows how to make it *reactive*. It's just plain HTML, but with (1) user-defined custom elements (via *components*), and (2) Vue-defined and user-defined custom - attributes (via *directives*; the built-in Vue directives all start - with `v-`). If you don't like writing raw HTML, that's fine, you - could write it via PUG or any other compile-to-HTML language, since - Vue templates are *just HTML*. From the JavaScript, they are just - plain strings. + attributes (via *directives*). If you don't like writing raw HTML, + that's fine, you could write it via PUG or any other + compile-to-HTML language, since Vue templates are *just HTML*. + From the JavaScript, they are just plain strings. - *Render functions*: Ultimately, *templates* compile to render functions. If your application design and toolchain @@ -76,20 +78,7 @@ gives us the tools to effectively write dope-ass parts of a user-interface, without requiring is to use Vue to do the entire interface (though you could). -# IDK what section this belongs in. - -Components don't work by literally registering custom elements with -the browser (though a W3C spec exists for allowing that, it isn't -(yet?) widely implemented). Instead, it's the *template language* -that knows about them, the custom element names are registered with -the template compiler, and the compiler then knows that when it -encounters a node with that element name, it needs to emit a render -function that instantiates that component. Ditto for directives. - -THE ABOVE IS FALSE. The render function calls -`something.createElement("element-name")`, the components are -registered with the `createElement`; the compiler doesn't need to know -this. +# Major topics ## Reactivity @@ -107,26 +96,6 @@ with a couple of silly magic functions to work around this limitation: ensures that the deletion triggers view updates, working around the limitation that Vue can't detect attribute deletions. -## Configuration - - - Global: `Vue.config` - * Development Settings - * `Vue.config.silent` Bool - * `Vue.config.devtools` Bool - * `Vue.config.warnHandler` Function - * `Vue.config.performance` Bool - * `Vue.config.productionTip` Bool - * For-reals Settings - * `Vue.config.optionMergeStrategies` Map<String,Function> - * `Vue.config.errorHandler` Function - * `Vue.config.ignoredElements` Array<String|RegExp> - * `Vue.config.keyCodes` Map<String,Number|Array<Number>> - - - > Unfortunately, that's custom `<element></element>`s; with Vue - > components, we can't use the `<element />` shorthand, or - > implied-closing (like with `<li>`). - ## Root Vue Instance var vm = new Vue({ ... }); @@ -163,8 +132,15 @@ We define a component like var MyComponent = Vue.extend({ ... }); +The things that go in the `...` are a superset of the things that we +can pass to `new Vue({ ... })`. + But that doesn't give it a name! We'll need to register our component -with an HTML tag name. We can do that globally with: +with an HTML tag name. + +### Global registration + +We register a component globally with: Vue.component('tag-name', MyComponent); @@ -186,30 +162,101 @@ we can use for convenience: > fact that component creation and registration are two distinct > operations. Lame shorthand! - If we want to be able to retrieve a component that we know is - registered, but the current code doesn't have an object for, we can - get it like: +If we want to be able to retrieve a component that we know is +registered, but the current code doesn't have an object for, we can +get it like: // returns the component previously registered to 'tag-name' var MyComponent = Vue.component('tag-name'); +### Scoped registration + +Of course, you may have had drilled in to your head "globals are +bad". We can also register components locally to a Vue instance. + +TODO. + ## Directives +Unlike components, which are a specific object type that had to be +created with `Vue.extend(...)`, directives are implemented as plain +map objects. + +Which is a little confusing, since it means that directive +registration looks like directive creation, and puts wrong notions in +your head. + +### Global registration + +Anyway, a directive can be registered globally: + + Vue.directive('directive-name', { ... }); + +The resulting attribute name always has a `v-` prefix; the above +results in needing to set `v-directive-name="foo"`. + +### Scoped registration + +TODO + ## Mixins -# other +## Templates + + > Unfortunately, that's custom `<element></element>`s; with Vue + > components, we can't use the `<element />` shorthand, or + > implied-closing (like with `<li>`). + +# Built-in ("core") directives + +TODO + +# Configuration + + - Global: `Vue.config` + * Development Settings + * `Vue.config.silent` Bool + * `Vue.config.devtools` Bool + * `Vue.config.warnHandler` Function + * `Vue.config.performance` Bool + * `Vue.config.productionTip` Bool + * For-reals Settings + * `Vue.config.optionMergeStrategies` Map<String,Function> + * `Vue.config.errorHandler` Function + * `Vue.config.ignoredElements` Array<String|RegExp> + * `Vue.config.keyCodes` Map<String,Number|Array<Number>> + +# Bonus: Single File Components (SFC's) + +TODO + +# misc + +Components don't work by literally registering custom elements with +the browser (though a W3C spec exists for allowing that, it isn't +(yet?) widely implemented). Instead, it's the *template language* +that knows about them, the custom element names are registered with +the template compiler, and the compiler then knows that when it +encounters a node with that element name, it needs to emit a render +function that instantiates that component. Ditto for directives. + +THE ABOVE IS FALSE. The render function calls +`something.createElement("element-name")`, the components are +registered with the `createElement`; the compiler doesn't need to know +this. + +I'm a big advocate of learning about things by reading the source. Be +aware that Vue is written in a JavaScript superset language called +[Flow][] that adds typechecking, similar to TypeScript. * Global API - `Vue.nextTick` - - `Vue.directive` - `Vue.filter` - `Vue.use` - `Vue.mixin` - `Vue.version` return the Vue version as a String - - Vue instances may have a "render" function, or a "template". I believe that templates compile to a render function (via `vue-template-compiler`), either at run-time, or at bundle-time if @@ -217,3 +264,4 @@ possible. [MVVM]: https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel [W3C Custom Elements]: https://www.w3.org/TR/custom-elements/#concepts +[Flow]: https://flow.org/ |