Skip to content
Newer
Older
100644 162 lines (102 sloc) 8.57 KB
a14effc @bergie Move images out of the root
bergie authored
1 ![VIE](https://raw.github.com/bergie/VIE/master/design/vie_logo_100.png) Vienna IKS Editables
ac9f574 @bergie Zart has landed
bergie authored
2 ====================
17fb439 @bergie Initial
bergie authored
3
ac9f574 @bergie Zart has landed
bergie authored
4 VIE is a utility library for implementing [decoupled Content Management systems](http://bergie.iki.fi/blog/decoupling_content_management/). VIE is developed [as part of](http://wiki.iks-project.eu/index.php/VIE) the EU-funded [IKS project](http://www.iks-project.eu/).
09496e8 @bergie Quick docs on building and testing
bergie authored
5
a14effc @bergie Move images out of the root
bergie authored
6 ![Decoupled CMS communications](https://raw.github.com/bergie/VIE/master/design/cms-decoupled-communications.png)
ab54a26 @bergie Example of RDFa parsing with Zart
bergie authored
7
ac9f574 @bergie Zart has landed
bergie authored
8 * In French, _vie_ means life, showcasing how VIE makes your website come alive
9 * In English, _vie_ means striving for victory or superiority
ab54a26 @bergie Example of RDFa parsing with Zart
bergie authored
10
bfb1ce8 @bergie Link to the VIE intro post on IKS blog
bergie authored
11 VIE development is now targeting a 2.0 release. [Read this blog post](http://bergie.iki.fi/blog/vie_2-0_is_starting_to_emerge/) to find out the changes from VIE 1.0. There is also a [good introductory post on VIE](http://blog.iks-project.eu/semantic-ui-development-with-vie/) on the IKS blog.
ce18888 @bergie Link to the VIE 2.x blog post
bergie authored
12
ac9f574 @bergie Zart has landed
bergie authored
13 ## VIE integration in nutshell
ab54a26 @bergie Example of RDFa parsing with Zart
bergie authored
14
ac9f574 @bergie Zart has landed
bergie authored
15 Adding VIE to your system is as easy as:
16
17 1. Mark up your pages with RDFa annotations
18 2. Include `vie.js` into the pages
19 3. Implement [Backbone.sync](http://documentcloud.github.com/backbone/#Sync)
20
21 ## Common representation of content on HTML level
22
23 A web editing tool has to understand the contents of the page. It has to understand what parts of the page should be editable, and how they connect together. If there is a list of news for instance, the tool needs to understand it enough to enable users to add new news items. The easy way of accomplishing this is to add some semantic annotations to the HTML pages. These annotations could be handled via Microformats, HTML5 microdata, but the most power lies with RDFa.
24
25 RDFa is a way to describe the meaning of particular HTML elements using simple attributes. For example:
26
27 <div id="myarticle" typeof="http://rdfs.org/sioc/ns#Post" about="http://example.net/blog/news_item">
28 <h1 property="dcterms:title">News item title</h1>
29 <div property="sioc:content">News item contents</div>
30 </div>
31
32 Here we get all the necessary information for making a blog entry editable:
33
34 * typeof tells us the type of the editable object. On typical CMSs this would map to a content model or a database table
35 * about gives us the identifier of a particular object. On typical CMSs this would be the object identifier or database row primary key
36 * property ties a particular HTML element to a property of the content object. On a CMS this could be a database column
37
38 As a side effect, this also makes pages more understandable to search engines and other semantic tools. So the annotations are not just needed for UI, but also for SEO.
39
40 ## Common representation of content on JavaScript level
41
42 Having contents of a page described via RDFa makes it very easy to extract the content model into JavaScript. We can have a common utility library for doing this, but we also should have a common way of keeping track of these content objects. Enter [Backbone.js](http://documentcloud.github.com/backbone/):
43
44 > Backbone supplies structure to JavaScript-heavy applications by providing models with key-value binding and custom events, collections with a rich API of enumerable functions, views with declarative event handling, and connects it all to your existing application over a RESTful JSON interface.
45
46 With Backbone, the content extracted from the RDFa-annotated HTML page is easily manageable via JavaScript. Consider for example:
47
0bba262 @bergie Update the README
bergie authored
48 v = new VIE();
49 v.use(new v.RdfaService());
50 v.load({element: jQuery('#myarticle')}).from('rdfa').execute().success(function(entities) {
51 _.forEach(entities, function(entity) {
52 entity.set({'dcterms:title': 'Hello, world'});
53 entity.save(null, {
54 success: function(savedModel, response) {
55 alert("Your article '" + savedModel.get('dcterms:title') + "' was saved to server");
56 }
57 });
58 })
59 console.log("We got " + entities.length + " editable objects from the page");
60 });
61
62 The classic VIE API will also work:
63
ac9f574 @bergie Zart has landed
bergie authored
64 var objectInstance = VIE.RDFaEntities.getInstance(jQuery('#myarticle'));
65 objectInstance.set({'dcterms:title': 'Hello, world'});
66 objectInstance.save(null, {
67 success: function(savedModel, response) {
68 alert("Your article '" + savedModel.get('dcterms:title') + "' was saved to server");
69 }
ab54a26 @bergie Example of RDFa parsing with Zart
bergie authored
70 });
71
ac9f574 @bergie Zart has landed
bergie authored
72 This JS would work across all the different CMS implementations. Backbone.js provides a quite nice RESTful implementation of communicating with the server with JSON, but it can be easily overridden with CMS-specific implementation by just implementing a new [Backbone.sync method](http://documentcloud.github.com/backbone/#Sync).
1be9eb8 @bergie Document deferred I/O
bergie authored
73
ac9f574 @bergie Zart has landed
bergie authored
74 ## Example
1be9eb8 @bergie Document deferred I/O
bergie authored
75
ac9f574 @bergie Zart has landed
bergie authored
76 There is a full static HTML example of VIE at work. Saving outputs the edited contents as JSON into the JavaScript console:
1be9eb8 @bergie Document deferred I/O
bergie authored
77
ac9f574 @bergie Zart has landed
bergie authored
78 * [Example with Aloha Editor](https://github.com/bergie/VIE/raw/master/example.html)
79 * [Example with WYMeditor](https://github.com/bergie/VIE/blob/wymeditor/example-wymeditor.html)
d27b892 @bergie Quickly mention the dependencies
bergie authored
80
ac9f574 @bergie Zart has landed
bergie authored
81 Be sure to read the [annotated VIE source code](http://bergie.github.com/VIE/) for API documentation.
d27b892 @bergie Quickly mention the dependencies
bergie authored
82
0bba262 @bergie Update the README
bergie authored
83 ## I/O operations
84
85 All Input/Output operations of VIE are based on the [jQuery Deferred](http://api.jquery.com/category/deferred-object/) object, which means that you can attach callbacks to them either before they run, or also after they've been run.
86
87 The operations may either succeed, in which case the `then` callbacks will fire, or be rejected, in which case the `fail` callbacks will fire. Any `then` callbacks will fire in either case.
88
89 ## Dependencies
90
91 VIE uses the following JavaScript libraries:
92
93 * [jQuery](http://jquery.com/) for DOM manipulation and [Deferreds](http://api.jquery.com/category/deferred-object/)
94 * [Backbone.js](http://documentcloud.github.com/backbone/) for entities (models) and collections
95 * [Underscore.js](http://documentcloud.github.com/underscore/) for various JavaScript utilities
96
97 Some functionality in VIE additionally uses:
98
99 * [RdfQuery](http://code.google.com/p/rdfquery/) as a triplestore and for reasoning over rules
100
ac9f574 @bergie Zart has landed
bergie authored
101 ## Implementations
d27b892 @bergie Quickly mention the dependencies
bergie authored
102
ac9f574 @bergie Zart has landed
bergie authored
103 * [Midgard Create](https://github.com/bergie/midgardmvc_ui_create)
104 * [WordPress](https://github.com/Jotschi/Aloha-Editor-Wordpress-Plugin)
105 * [TYPO3](http://git.typo3.org/TYPO3v5/Distributions/Base.git)
106 * [KaraCos](http://gitorious.org/karacos2-wsgi-web-applications-engine/karacos2-wsgi-web-applications-engine)
107 * Gentics Enterprise CMS
108 * Drupal
109 * Jekyll
110 * Plone ([GSoC 2011 proposal](http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/dalsh/1))
111 * [Symfony2](https://github.com/liip/LiipVieBundle)
d27b892 @bergie Quickly mention the dependencies
bergie authored
112
ac9f574 @bergie Zart has landed
bergie authored
113 ## Using VIE on Node.js
d27b892 @bergie Quickly mention the dependencies
bergie authored
114
ac9f574 @bergie Zart has landed
bergie authored
115 VIE is a CommonJS library that works on both browser and the server. On [Node.js](http://nodejs.org/) you can install it with:
116
117 npm install vie
09496e8 @bergie Quick docs on building and testing
bergie authored
118
ac9f574 @bergie Zart has landed
bergie authored
119 Here is a simple Node.js script that uses VIE for parsing RDFa:
09496e8 @bergie Quick docs on building and testing
bergie authored
120
ac9f574 @bergie Zart has landed
bergie authored
121 var jQuery = require('jquery');
4e550be @bergie Update Node example
bergie authored
122 var vie = require('vie');
123 var VIE = new vie.VIE();
09496e8 @bergie Quick docs on building and testing
bergie authored
124
ac9f574 @bergie Zart has landed
bergie authored
125 var html = jQuery('<p xmlns:dc="http://purl.org/dc/elements/1.1/" about="http://www.example.com/books/wikinomics">In his latest book <cite property="dc:title">Wikinomics</cite>, <span property="dc:creator">Don Tapscott</span> explains deep changes in technology, demographics and business.</p>');
126
127 VIE.RDFaEntities.getInstances(html);
128 var objectInstance = VIE.EntityManager.getBySubject('http://www.example.com/books/wikinomics');
129
130 console.log(objectInstance.get('dc:title'));
131
132 ## Development
09496e8 @bergie Quick docs on building and testing
bergie authored
133
ac9f574 @bergie Zart has landed
bergie authored
134 VIE development is coordinated using Git. [VIE@IKS](https://github.com/IKS/VIE) is the canonical "blessed repository", with actual development happening at [VIE@bergie](https://github.com/bergie/VIE).
09496e8 @bergie Quick docs on building and testing
bergie authored
135
0bba262 @bergie Update the README
bergie authored
136 Feel free to [report issues](https://github.com/bergie/VIE/issues) or send [pull requests](http://help.github.com/pull-requests/) if you have ideas for pushing VIE forward. Contributions that include their own unit tests appreciated!
09496e8 @bergie Quick docs on building and testing
bergie authored
137
ac9f574 @bergie Zart has landed
bergie authored
138 Development discussions happen on the `#iks` channel on Freenode. See also [VIE on Ohloh](http://www.ohloh.net/p/vie).
09496e8 @bergie Quick docs on building and testing
bergie authored
139
0bba262 @bergie Update the README
bergie authored
140 ### Code organization
141
142 VIE source code is inside the `src` directory. Each separate unit of functionality should be handled in its own file, with the `src/VIE.js` being the entry point to the system.
143
144 ### Building VIE
145
146 The VIE library consists of many individual pieces that we merge together in the build process. You'll need [Apache Ant](http://ant.apache.org/). Then just run:
147
148 $ ant
149
150 The built VIE library will appear in the `dist` folder.
151
ac9f574 @bergie Zart has landed
bergie authored
152 ### Running Unit Tests
09496e8 @bergie Quick docs on building and testing
bergie authored
153
0bba262 @bergie Update the README
bergie authored
154 Direct your browser to the `test/index.html` file to run VIE's [QUnit](http://docs.jquery.com/Qunit) tests.
155
156 #### Unit tests on Node.js
157
52172d1 @bergie Easier testing instructions
bergie authored
158 You need Node.js and [NPM](http://npmjs.org/). Then just run:
09496e8 @bergie Quick docs on building and testing
bergie authored
159
52172d1 @bergie Easier testing instructions
bergie authored
160 $ npm install --dev
161 $ npm test
Something went wrong with that request. Please try again.