40 | Facettage.js is an open source library useful to backendless datascape prototyping.
41 |
42 | Examples above are included in the master branch of the repo, just clone it.
43 |
38 |
39 |
40 |
41 |
42 |
43 |
121 |
122 |
152 |
153 |
154 |
155 |
158 |
159 |
160 |
161 |
162 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | Facettage.js
2 | ============
3 |
4 | ### Facet management for backendless datascapes
5 | Facets are a mix of data and scripts. *Facettage* is a facet store that leverages this data/script duality: configure facets as memory structures and retrieve data like from a store.
6 |
7 | > "Information is beautiful, but backends are ugly."
8 | > _- David Backendless_
9 |
10 | * [DOWNLOAD](https://github.com/medialab/Facettage/blob/master/facettage.js) - [minified](https://github.com/medialab/Facettage/blob/master/facettage.min.js)
11 | * [EXAMPLES](http://medialab.github.io/Facettage/examples)
12 | * [API REFERENCE](https://github.com/medialab/Facettage/wiki/Facettage-API-reference)
13 |
14 | **MIT License**. Requires [D3.js](https://github.com/mbostock/d3) and [FileSaver.js](https://github.com/eligrey/FileSaver.js) to work properly.
15 |
16 | ### Problems it solves
17 | You are prototyping a backendless dashboard. Thanks to *D3.js* or other libraries, your javascript is really efficient at filtering and transforming data into multiple facets that you visualize with generic UX modules. However **all the facets are not made equal**. Some are reusable, and you want to keep them in memory, while others are not. Some are lightweight but costly to compute, and you want to cache them, while others are the opposite. *Facettage* solves different facet management issues:
18 |
19 | - You often want to **change how a facet is obtained**.
20 | - Some facets are less costly if you compute them from other facets, and you grow a **facet dependency tree**.
21 | - How to easily **generate cache files** when you have no backend?
22 | - You want to **clear certain facets** because of RAM issues, but not *that* heavy, costly but crucial facet that is needed everywhere.
23 |
24 | ### How to use
25 | Basically, you describe your facets and their properties before accessing them when you need it. With the proper configuration, *Facettage* relieves you from the burden of wondering how you should access each different facet.
26 |
27 | > "Few it's more."
28 | > _- Morritz Few_
29 |
30 | #### 1. Create a facet
31 | There are 3 ways to create a new facet:
32 | ```javascript
33 | // Facet from data
34 | var facet = Facettage.newFacet('jedi', {
35 | data: {name: 'Anakin Skywalker'}
36 | });
37 | ```
38 |
39 | ```javascript
40 | // Facet from file. This example requires the proper CSV file in the data cache.
41 | var facet = Facettage.newFacet('jedi', {
42 | cached: true,
43 | type: 'csv'
44 | });
45 | ```
46 |
47 | ```javascript
48 | // Facet from function
49 | var facet = Facettage.newFacet('jedi', {
50 | compute: function(){ return {name: 'Anakin Skywalker'}; }
51 | });
52 | ```
53 |
54 | #### 2. Retrieve the data from the facet
55 |
56 | When you ask data to the facet, you do not care where it comes from.
57 |
58 | ```javascript
59 | myFacet.retrieveData( function (data) {
60 | // Do something with data
61 | });
62 | ```
63 |
64 | *Facettage* even stores the facet from you.
65 |
66 | ```javascript
67 | // Get the facet from its name
68 | Facettage.getFacet('my-facet')
69 | .retrieveData( function (data) {
70 | // Do something with data
71 | });
72 | ```
73 |
74 | The ```retrieveData()``` method gets the data from memory if it is available, then downloads from the cache if it is ```cached```, and finally computes it if it has a ```compute()``` method. These specific methods are also available if you want.
75 |
76 | #### 3. Create and resolve facet dependencies
77 | ```javascript
78 | // The 'root' data is a list of things stored in a CSV file
79 | Facettage.newFacet('list-of-things.csv', {
80 | cached: true,
81 | type: 'csv'
82 | });
83 |
84 | // This facet is a filtered version of the list
85 | Facettage.newFacet('red-things', {
86 | dependencies:['list-of-things.csv'],
87 | compute: function () {
88 | return Facettage.getFacet('list-of-things.csv')
89 | .getData()
90 | .filter( function (d) {
91 | return d.color == 'red';
92 | });
93 | }
94 | });
95 |
96 | // You can ask for 'red-things' from there, the dependency will be resolved before.
97 | Facettage.getFacet('red-things')
98 | .retrieveData( function (redThings) {
99 | // Do something with redThings
100 | });
101 | ```
102 |
103 | #### Generating the cache
104 |
105 | *Facettage* helps you to download the facet data.
106 |
107 | ```javascript
108 | // Download a facet
109 | Facettage.getFacet('countries-stat-summary').download();
110 | // The downloaded JSON file has the facet for name: 'countries-stat-summary'
111 |
112 | // Download all facets that need to be
113 | Facettage.downloadCacheables();
114 | ```
115 |
116 | The ```downloadCacheables()``` downloads any facet that:
117 | - is not already cached,
118 | - has been computed,
119 | - and is not ```uncacheable```.
120 |
121 | Take the downloaded files, put them in the 'data/cache/' folder where *Facettage* will retrieve them. Then edit your code to activate the cache for that facet. Do not erase the ```compute()``` method, it may be useful later if you change your mind.
122 |
123 | Note: you can specify additional methods to serialize and unserialize data.
124 |
125 | ### More
126 |
127 | Take a look at the source code of [online examples](http://medialab.github.io/Facettage/examples/).
128 |
129 | Also, [api reference](https://github.com/medialab/Facettage/wiki/Facettage-API-reference).
130 |
131 |
--------------------------------------------------------------------------------
/examples/07.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 | Facettage
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 |
25 |
26 | Facettage.js
27 |
40 | In order to cache the data, we have to compute and download the cached file:
41 |
42 |
43 |
44 | We are then supposed to put that file in the cache directory located in data/cache/. It is already the case, so we can load it from cache already:
45 |