summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--Makefile12
-rw-r--r--vue-notes.md172
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/