---
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