simplyview 2.0.2 → 2.1.0

package/docs/readme.md

@@ -1,33 +0,0 @@
-# Introduction
-
-SimplyView is a set of seperate components that allow you to rapidly build web 
-application user interfaces. They are designed to work with modern reactive 
-libraries, like that included in [SimplyEdit](https://simplyedit.io/).
-
-SimplyView seperates structure - HTML - from behaviour - javascript. There is 
-never a need to write HTML inside your javascript code. There is also never a 
-need to write javascript - or any other kind of code - inside your HTML. 
-This strict seperation allows for a much easier workflow between designers and developers.
-
-This seperation also makes it possible, even easy, to re-use and upgrade 
-existing web applications. There is no need to rewrite everthing from scratch. 
-SimplyView works well with jQuery. In rare cases you can use the simply.activate 
-component to make sure your legacy javascript can react to changes in the HTML 
-structure.
-
-SimplyView is not a framework, but a selection of components. There is a
-simply.app component which ties them all together, but you don't need it to
-use any of them.
-
-- [simply.app](simply.app.md)
-- [simply.route](simply.route.md)
-- [simply.command](simply.command.md)
-- [simply.action](simply.action.md)
-- [simply.collect](simply.collect.md)
-- [simply.activate](simply.activate.md)
-- [simply.include](simply.include.md)
-- [simply.api](simply.api.md)
-- [simply.viewmodel](simply.viewmodel.md)
-- [simply.path](simply.path.md)
-
-Here are [some examples](examples.md) that use parts of SimplyView.

package/docs/simply.action.md

@@ -1,42 +0,0 @@
-# simply.action
-
-Actions are a standardized way to define a kind of API for your user 
-interface. They are meant to be used together with routes and commands. 
-
-In this case the routes and commands are tightly bound to your URL 
-structure and your HTML structure respectively. 
-
-Actions should be decoupled from those. An action should just be a method 
-that updates the application state. The parameters for an action should 
-be the logical parameters for that update.
-
-```javascript
-var myApp = simply.app({
-  commands: {
-    addTodo: function(form, values) {
-      form.elements.todo.value = '';
-      this.app.actions.addTodo(values.todo);
-    }
-  },
-
-  actions: {
-    addTodo: function(todo) {
-      this.app.view.todos.push(todo);
-    }
-  }
-});
-```
-
-By structuring your application in this way, it is easy to add different 
-user interface modes which accomplish the same action. So you can create a 
-route as well as a command, that both trigger the same action. Or later you 
-can add keyboard shortcuts or gestures, without having to copy the logic of 
-your action.
-
-You can add actions later by just defining them in the actions object:
-
-```javascript
-myApp.actions.anotherAction = function(...arguments) {
-   ...
-};
-```

package/docs/simply.activate.md

@@ -1,27 +0,0 @@
-# simply.activate
-
-simply.activate is a component to automatically initialize HTML elements with 
-javascript as they appear in the DOM.
-
-```javascript
-simply.activate.addListener('autosize',function() {
-  $.autosize(this);
-});
-```
-
-```html
-<textarea data-simply-activate="autosize"></textarea>
-```
-
-The `addListener` method takes two arguments, a name and a callback method.
-The name is what you use in the html `data-simply-activate` attribute. The
-callback method is then called whenever the DOM element with that attribute
-is added to the dom. It is also called on load.
-
-The callback method has no arguments, instead it is called on the DOM element
-itself. `this` references the DOM element.
-
-Now you can use any 'legacy' component, in this case a jQuery textarea 
-resizer, that needs to initialize HTML elements. Simply.activate will
-trigger the initialization routine whenever the element is inserted into the
-dom, no matter how or when this happens.

package/docs/simply.api.md

@@ -1,188 +0,0 @@
-# simply.api
-
-Simply.api is a library that makes it easier to connect to online API's,
-like REST or JSON-RPC api's. It contains a simplified fetch() method as well
-as a proxy that allows you to call remote API's as if they were a local
-library. E.g.:
-
-```javascript
-const githubApi = simply.api.proxy({
-	baseURL: 'https://api.github.com',
-	headers: {
-		'Accept': 'application/vnd.github.v3+json',
-		'User-Agent': 'SimplyApi'
-	}
-});
-
-githubApi.users.poef()
-.then(user => {
-	console.log(user);
-});
-```
-
-The proxy() method returns an object that will create new proxy objects on
-the fly for any property you access on it, like the 'users' property above.
-When you call such a property as a function, the proxy object will convert
-the property path to a URL and fetch it.
-
-In this case the githubApi.users.poef() call is converted to a GET request
-with the url: 'https://api.github.com/users/poef'.
-
-You can also pass arguments to the method, by passing an object with key
-value pairs:
-
-```javascript
-githubApi.users.octocat.hovercard({
-	subject_type: 'repository',
-	subject_id: 1300192
-});
-```
-
-Which is converted in a fetch() request like this:
-
-```javascript
-GET https://api.github.com/users/octocat/hovercard?subject_type=repository&subject_id=1300192
-```
-
-If you want to use a different HTTP Verb, like 'POST', add that as the last entry like
-this:
-
-```javascript
-githubApi.user.keys.post({
-	key: "mykey"
-})
-.then(result => {
-	console.log(result);
-});
-```
-
-The default verb methods that simply.api understands are GET and POST. If
-you need more, declare them in the options object under the 'verbs' key.
-
-You can add any option recognized by the default fetch() api in the proxy
-options object, see [the init property
-here](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#parameters).
-In addition the proxy recognizes these options:
-
-- responseFormat
-- paramsFormat
-- verbs
-- user and password
-- handlers
-
-## responseFormat
-
-This declares the expected result format of the remote API. The valid
-options are:
-
-- text
-- formData
-- blob
-- arrayBuffer
-- unbuffered
-- json
-
-The default is 'json'. Unlike the standard fetch() api, simply.api.fetch
-(used by the proxy object) automatically parses and returns the result, as a
-Promise. If an error is returned - the response.ok flag is false - then it
-will throw an error object with the status, message and full response
-object.
-
-
-## paramsFormat
-
-Available formats are:
-- search
-- formData
-- json
-
-When the fetch method is GET, the format is forced to 'search'. 
-
-### search
-This option sets the parameter format for the remote API. When set to search, 
-the parameters are send as a url encoded parameters in the URL of the
-request.
-
-### formData
-Sets the parameter format to the default formdata encoding, add the
-parameters to the body of the request.
-
-### json
-Encodes the parameters as a json string and adds it to the body of the
-request.
-
-## verbs
-
-By default simply.api.proxy understands the GET and POST verbs. You can add
-more by setting this option, e.g:
-
-```javascript
-const githubApi = simply.api.proxy({
-	baseURL: 'https://api.github.com',
-	headers: {
-		'Accept': 'application/vnd.github.v3+json',
-		'User-Agent': 'SimplyApi'
-	},
-	verbs: [ 'get', 'post', 'put', 'delete' ]
-});
-```
-
-Now you can call the put() and delete() methods on the proxy as well:
-
-```javascript
-githubApi.user.following.octocat.delete();
-```
-
-Note: the verb names are automatically uppercased when sent. 
-
-## user and password
-
-If you set a user and password property in the options to simply.api.proxy,
-these will be converted to a basic authentication header and added to each
-request.
-
-## handlers
-
-Some API's require extra handling for requests or parsing of responses. You
-can override or extend the default handlers here. The available handlers are:
-
-- fetch
-- result
-- error
-
-A minimal definition for these handlers that maintains the default behaviour
-is:
-
-```javascript
-const githubApi = simply.api.proxy({
-	baseURL: 'https://api.github.com',
-        headers: {
-                'Accept': 'application/vnd.github.v3+json',
-                'User-Agent': 'SimplyApi'
-        },
-        verbs: [ 'get', 'post', 'put', 'delete' ],
-	handlers: {
-		fetch: function(verb, params, options) {
-			// prepare stuff here
-			return simply.api.fetch(verb, params, options)
-			.then(response => {
-				// do some more stuff here
-				return response;
-			});
-		},
-		result: function(result, options) {
-			// ditto
-			return simply.api.getResult(result, options)
-			.then(result => {
-				// more doing
-				return result;
-			});
-		},
-		error: function(error, options) {
-			// ...
-			simply.api.logError(error, options); // no return value here				
-		}
-	}
-});
-```
-

package/docs/simply.app.md

@@ -1,27 +0,0 @@
-# simply.app
-
-simply.app provides a simple starting point to build web applications:
-
-```javascript
-var myApp = simply.app({
-  routes: {
-    '/:section/': function(params) { ... }
-  },
-
-  commands: { ... },
-
-  actions: { ... },
-
-  container: document.getElementById('myApp'),
-
-  view: {
-    myVariable: 'foo'
-
-  }
-
-});
-```
-
-It combines [simply.route](simply.route.md),
-[simply.command](simply.command.md), [simply.action](simply.action.md) and
-[simply.view](simply.view.md) into a single application wrapper.

package/docs/simply.collect.md

@@ -1,64 +0,0 @@
-# simply.collect
-
-simply.collect allows you to create auto updating forms, just by adding a few 
-attributes to the form and its elements:
-
-```javascript
-function getAddress(elements) {
-  if (elements.zipcode.value && elements.housenr.value) {
-    zipcodeAPI
-    .getAddress(elements.zipcode.value,elements.country.value)
-    .then(function(address) {
-      elements.street.value = address.street;
-      elements.city.value = address.city;
-    }
-  }
-}
-
-simply.collect.addListener('address', getAddress);
-```
-
-```html
-<form>
-  <div data-simply-collect="address">
-    <label>
-      Zipcode: <input name="zipcode" data-simply-element="zipcode">
-    </label>
-    <label>
-      House NR: <input name="housenumber" data-simply-element="housenr">
-    </label>
-    <label>
-      Street: <input name="street" data-simply-element="street">
-    </label>
-    <label>
-      City: <input name="city" data-simply-element="city">
-    </label>
-  </div>
-</form>
-```
-
-The listener will get called whenever any of the elements changes. You can add 
-as many forms and as many container elements with data-simply-collect as you want.
-
-## simply.collect.addListener
-
-Add a collect listener. See the code above in the overview.
-
-## simply.collect.removeListener
-
-Removes a previously added listener. You must call removeListener with the 
-exact same name and function as used in addListener:
-
-```javascript
-simply.collect.removeListener('address', getAddress);
-```
-
-## simply.collect.update
-
-simply.collect only listens for the change event. So if you update an input 
-elements value through javascript, the collect listeners won't trigger, unless 
-you also trigger the change event. simply.collect.update does this for you:
-
-```javascript
-simply.collect.update(form.elements.zipcode, newZipcode);
-```

package/docs/simply.command.md

@@ -1,110 +0,0 @@
-# simply.command
-
-simply.command provides a way to tie behaviour (javascript code) to HTML
-elements:
-```html
-<button data-simply-command="doSomething">does something</button>
-```
-
-Commands can be set on any HTML element, but the behaviour differs based on 
-the element type:
-
-- BUTTON, A:
-  Command triggers on click. Value is copied from the data-simply-value attribute.
-- INPUT, TEXTAREA, SELECT:
-  Command triggers on change. Value is copied from the input value.
-- FORM:
-  Command triggers on submit. Value is the set of form values.
-- All others:
-  Command triggers on click. Value is copied from the data-simply-value 
-  attribute. Only runs if no other command handlers match.
-
-If a command is triggered, the default event handler is cancelled. So links 
-aren't followed, forms aren't submitted, etc.
-
-Initialize the commands like this:
-
-```javascript
-var commands = simply.command(myApp, {
-  myCommand: function(el, value) {
-    doSomething(value);
-  }
-});
-```
-
-For basic applications, commands are sufficient. But once your application 
-gets more complex it pays to limit the code in commands to just the parts that 
-tie into the HTML structure of your application. So searching the DOM, 
-getting attribute values, etc. 
-
-Once that is done, you should call an internal function that doesn't know 
-anything about the exact HTML structure. [simply.action](simply.action.md) 
-is purpose build to be used in that way. The Todo example shows how you can use this.
-
-## commands.action
-
-Each command function runs with the commands object returned from 
-simply.command as its scope. The action method is a useful shortcut to app.actions:
-
-```javascript
-var myApp = simply.app({
-  commands: {
-    addTodo: function(form, values) {
-      form.elements.todo.value = '';
-      this.action.call('addTodo', values.todo);
-    }
-  },
-
-  actions: {
-    addTodo: function(todo) {
-      this.app.view.todos.push(todo);
-    }
-  }
-});
-```
-
-The same thing can also be accomplished like this:
-```javascript
-this.app.actions.addTodo(values.todo);
-```
-
-## commands.call
-
-Allows you to call a command directly:
-```javascript
-myApp.commands.call('addTodo', el, value);
-```
-
-## commands.appendHandler
-
-Adds a command handler on top of the existing ones, so it gets matched first.
-
-```javascript
-myApp.commands.appendHandler({
-  match: 'input[type="radio"]',
-
-  check: function(el, evt) {
-    return (evt.type=='change');
-  },
-
-  get: function(el) {
-    return el.dataset.simplyValue || el.value;
-  }
-});
-```
-
-Handler properties:
-
-- match:
-  A CSS selector that checks if an element is handled by this command handler.
-- check:
-  A function that checks if the command should be run in this event.
-- get:
-  A function that returns the value for this command.
-
-## commands.prependHandler
-
-Adds a command handler, just like appendHandler. But it adds it first in the 
-list, so it will be matched last. This way you can add handlers with a more 
-generic CSS selector and append more specific handlers.
-

package/docs/simply.include.md

@@ -1,61 +0,0 @@
-# simply.include
-
-simply.include is a component that allows you to include external HTML - with 
-CSS and javascript - in the current HTML document. You will need to make sure 
-you don't overwrite global variables, the javascript and css get applied to 
-the whole document.
-
-This component makes it easy to create microfrontends for microservices, 
-without forcing you to use a specific framework or technology.
-
-Start by including the simply.include script, or simply.everything.js:
-
-```html
-<script src="js/simply.everything.js"></script>
-```
-
-Then add a simply-include link at the exact spot where you want to include a 
-widget or application or just a piece of HTML:
-
-```html
-<link rel="simply-include" href="/simplyview/widgets/my-widget/index.html"></link>
-```
-
-Your widget may contain any HTML, CSS and javascript you like, except it 
-shouldn't contain a HEAD. So a widget might look like this:
-
-```html
-<script src="/simplyview/js/simply.everything.js"></script>
-<link rel="simply-include-once" href="/simplyview/common/head.html">
-<link rel="simply-include-once" href="/simplyview/common/menu.html">
-<link rel="stylesheet" href="/simplyview/widgets/my-widget/style.css">
-<div class="my-widget">
-  ....
-</div>
-```
-
-The widget includes some common HTML, but only if it wasn't included before. 
-Assuming your pages all include the common head and menu, the widget will skip 
-this if the widget is included in a page. However you can also call the widget 
-as a normal page. In that case the common head and menu will be included and 
-the widget will decorate itself with the default styling and menu.
-
-simply.include will automatically detect `<link rel="simply-include(-once)">` 
-links in the DOM, no matter when and how they appear, and replace them with 
-the HTML fetched from the linked href.
-
-## Security
-
-simply.include is meant to include HTML with CSS and javascript into an 
-existing document. So you must take care that whatever you include is what you 
-meant to include. If you allow user input, you must make sure that it doesn't 
-have `<link rel="simply-include(-once)">` tags. Or that if they do, they won't 
-get executed.
-
-As a baseline, always clean user input of any offending tags, or even better: 
-clean it of all HTML. If that can't be done, make sure you use a whitelist of 
-acceptable tags. 
-
-Finally as a catchall, use Content-Security-Policy headers to only allow script 
-execution of whitelisted URL's. Don't allow inline scripts or you will still 
-be open to Cross Site Scripting attacks (XSS).

package/docs/simply.keyboard.md

@@ -1,60 +0,0 @@
-# simply.keyboard
-
-simply.keyboard is a simple library to add keyboard support to your application:
-
-```javascript
-let myKeys = {
-  default: {
-    ArrowDown: (e) => {
-      // handle arrow down
-    }
-  }
-}
-simply.keyboard(myApp, myKeys);
-```
-
-But generally you won't use this directly, but through simply.app:
-
-```javascript
-var myApp = simply.app({
-  keyboard: {
-    default: {
-      ArrowDown: (e) => {
-
-      }
-    }
-  }
-});
-```
-
-You can add multiple keyboard definitions:
-
-```javascript
-var counterApp = simply.app({
-  keyboard: {
-    default: {
-      ArrowDown: (e) => {
-
-      }
-    },
-    alternate: {
-      ArrowDown: (e) => {
-
-      }
-    }
-  }
-});
-```
-
-The default keyboard is 'default', but you can switch the keyboard by setting this attribute:
-
-```html
-<div data-simply-keyboard="alternate">
-  <input type="text" name="example">
-</div>
-```
-
-Whenever a keyboard `keydown` is fired, simply.keyboard will look for the closest parent with a `data-simply-keyboard` attribute. If found, it will use that keyboard definition. If not found, it will use `default`.
-
-The `keydown` event is only handled if the activeElement (the element that has focus) is inside the application container. See `simply.app` for more on that.
-

package/docs/simply.path.md

@@ -1,3 +0,0 @@
-# simply.path
-
-TODO