Commit b1f82ea1 authored by Seb's avatar Seb

added new series: details

parent af1bcb74
......@@ -14,6 +14,9 @@ series:
"snipspector":
desc: "Snipspector"
sort: 2
"102":
desc: "Advanced series"
"details":
desc: "Details"
sort: 3
"102":
desc: "Advanced bits"
sort: 4
---
title: 'Events'
layout: series_item
series: 'details'
estimated-time: 10
---
### Listen to events
~~~
objs.on("name", function(data) {
})
~~~
if you want to proxy events:
~~~
objs.onAll(function(evtName, data) {
})
~~~
[learn more](https://github.com/biojs/biojs-events)
### Expose your events
The registry now listen to every snippet that contains `//@biojs-instance=<variable>` and display the event console on the first received event.
Have a look at the [MSA component](http://biojs.io/d/biojs-vis-msa) or [Muts-Needle](http://biojs.io/d/muts-needle-plot) as an example.
Guidelines for events
----------------
You can choose any library that supports the choosen syntax.
Please provide
~~~
objs.on("name", function(data) {})
objs.off("name", function(data) {})
objs.once("name", function(data) {})
objs.trigger("name", function(data) {})
objs.onAll(function(eventName, data) {}) // (optional)
~~~
Here is a list of some popular libraries that offer this functionality:
* [Backbone](backbonejs.org)
* [Bean](https://github.com/fat/bean)
* [EventEmitter](https://github.com/Wolfy87/EventEmitter)
* [JS-signals](https://github.com/millermedeiros/js-signals)
* [MiniPubSub](https://github.com/neurodrone/MiniPubSub)
* [microevent.js](https://github.com/jeromeetienne/microevent.js)
* [atom](https://github.com/zynga/atom)
* [asEvented](https://github.com/mkuklis/asEvented)
* [Vine](https://github.com/arextar/Vine)
* [minivents](https://github.com/allouis/minivents)
Not all of them use the same method names or signatures. Please try to adapt those the signatures given above if you want to use them.
How to use
----------
### 1. install
~~~
npm install biojs-events --save
~~~
### 2. Mix the events capability with your object
After the code of your BioJS component add the events capability by mixing you component prototype with the event class
~~~
require('biojs-events').mixin(my_component.prototype);
~~~
### 3. Trigger events
Now in your code you can use the events methods (trigger, off,on,once):
~~~
this.trigger('onSomethingChanged', {
data : "some data"
});
~~~
and of course listen to your own events:
~~~
this.on('onSomethingChanged', function(data){
console.log(data); // will print "some data"
});
~~~
---
title: 'Reusability'
layout: series_item
series: 'details'
estimated-time: 10
---
The modularity and re-usability is one of the key ideas of BioJS. Maybe it helps to think of biojs.io as an "App Store" for JS components and "downloading the App" means actually embedding it in a website.
### General assumptions:
(user refers to someone who embeds your application, e.g. a website owner)
* you only have __one div__ (nobody wants to copy HTML that will change over versions, to some extent you could have more for optional user controls)
* a user is allowed to create multiple instances of your app (on the same page)
* a user might want to customize your app by changing some options - he will have its own file and customize the your settings
### This means:
* don't dumb HTML to the snippets - a general rule of thumb is that this makes your app hard to reuse -> only use "js" in the example
* If you want to stick with your HTML upload form, please provide at least one minimal example with just your raw component (see below for a minimal example)
* Don't use global variables!
* Consider the div that your application gets as a virtual environment for your component - only modify stuff inside of it
* A user will instantiate your application (=will call your main class with new)
* Don't do crazy shit with document.body or the Function.prototype
* Don't query the entire web page for DOM elements - an ID is unique. So $('#fancyId') won't work and $(".fancyClass") will return you the objects of all instances
A general advise is to create all the needed DOM elements in your component and save references to the most important ones.
---
title: 'Common code patterns'
layout: series_item
series: 'details'
estimated-time: 10
---
This is a list of common scenarios you might face - may this list be with you.
### How to have receive a DOM element from the examples?
`examples/simple.js`
~~~
var App = require("fancy-biojs-app");
var instance = new App({el: yourDiv, <other options>});
~~~
`index.js`
~~~
module.exports = function(opts){
var el = opts.el;
}
~~~
### How to receive a file?
`examples/simple.js`
~~~
var xhr = require("xhr");
var App = require("fancy-biojs-app");
xhr("<relative path to your file>", function(err,status, body){
var instance = new App({el: yourDiv, model: body});
});
~~~
You need to add the "xhr" module in the exposed section of the snippet configuration.
### How to have default options?
`examples/simple.js`
~~~
var App = require("fancy-biojs-app");
var instance = new App({el: yourDiv, fancyColor: blue});
~~~
` index.js`
~~~
var extend = require("js-extend").extend // you could also use underscore or jQuery
module.exports = function(userOpts){
var opts = {
fancyColor: "red"
}
opts = extend(opts, userOpts);
var el = userOpts.el;
}
~~~
{% hlblock help %}
You can also browse existing components at the registry.
{% endhlblock %}
---
title: 'Package.json'
layout: series_item
series: 'details'
estimated-time: 10
---
{% hlblock info %}
All the following parameters can be added or changed in your `package.json`
{% endhlblock %}
### Biojs specific parameters
* `logo`: alternative project logo (default: github avatar)
* `registryHeight`: height of the registry iFrame for your first example (default: 400)
* `publication`: PMID (Pubmed Id) to the most recent citation (can also be an array)
~~~
"biojs": {
"logo": "",
"registryHeight": "400",
}
~~~
### [Parcelify params](https://github.com/rotundasoftware/parcelify)
Specify css files for browserify (behaves like main for js)
~~~
style: "main.css"
~~~
### [BioJS2Galaxy params](https://github.com/biojs/biojs2galaxy)
~~~
"galaxy": {
"datatypes": []
}
~~~
### [General npm params](https://www.npmjs.org/doc/files/package.json.html)
* name
* version
* description
* keywords (use "biojs")
* homepage
* license
* contributors
* main
* repository
### Optional params
* author
* bugs
* bin
* scripts
* dependencies
* devDependencies
### Contributors
~~~
[{ "name" : "Barney Rubble"
, "email" : "b@rubble.com"
, "url" : "http://barnyrubble.tumblr.com/"
},{ "name" : "Barney Rubble 2"
, "email" : "b2@rubble.com"
, "url" : "http://barnyrubble2.tumblr.com/"
}]
~~~
### [Snippets](https://github.com/biojs/biojs-sniper)
~~~
"sniper": {
"js": ["/build/msa.js"],
"css": ["/css/msa.css"],
"snippets": ["examples"],
"first": "msa_show_menu"
}
~~~
optional attributes:
* `buildCSS` (will replace `css`)
* `buildJS` (will replace `js`)
The `build` attributes can be used to specify alternative locations - in any case the registry will ignore js resources starting with `build`.
{% hlblock info %}
Do you want to [learn more](https://github.com/biojs/biojs-sniper) about the `sniper`?
{% endhlblock %}
---
title: 'Adding CSS'
layout: series_item
series: 'details'
estimated-time: 10
---
{% hlblock info %}
We use [`parcelify`](https://github.com/rotundasoftware/parcelify) as this allows a CSS dependency chain (as you no it from browserify).
{% endhlblock %}
### 1. Add your CSS files to the `style` field
`package.json`
~~~
"style" : "css/*.css"
~~~
or
~~~
"style" : "*.scss"
~~~
{% hlblock info %}
The registry now _only_ picks the `style` dependencies - it doesn't merge it with your css files in the sniper section. So be sure that you add all css files - the "style" attribute can also be an array.
{% endhlblock %}
{% alert warn %}
You need to install `npm` before you can start to rock. See <a href="20_getting_started.html"> the getting started guide </a> for more info.
{% endalert %}
### 2. Adding a build tasks and updating the sniper
2.1) Install parcelify
~~~
npm install parcelify --save-dev
~~~
2.2) Adding it as a build task
`package.json`
~~~
"scripts": {
...
"css": "parcelify ./ -c build/bundle.css",
...
}
~~~
2.3) Update the sniper
~~~
css: ["/build/bundle.css"]
~~~
2.4) Optional: Parcelify has a watch mode
~~~
parcelify ./ -w -c build/bundle.css
~~~
### 3. Using a preprocessor (SASS, LESS, ...)
For CSS preprocessors like SASS or LESS you can use a parcelify tranform, see this example for SASS:
~~~
"transforms" : [ "sass-css-stream" ],
"dependencies" : {
"sass-css-stream": "~0.0.1"
}
~~~
{% hlblock info %}
Do you want to [learn more](https://github.com/rotundasoftware/parcelify#local-package-specific-transforms) about parcelify transforms?
{% endhlblock %}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment