PageRenderTime 55ms CodeModel.GetById 26ms RepoModel.GetById 1ms app.codeStats 0ms

/README.md

https://github.com/JeromeParadis/server-backbone-redis
Markdown | 215 lines | 160 code | 55 blank | 0 comment | 0 complexity | 46d4618b2b770398a6f3543aa4aa7770 MD5 | raw file
  1. # Why?
  2. I created this module because in a socket.io app I'm working on, all data is created, processed and persisted on the server. By having the models on the server-side with a Redis data store, it is easy to persist the data. With the export/import to JSON from JSON functionality, I can easily push data to clients connected through socket.io. Then, on the client-side, I continue to use the backbone models within views to update the UI.
  3. # Documentation
  4. * For up-to-date documentation, see the [Wiki](https://github.com/JeromeParadis/server-backbone-redis/wiki)
  5. * I sometimes update the doc at the bottom of this README
  6. # Dependencies
  7. npm install underscore
  8. npm install backbone
  9. npm install redis
  10. # Install Latest version
  11. npm install server-backbone-redis
  12. # Howto
  13. ## Documentation
  14. This module does two things:
  15. * sharing of models through server and client for a single code base
  16. * using Redis on the server-side as a data store to Backbone
  17. ## Backbone Models
  18. You can share your Backbone models for a single definition on the server and the client. Example of a ./models/models.js file. It uses CommonJS to include the right stuff when included in a node application. On the server side and client side, you will always use models.Backbone instead of Backbone.
  19. Create the name property in your models to define the object name. This name will be reused to generate Redis keys. Example:
  20. * Model name = "user", ID=2 -> Redis key = "user:2"
  21. (function () {
  22. var server = false, models;
  23. if (typeof exports !== 'undefined') {
  24. Backbone = require('../../../server-backbone-redis');
  25. models = exports;
  26. server = true;
  27. } else {
  28. models = this.models = {};
  29. }
  30. models.Backbone = Backbone;
  31. //
  32. //models
  33. //
  34. models.User = Backbone.Model.extend({
  35. defaults: {
  36. "id": null,
  37. "name": null,
  38. "entry": null
  39. },
  40. initialize: function() {
  41. var time = new Date();
  42. if (!this.get("entry"))
  43. this.set({entry: time});
  44. },
  45. name: "testuser"
  46. });
  47. models.UsersCollection = Backbone.Collection.extend({
  48. model: models.User
  49. });
  50. models.Wrapper = Backbone.Model.extend({});
  51. })()
  52. ## New JSON export/import model methods (available on server and client)
  53. ### xport()
  54. Exports object to JSON.
  55. ### mport()
  56. Import data into object from JSON.
  57. EJS example:
  58. var user1 = new models.User();
  59. user1.mport('<%- user1.xport() %>');
  60. ## New server-side Backbone properties/methods
  61. ### search(model_class,pattern,cb,err_cb)
  62. Example:
  63. models.Backbone.search(models.User,"*",function(results) {
  64. // follow the fetch collections results where results are an array of Backbone model attributes and not Backbone model objects
  65. // NOTE: if (new models.User()).name === "user", then Redis is searched with "keys user:*" command
  66. // So, we can load the collections ourselves
  67. var users = new models.UsersCollection(results);
  68. ... do something with users Backbone collection
  69. },function(err) { console.log(err); });
  70. ### search_delete(model_class,keypattern,cb,cb_err)
  71. Same as search() but will delete the objects of model_class who's IDs match the keypattern
  72. ### setClient(rc)
  73. Setup Redis client to avoid creating a second Redis connection.
  74. ### initServer(app)
  75. Setup a connect/express app with a handler to add a new server route the xport/mport script to the client. Script can be then include on the client:
  76. <script type="text/javascript" src="/sbr/backbone-exp-imp.js"></script>
  77. ### debug
  78. Set this property to true to show debugging information.
  79. ## Typical usage on the server:
  80. Once your models.js file is defined like above to include the server-side redis stuff. You simply include your models:
  81. var models = require('./models/models');
  82. You can access Backbone through models.Backbone.
  83. ## Typical includes on the client:
  84. <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
  85. <script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.1.7/underscore-min.js"></script>
  86. <script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/backbone.js/0.5.1/backbone-min.js"></script>
  87. <script type="text/javascript" src="/models/models.js"></script>
  88. <script type="text/javascript" src="/sbr/backbone-exp-imp.js"></script>
  89. ## Redis data store
  90. Server-side, you can use standard Backbone methods to save/persist to redis. The store uses the xport() and mport() methods to save and fetch the objects content in Redis. You can use the usual Backbone model and collections methods such as:
  91. * model.fetch()
  92. * model.save()
  93. * collection.fetch()
  94. You can supply your own Backbone IDs through the id property/attributes in Backbone models. If not supplied, the record will be incremented through a Redis incr counter. For example, the User model with it's name="user" will internally use these Redis keys:
  95. Record keys -> user:[ID] (i.e.: "user:1", "user:2", "user:3", etc.
  96. Counter key -> "next.user.id"
  97. You can specify your own keys to manually create relationship records. For example:
  98. models.User = Backbone.Model.extend({
  99. defaults: {
  100. "id": null,
  101. "name": null
  102. },
  103. name: "user"
  104. });
  105. models.Group = Backbone.Model.extend({
  106. defaults: {
  107. "id": null
  108. "name": null
  109. },
  110. name: "group"
  111. });
  112. models.UserGroup = Backbone.Model.extend({
  113. defaults: {
  114. "id": null
  115. "specs": null
  116. },
  117. name: "usergroup"
  118. });
  119. ...
  120. // user is loaded or fetched and has an id = 1 (Redis key: "user:1")
  121. //
  122. // group1 and group2 are fetched/saved and have ids 1 and 2 (Redis keys "group:1" & "group:2"
  123. ...
  124. var usergroup1 = new models.UserGroup({userid:user.id,groupid:group1.id});
  125. usergroup1.id = "group:" + group1.id + ":user:" + user.id;
  126. usergroup1.save({},{success: function(saved) {
  127. console.log("Saved usergroup1: " + saved.xport());
  128. }});
  129. var usergroup2 = new models.UserGroup({userid:user.id,groupid:group2.id});
  130. usergroup2.id = "group:" + group2.id + ":user:" + user.id;
  131. usergroup2.save({},{success: function(saved) {
  132. console.log("Saved usergroup2: " + saved.xport());
  133. }});
  134. // Will create the user group records with Redis keys= "usergroup:group:1:user:1" and "usergroup:group:2:user:1"
  135. # Acknowledgments
  136. * xport()/mport() code taken from this fine article: http://andyet.net/blog/2011/feb/15/re-using-backbonejs-models-on-the-server-with-node/
  137. * This article inspired me to add Node.js server-side Redis support to backbone
  138. # Disclaimer / To Do
  139. * Use at your own risk
  140. * Some code is redundant. Some cleanup to do.
  141. * Haven't tested for Redis injection vulnerability. Sanitize/check IDs on server before doing any fetch/create, etc.
  142. * It was created to do everything on the server and push some updates to the client through socket.io. Could add some express routes and backbone.js code on client-side to make calls from the client.
  143. * No Redis pub/sub features
  144. # MIT License
  145. Copyright (c) 2011 Jerome Paradis
  146. Permission is hereby granted, free of charge, to any person obtaining a copy
  147. of this software and associated documentation files (the "Software"), to deal
  148. in the Software without restriction, including without limitation the rights
  149. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  150. copies of the Software, and to permit persons to whom the Software is
  151. furnished to do so, subject to the following conditions:
  152. The above copyright notice and this permission notice shall be included in
  153. all copies or substantial portions of the Software.
  154. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  155. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  156. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  157. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  158. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  159. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  160. THE SOFTWARE.