summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@lukeshu.com>2018-01-05 16:55:40 -0500
committerLuke Shumaker <lukeshu@lukeshu.com>2018-01-05 16:55:40 -0500
commit9b0d35a213e77a81a78de9cd2dded0dab2e54839 (patch)
tree6dbbe4519ed3495e05a280c0e64e0f35950864ff
initial commit
-rw-r--r--vue-notes.md219
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