diff options
| -rw-r--r-- | vue-notes.md | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/vue-notes.md b/vue-notes.md new file mode 100644 index 0000000..4c8fe41 --- /dev/null +++ b/vue-notes.md @@ -0,0 +1,219 @@ +--- +LocalWords: Vue DOM JS +--- + +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'; + +Vue (pronounced like "view") is a *progressive* framework for building +user interfaces; progressive means that you can use it for as much, or +as little, of the user interface as you like. + +There are a few major object types in Vue that are helpful to +understanding Vue at a high-level: + + - *Vue Instances*: a Vue instance manages a part of the DOM. + + - *Components*: think of components as "custom HTML `<element>`s". + An instance of a component is a type of Vue instance. That is, + your custom `<element>` obviously "owns" and manages the underlying + real HTML elements in the DOM that are used to implement it. + + - *Directives*: think of directives as "custom HTML `attr="ibutes"`". + +In addition to those objects: + + - *Reactive*: Each *component* has a "data" object associated with + it; this is usually just a plain map Object. If you (in the + ordinary, plain, JS ways!) modify that object, the component will + automatically *react* to that change, and update the DOM + accordingly. + + - *Templates*: Vue has its own HTML templating language, that allows + 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. + + - *Render functions*: Ultimately, *templates* compile to render + functions. If your application design and toolchain + (WebPack/Babel/what-have-you) allow it, this can be done + ahead-of-time as a server-side optimization step before being + served to the client, or it can happen at runtime by calling + `Vue.compile("template string")`, which returns a function. + Anyway, having render functions exposed to programmers means that, + if you want, you can write the render functions yourself, instead + of writing templates. Programmers coming from React will note that + JSX is useful for writing render functions. + +Tying it together: A *component* is mostly just a *Vue instance* that +manages its part of the DOM by calling a *render function* (compiled +from a *template*) in accordance with an object that the component is +assigned to be *reactive* to. + +The premise of Vue is that this small set of objects and concepts +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. + +## Reactivity + +Because of limitations in JavaScript, when implementing the magical +reactivity that Vue provides, Vue can detect attribute *modification*, +but not adding or removing attributes. Lame! So, Vue provides us +with a couple of silly magic functions to work around this limitation: + + - `Vue.set(object, key, value);` is like `object[key] = value;`, except + that if the `key` attribute doesn't exist yet, it is created as a + reactive attribute, working around the limitation that Vue can't + detect attribute additions. + + - `Vue.delete(object, key);` is like `delete object[key];`, but + 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({ ... }); + +> As a convention, it is common to use the variable name `vm` for the +> root Vue instance; `vm` stands for ViewModel; a reference to the +> [Model+View+ViewModel (MVVM)][MVVM] application architecture; but +> don't worry about MVVM, since from your point of view of, your Vue +> program won't be following MVVM; just accept it as an arbitrary +> convention. + +To use it, you will need to *mount* the instance to the part of the +DOM that it will manage. + +You can do this after-the-fact like: + + vm.$mount("css-selector"); // the first matching element will be used + // or + vm.$mount(HTMLElement); + +Or, you can do it at instance creation by specifying `el`: + + var vm = new Vue({ + el: CSS-selector-or-HTMLElement, + }); + +The mount-point element will be *replaced* with the Vue-generated DOM, +so it is therefore not recommended to mount the root instance to +`<html>` or `<body>`. + +## Components + +We define a component like + + var MyComponent = Vue.extend({ ... }); + +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: + + Vue.component('tag-name', MyComponent); + + > Vue does not enforce the rules on component names that are there + > for [W3C Custom Element][W3C Custom Elements] tag names + > (all-lowercase, must contain a hyphen), but it is conventional to + > follow them anyway, and is considered good practice. + +Since it's so common to immediately register components, and not +otherwise use them directly in the JS, we have a bit of shorthand that +we can use for convenience: + + Vue.component('tag-name', Vue.extend({ ... })); + // can be written as + Vue.component('tag-name', { ... }); + // and it will automatically call Vue.extend for us + + > Wait, that didn't actually save us much typing, and obscured the + > 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: + + // returns the component previously registered to 'tag-name' + var MyComponent = Vue.component('tag-name'); + +## Directives + +## Mixins + +# other + + * 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 +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 |