Ampersand's view conventions. Also written as a test you can use to test if your module follows the conventions.
The core purpose of a view is to manage the contents, events, and behavior or a single DOM element.
In ampersand, a "view" doesn't have to actually be an "ampersand-view" at all.
But in order to maintain the ability to write a collection renderer or to be able to render sub-views it's useful to have a few simple conventions we follow.
Any object can be a view if it follows these rules.
For convenience, compliance can be tested via this npm module.
The rules are most easily explained by an example, here is a well-commented absolutely bare-minimum
In fact, this is the view we use to test the compliance test.
// If given an element as part of an options object// the view *should* store an element as `this.el`.thisel = optionsel;// All views should have a `render` method that creates, replaces, or// fills in the `this.el` property.// If passed in when created this view may already have a `this.el`.// If so, your render would method would populate it, or create a new// one and replace it (if already part of the DOM tree).if !thisel thisel = documentcreateElement'div';// The important thing is after calling `render` the view should have// a `this.el` that is a *real* DOM element.thiseltextContent = 'hello, awesome developer!';;// It should have a `remove` method that does any tear down you may want// to do. Including ideally removing itself from its parent (if reasonable to do so)// you could do it with vanilla JS like thisvar parent = thiselparentNode;if parent parentremoveChildthisel;// ...or if you're using jQuery you could just do// $(this.el).remove();;// CommonJS module, of coursemoduleexports = MinimalView;
npm install ampersand-view-conventions
The view compliance tests are written for tape. Simply pass in the test instance and your view constructor.
If there are additional required options for instantiating your view, pass those as a third argument.
var test = require'tape';var viewCompliance = require'ampersand-view-conventions';var YourView = require'your-awesome-view';// if there are no additional required arguments, you can just pass in// the constructorviewComplianceviewtest YourView;// if there's additional arguments required to instantiate your view// pass those in too. This is just minimal amount required to be able// to instantiate an instance of your view.viewComplianceviewtest YourView some: 'option object';// your other teststest'something'tpass;tend;
formField method and pass in the test instance, the view constructor, required options and a valid value.
var test = require'tape';var viewCompliance = require'ampersand-view-conventions';var YourFormFieldView = require'your-wicked-form-field-view';// you need at least a name for the required options and a valid valueviewComplianceformFieldtest YourFormFieldView name: 'field' 'valid value';// also run the view tests if you like, for good measureviewComplianceviewtest YourFormFieldView name: 'field';
Refer to minimal-field-view.js for an example form field that implements the conventions.