chiasm-component - npm Package Compare versions

Comparing version 0.2.0 to 0.2.1

chiasm-component.js

 (function(f){if(typeof exports==="object"&&typeof module!=="undefined"){module.exports=f()}else if(typeof define==="function"&&define.amd){define([],f)}else{var g;if(typeof window!=="undefined"){g=window}else if(typeof global!=="undefined"){g=global}else if(typeof self!=="undefined"){g=self}else{g=this}g.ChiasmComponent = f()}})(function(){var define,module,exports;return (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){
 (function (global){
 // chiasm-component.js
-// v0.2.0
+// v0.2.1
 // github.com/chiasm-project/chiasm-component
@@ -24,3 +24,3 @@ //
   // with special semantics around the notion of a "public property".
-  var model = Model();
+  var my = new Model();
 
@@ -35,18 +35,35 @@ // `addPublicProperty()`
   // a public property , then an error will be reported.
-  model.addPublicProperty = function (property, defaultValue){
-    if(!model.publicProperties){
-      model.publicProperties = [];
+  my.addPublicProperty = function (property, defaultValue){
+    if(!my.publicProperties){
+      my.publicProperties = [];
     }
-    model.publicProperties.push(property);
-    model[property] = defaultValue;
+    my.publicProperties.push(property);
+    my[property] = defaultValue;
   };
 
+  // Adds all public properties in the given object.
+  my.addPublicProperties = function (publicProperties){
+    Object.keys(publicProperties).forEach(function (property){
+      my.addPublicProperty(property, publicProperties[property]);
+    });
+  };
+
+  // Initialize an SVG container element for chaism-layout to use.
+  // This is for supporting multiple components in a single SVG element.
+  my.initSVG = function (){
+    return my.el = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  }
+  
+  // Initialize a DIV container element for chaism-layout to use.
+  my.initDIV = function (){
+    return my.el = document.createElement("div");
+  }
+
   // Add the default values passed into the constructor
   // as public properties.
-  publicProperties = publicProperties || {};
-  Object.keys(publicProperties).forEach(function (property){
-    model.addPublicProperty(property, publicProperties[property]);
-  });
+  if(publicProperties){
+    my.addPublicProperties(publicProperties);
+  }
 
-  return model;
+  return my;
 }
@@ -53,0 +70,0 @@

index.js

@@ -22,3 +22,3 @@ // chiasm-component.js
   // with special semantics around the notion of a "public property".
-  var model = Model();
+  var my = new Model();
 
@@ -33,20 +33,37 @@ // `addPublicProperty()`
   // a public property , then an error will be reported.
-  model.addPublicProperty = function (property, defaultValue){
-    if(!model.publicProperties){
-      model.publicProperties = [];
+  my.addPublicProperty = function (property, defaultValue){
+    if(!my.publicProperties){
+      my.publicProperties = [];
     }
-    model.publicProperties.push(property);
-    model[property] = defaultValue;
+    my.publicProperties.push(property);
+    my[property] = defaultValue;
   };
 
+  // Adds all public properties in the given object.
+  my.addPublicProperties = function (publicProperties){
+    Object.keys(publicProperties).forEach(function (property){
+      my.addPublicProperty(property, publicProperties[property]);
+    });
+  };
+
+  // Initialize an SVG container element for chaism-layout to use.
+  // This is for supporting multiple components in a single SVG element.
+  my.initSVG = function (){
+    return my.el = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  }
+  
+  // Initialize a DIV container element for chaism-layout to use.
+  my.initDIV = function (){
+    return my.el = document.createElement("div");
+  }
+
   // Add the default values passed into the constructor
   // as public properties.
-  publicProperties = publicProperties || {};
-  Object.keys(publicProperties).forEach(function (property){
-    model.addPublicProperty(property, publicProperties[property]);
-  });
+  if(publicProperties){
+    my.addPublicProperties(publicProperties);
+  }
 
-  return model;
+  return my;
 }
 
 module.exports = ChiasmComponent;

package.json

 {
   "name": "chiasm-component",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A common base for Chiasm plugins.",
@@ -8,3 +8,4 @@ "main": "index.js",
     "pretest": "browserify -o chiasm-component.js -s ChiasmComponent index.js",
-    "test": "mocha"
+    "test": "mocha",
+    "prepublish": "npm test"
   },
@@ -11,0 +12,0 @@ "repository": {

README.md

 # chiasm-component
 
-A common base for Chiasm plugins.
+[![Build
+Status](https://travis-ci.org/chiasm-project/chiasm-component.svg?branch=master)](https://travis-ci.org/chiasm-project/chiasm-component)
+
+A common base for [Chiasm](https://github.com/chiasm-project/chiasm) plugins.
+
+This module is a thin wrapper around [Model.js](https://github.com/curran/model) that adds an API for defining
+public properties.  In Chiasm, only public properties are allowed to be
+configured via `chiasm.setConfig(config)`. If a user attempts to configure a
+property value not added as a public property, an error will be reported.
+
+Example use:
+
+```javascript
+var myComponent = ChiasmComponent ({ x: "foo", y: "bar" });
+```
+
+In the above snippet, `myComponent` will be a model.js Model.
+
+The constructor argument `publicProperties` (optional) is an object where:
+ 
+  * Keys are property names
+
+  * Values are default values for these properties
+  
+This argument specifies a set of public properties and their default values.
+
+```javascript
+myComponent.addPublicProperty("z", "baz");
+```
+
+This function adds a public property to a model (e.g. "z") and specifies its default value (e.g. "baz").  This makes the property available for dynamic configuration within Chiasm.
+
+## Background
+
+Originally, Chaism plugins were simply Models, so a plugin could be defined like this:
+
+```javascript
+function MyPlugin(){
+  return Model();
+};
+```
+
+The problem with this setup is that changes can only be propagated from the Chiasm configuration to components, but not the other way around, because Chiasm has no way to know which properties it should listen for changes on. In cases where user interaction causes changes in components, it is desirable to have those changes propagate back into the configuration. This is so the visualization state resulting from user interactions can be serialized.
+
+To enable change propagation from components to the Chiasm configuration, set a special property `publicProperties` was introduced. This is an array of property names. Each of these properties must have a default value defined on the model at the time it is returned from the component constructor. In cases where the property is optional and is initially not specified, use `Model.None` (which is conceptually similar to [Scala's Option type](http://alvinalexander.com/scala/using-scala-option-some-none-idiom-function-java-null)).
+
+```javascript
+return function MyPlugin(){
+  return Model({
+    publicProperties: ["message"],
+    message: "Hello"
+  });
+};
+```
+
+ChiasmComponent provides syntactic sugar for the above convention. The above code is equivalent to:
+
+```javascript
+return function MyPlugin(){
+  return ChiasmComponent({
+    message: "Hello"
+  });
+};
+```
+
+## Why "public properties"?
+
+It became clear in early Chiasm prototypes that if a property is not declared as a public property, then configured by the Chiasm configuration, then that configured property is *removed* from the configuration, the system results in an unpredictable state. This is because when a property is removed from the configuration, it should be *reset to its default value*. If a property is not declared as a public property, Chiasm has no way of knowing what its default value is. Therefore, to ensure stability and a consistently predictable state under all runtime configuration changes (including removing properties), the strict rule was added in Chiasm that **only public properties are allowed to be configured**. This is why an error is reported if a property is attempted to be configured that is not a public property.
+
+## Working with the DOM
+
+Here's how you can use the DOM and create elements associated with the plugin.
+
+```javascript
+function MyPlugin(){
+  var component = ChiasmComponent({
+    message: "Hello"
+  });
+  component.el = document.createElement("div");
+  return component;
+}
+```
+
+The property `el` stands for "element" (inspired by [el in Backbone Views](http://backbonejs.org/#View-el)). This element should be created in the component constructor. The [Chiasm Layout Plugin](https://github.com/chiasm-project/chiasm-layout) looks for this special property, and manages adding and removing this DOM element from a parent container element.
+
+From here, you can dive deeper and check out the [Chiasm Foundation Example](http://bl.ocks.org/curran/b4aa88691528c0f0b1fa), which contains a basic Chaism plugin that uses SVG, and another that uses Canvas.
+
+## Glossary
+
+The following terms have a precise meaning within the Chiasm project.
+
+ * **Plugin** A JavaScript module that defines a constructor function that returns a component.
+ * **Component** A [Model.js model](https://github.com/curran/model) constructed by a plugin.
+ * **Configuration** A JSON data structure that defines a collection of components and values for their public properties.
+ * **Public Properties** The set of properties for a given component that can be set via the configuration. Public properties are declared in a special component property `publicProperties`, an array of property name strings. All public properties must have default values.
+ * **Default Values** Values for public properties that are initially assigned to the properties at the time the component is constructed. Since all public properties must have default values, `Model.None` should be used in cases where the property is optional.

test.js

@@ -7,21 +7,39 @@ var expect = require('chai').expect
   it("should set public properties specified in constructor", function () {
-    var component = ChiasmComponent({
+
+    var my = ChiasmComponent({
       x: 5,
       y: 10
     });
-    expect(component.publicProperties.length).to.equal(2);
-    expect(component.publicProperties).to.contain("x");
-    expect(component.publicProperties).to.contain("y");
-    expect(component.x).to.equal(5);
-    expect(component.y).to.equal(10);
+
+    expect(my.publicProperties.length).to.equal(2);
+    expect(my.publicProperties).to.contain("x");
+    expect(my.publicProperties).to.contain("y");
+    expect(my.x).to.equal(5);
+    expect(my.y).to.equal(10);
   });
 
   it("should set public properties specified via addPublicProperty", function () {
-    var component = ChiasmComponent();
-    component.addPublicProperty("foo", "bar");
-    expect(component.publicProperties.length).to.equal(1);
-    expect(component.publicProperties).to.contain("foo");
-    expect(component.foo).to.equal("bar");
+    var my = ChiasmComponent();
+
+    my.addPublicProperty("foo", "bar");
+
+    expect(my.publicProperties.length).to.equal(1);
+    expect(my.publicProperties).to.contain("foo");
+    expect(my.foo).to.equal("bar");
   });
 
+  it("should set public properties specified via addPublicProperties", function () {
+    var my = ChiasmComponent();
+
+    my.addPublicProperties({
+      x: 50,
+      y: 100
+    });
+
+    expect(my.publicProperties.length).to.equal(2);
+    expect(my.publicProperties).to.contain("x");
+    expect(my.x).to.equal(50);
+    expect(my.publicProperties).to.contain("y");
+    expect(my.y).to.equal(100);
+  });
 });

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

14208

increased by90.46%

Number of package files

8

increased by14.29%

Lines of code

155

increased by34.78%

Number of lines in readme file

99

increased by2375%

No dependency changes