netzke-core 0.12.3 → 1.0.0.0.pre

Sign up to get free protection for your applications and to get access to all the features.
Files changed (41) hide show
  1. data/CHANGELOG.md +65 -607
  2. data/Gemfile +1 -1
  3. data/LICENSE +2 -6
  4. data/README.md +77 -145
  5. data/javascripts/base.js +582 -96
  6. data/javascripts/core.js +62 -0
  7. data/javascripts/notifications.js +43 -0
  8. data/javascripts/remoting_provider.js +29 -0
  9. data/javascripts/routing.js +63 -0
  10. data/lib/netzke/base.rb +16 -83
  11. data/lib/netzke/core/action_config.rb +1 -5
  12. data/lib/netzke/core/actions.rb +59 -21
  13. data/lib/netzke/core/{client_class.rb → client_class_config.rb} +81 -73
  14. data/lib/netzke/core/client_code.rb +157 -0
  15. data/lib/netzke/core/component_config.rb +2 -2
  16. data/lib/netzke/core/composition.rb +85 -65
  17. data/lib/netzke/core/configuration.rb +26 -14
  18. data/lib/netzke/core/core_i18n.rb +17 -0
  19. data/lib/netzke/core/css_config.rb +6 -6
  20. data/lib/netzke/core/dynamic_assets.rb +17 -24
  21. data/lib/netzke/core/embedding.rb +2 -2
  22. data/lib/netzke/core/endpoint_response.rb +8 -2
  23. data/lib/netzke/core/inheritance.rb +33 -0
  24. data/lib/netzke/core/plugins.rb +1 -4
  25. data/lib/netzke/core/railz/action_view_ext.rb +1 -1
  26. data/lib/netzke/core/railz/controller_extensions.rb +21 -15
  27. data/lib/netzke/core/services.rb +61 -48
  28. data/lib/netzke/core/session.rb +0 -2
  29. data/lib/netzke/core/state.rb +11 -9
  30. data/lib/netzke/core/stylesheets.rb +3 -3
  31. data/lib/netzke/core/version.rb +1 -1
  32. data/lib/netzke/core.rb +3 -3
  33. data/lib/netzke/plugin.rb +2 -6
  34. data/stylesheets/core.css +2 -2
  35. metadata +11 -10
  36. data/TODO.md +0 -9
  37. data/javascripts/ext.js +0 -518
  38. data/lib/netzke/core/config_to_dsl_delegator.rb +0 -62
  39. data/lib/netzke/core/dsl_support.rb +0 -70
  40. data/lib/netzke/core/html.rb +0 -29
  41. data/lib/netzke/core/javascript.rb +0 -123
data/Gemfile CHANGED
@@ -2,7 +2,7 @@ source 'http://rubygems.org'
2
2
 
3
3
  gemspec
4
4
 
5
- gem 'rails', '4.2.0'
5
+ gem 'rails', '~>4.2.0'
6
6
  gem 'sqlite3'
7
7
  gem 'yard'
8
8
  gem 'rake'
data/LICENSE CHANGED
@@ -1,7 +1,3 @@
1
- Copyright (c) 2012 nomadcoder
1
+ Copyright (c) 2009-2015 Good Bit Labs Limited
2
2
 
3
- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4
-
5
- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6
-
7
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
3
+ GPLv3 License: http://www.gnu.org/licenses/gpl-3.0.en.html
data/README.md CHANGED
@@ -1,116 +1,16 @@
1
- # Netzke Core [![Gem Version](https://fury-badge.herokuapp.com/rb/netzke-core.png)](http://badge.fury.io/rb/netzke-core) [![Build Status](https://travis-ci.org/netzke/netzke-core.png?branch=master)](https://travis-ci.org/netzke/netzke-core) [![Code Climate](https://codeclimate.com/github/netzke/netzke-core.png)](https://codeclimate.com/github/netzke/netzke-core)
1
+ # Netzke Core [![Build Status](https://travis-ci.org/netzke/netzke-core.svg?branch=master)](https://travis-ci.org/netzke/netzke-core) [![Code Climate](https://codeclimate.com/github/netzke/netzke-core/badges/gpa.svg)](https://codeclimate.com/github/netzke/netzke-core)
2
2
 
3
- [RDocs](http://rdoc.info/projects/netzke/netzke-core)
3
+ [RDocs](http://www.rubydoc.info/projects/netzke/netzke-core)
4
4
 
5
5
  Netzke Core is the bare bones of the [Netzke framework](http://netzke.org). For pre-built full-featured components (like grids, forms, tab/accordion panels, etc), see [netzke-basepack](http://github.com/netzke/netzke-basepack).
6
6
 
7
- Some knowledge of Sencha Ext JS will be needed in order to fully understand this overview.
7
+ *Notes on versioning:*
8
8
 
9
- ## Rationale
9
+ * The latest *released* version is: [![Gem Version](https://badge.fury.io/rb/netzke-basepack.svg)](https://badge.fury.io/rb/netzke-basepack)
10
+ * The version under development (master): [version.rb](https://github.com/netzke/netzke-core/blob/master/lib/netzke/core/version.rb)
11
+ * For other versions check corresponding [branches](https://github.com/netzke/netzke-core/branches)
10
12
 
11
- [Sencha Ext JS]("http://www.sencha.com/products/extjs") is a powerful front-end framework, which is used for crafting web-apps that give the end user experience similar to that of a desktop application. It has an extensive set of widgets ('components'), and leverages a modular approach to its fullest: a developer can extend components (using Ext JS's own [class system]("http://docs.sencha.com/ext-js/4-1/#!/guide/class_system")), nest components using many powerful layouts, dynamically create and destroy them. The architecture of Ext JS is well thought out and very complete.
12
-
13
- However, with Ext JS being server-agnostic, it is not always a trivial task for a developer to bind Ext JS components to the server-side data *and* application business logic, especially in complex applications. Netzke as the solution that allows you to extend the modular approach to the server side.
14
-
15
- Netzke Core takes the burden of implementing the following key aspects of the framework:
16
-
17
- * Client-side (JavaScript) class generation
18
- * Client-server communication
19
- * Convenient declaration of Ext actions
20
- * Extendibility of components (class inheritance and mixins)
21
- * Unlimited nesting (composition)
22
- * Dynamic component loading
23
- * Client-side class caching
24
- * Inclusion of extra JavaScript and CSS files
25
-
26
- ...and more.
27
-
28
- All this extremely facilitates building fast, low-traffic, robust, and highly maintainable applications. As a result, your code scales much better in the sense of complexity, compared to using conventional MVC, where developers are pretty much limited with the programming techniques that they can apply.
29
-
30
- ## HelloWorld component
31
-
32
- *This component is distributed as a part of the test application, see `spec/rails_app/components/hello_world.rb`.*
33
-
34
- Ext JS files are not distributed with Netzke, so, make sure that they are located in (or sym-linked as) `YOUR_APP/public/extjs`.
35
-
36
- In `YOUR_APP/components/hello_world.rb`:
37
-
38
- ```ruby
39
- class HelloWorld < Netzke::Base
40
- # Configure client class
41
- js_configure do |c|
42
- c.title = "Hello World component"
43
- c.mixin # mix in methods from hello_world/javascripts/hello_world.js
44
- end
45
-
46
- # Actions are used by Ext JS to share functionality and state b/w buttons and menu items
47
- # The handler for this action should be called onPingServer by default
48
- action :ping_server
49
-
50
- # Self-configure with a bottom toolbar
51
- def configure(c)
52
- super
53
- c.bbar = [:ping_server] # embed the action into bottom toolbar as a button
54
- end
55
-
56
- # Endpoint callable from client class
57
- endpoint :greet_the_world do |params,this|
58
- # call client class' method showGreeting
59
- this.show_greeting("Hello World!")
60
- end
61
- end
62
- ```
63
-
64
- In `YOUR_APP/components/hello_world/javascripts/hello_world.js` put the client class (JavaScript) methods:
65
-
66
- ```javascript
67
- {
68
- // handler for the ping_server action
69
- onPingServer: function(){
70
- // calling greet_the_world endpoint
71
- this.greetTheWorld();
72
- },
73
-
74
- // called by the server as the result of executing the endpoint
75
- showGreeting: function(greeting){
76
- this.update("Server says: " + greeting);
77
- }
78
- }
79
- ```
80
-
81
- To embed the component in Rails view:
82
-
83
- Add `netzke` routes:
84
-
85
- ```ruby
86
- # in routes.rb
87
- RailsApp::Application.routes.draw do
88
- netzke
89
- ...
90
- end
91
- ```
92
-
93
- Use `load_netzke` in the layout to include Ext JS and Netzke scripts and stylesheets:
94
-
95
- ```erb
96
- <!DOCTYPE html>
97
- <html>
98
- <head>
99
- <meta http-equiv="Content-type" content="text/html; charset=utf-8">
100
- <%= csrf_meta_tag %>
101
- <%= load_netzke %>
102
- </head>
103
- <body>
104
- <%= yield %>
105
- </body>
106
- </html>
107
- ```
108
-
109
- Embed the component in the Rails view:
110
-
111
- ```erb
112
- <%= netzke :hello_world %>
113
- ```
13
+ For rationale and mini-tutorial, refer to the meta gem's [README](https://github.com/netzke/netzke). The README you're reading explains the Netzke architecture in detail. Some knowledge of Sencha Ext JS may be required to fully understand this overview.
114
14
 
115
15
  ## What is a Netzke component
116
16
 
@@ -129,17 +29,16 @@ your_web_app
129
29
  my_component.rb <-- the Ruby class
130
30
  my_component
131
31
  some_module.rb <-- optional extra Ruby code
132
- javascripts
32
+ client
133
33
  some_dependency.js <-- optional external JS library
134
- init_component.js <-- optional mixins to the client class
135
- extra_functionality.js <-- more mixins (mixin-in may depend on component class configuration)
136
- stylesheets
34
+ init_component.js <-- optional override ("include") to the client class
35
+ extra_functionality.js <-- more override
137
36
  my_special_button.css <-- optional custom CSS
138
37
  ```
139
38
 
140
39
  ## Client class
141
40
 
142
- The generated client class is *inherited* (as defined by the Ext JS [class system]("http://docs.sencha.com/ext-js/4-1/#!/guide/class_system")) from an Ext JS class, which by default is [Ext.panel.Panel]("http://docs.sencha.com/ext-js/4-1/#!/api/Ext.panel.Panel"). For example, a component defined like this:
41
+ The generated client class is *inherited* (as defined by the Ext JS class system) from an Ext JS class, which by default is `Ext.panel.Panel`. For example, a component defined like this:
143
42
 
144
43
  ```ruby
145
44
  class HelloWorld < Netzke::Base
@@ -149,10 +48,10 @@ end
149
48
  will have the following client class generated by Netzke (simplified):
150
49
 
151
50
  ```javascript
152
- Ext.define('Netzke.classes.HelloWorld', {"extend":"Ext.panel.Panel", "mixins":["Netzke.classes.Core.Mixin"]});
51
+ Ext.define('Netzke.classes.HelloWorld', {"extend":"Ext.panel.Panel", "mixins":["Netzke.Base"]});
153
52
  ```
154
53
 
155
- `Netzke.classes.Core.Mixin` contains a set of client class methods and properties common to every Netzke component.
54
+ `Netzke.Base` contains a set of client class methods and properties common to every Netzke component.
156
55
 
157
56
  Extending `HelloWorld` will be automatically reflected on the client-class level:
158
57
 
@@ -167,18 +66,23 @@ will have the following client class generated (simplified):
167
66
  Ext.define('Netzke.classes.HelloNewWorld', {"extend":"Netzke.classes.HelloWorld"});
168
67
  ```
169
68
 
170
- The configuration of a client-class is done by using the `Netzke::Base.js_configure`. For example, in order to inherit from a different Ext JS component, and to mix in the methods defined in an external JavaScript class:
69
+ Configuration of the client-class can be done by using the `Netzke::Base.client_class`. For example, in order to inherit from a different Ext JS component, and to mix in the methods defined in the `client` subfolder:
171
70
 
172
71
  ```ruby
173
72
  class MyTabPanel < Netzke::Base
174
- js_configure do |c|
73
+ client_class do |c|
175
74
  c.extend = "Ext.tab.Panel"
176
- c.mixin :extra_functionality
75
+ c.include :extra_functionality
177
76
  end
178
77
  end
179
78
  ```
180
79
 
181
- For more details on defining the client class, refer to [Netzke::Core::ClientClass](http://rdoc.info/github/netzke/netzke-core/Netzke/Core/ClientClass).
80
+ The code above will set the `extend` property to "Ext.tab.Panel", and will mix in the following scripts:
81
+
82
+ * `app/components/my_tab_panel/client/my_tab_panel.js` (if that exists)
83
+ * `app/components/my_tab_panel/client/extra_functionality.js`
84
+
85
+ For more details on defining the client class, refer to [Netzke::Core::ClientClassConfig](http://www.rubydoc.info/github/netzke/netzke-core/Netzke/Core/ClientClassConfig).
182
86
 
183
87
  ## Composition
184
88
 
@@ -216,15 +120,15 @@ Next to being statically nested in the layout, a child component can also be dyn
216
120
 
217
121
  this.netzkeLoadComponent('users');
218
122
 
219
- this will load the "users" component and [add](http://docs.sencha.com/ext-js/4-1/#!/api/Ext.container.Container-method-add) it to the current container.
123
+ this will load the "users" component and add it to the current container.
220
124
 
221
- For more details on dynamic component loading refer to inline docs of [javascript/ext.js](https://github.com/netzke/netzke-core/blob/master/javascripts/ext.js).
125
+ For more details on dynamic component loading refer to [netzkeLoadComponent docs](http://api.netzke.org/client/classes/Netzke.Base.html#method_netzkeLoadComponent).
222
126
 
223
- For more details on composition refer to [Netzke::Core::Composition](http://rdoc.info/github/netzke/netzke-core/Netzke/Core/Composition).
127
+ For more details on composition refer to [Netzke::Core::Composition](http://www.rubydoc.info/github/netzke/netzke-core/Netzke/Core/Composition).
224
128
 
225
129
  ## Actions, toolbars, and menus
226
130
 
227
- Actions are [used by Ext JS]("http://docs.sencha.com/ext-js/4-1/#!/api/Ext.Action") to share functionality and state among multiple buttons and menu items. Define actions with the `action` class method:
131
+ Actions are used by Ext JS to share functionality and state among multiple buttons and menu items. Define actions with the `action` class method:
228
132
 
229
133
  ```ruby
230
134
  action :show_report do |c|
@@ -250,11 +154,11 @@ Actions can also be referred to is submenus:
250
154
  c.tbar = [{text: 'Menu', menu: {items: [:show_report]}}]
251
155
  ```
252
156
 
253
- For more details on composition refer to [Netzke::Core::Actions](http://rdoc.info/github/netzke/netzke-core/Netzke/Core/Actions).
157
+ For more details on composition refer to [Netzke::Core::Actions](http://www.rubydoc.info/github/netzke/netzke-core/Netzke/Core/Actions).
254
158
 
255
159
  ## Client-server interaction
256
160
 
257
- Communication between the client class and the corresponding server class is done by means of defining *endpoints*. By defining an endpoint on the server, the client class automatically gets a method that is used to call the server.
161
+ Communication between the client class and the corresponding server class is done by means of defining *endpoints*. By defining an endpoint on the server, the client class automatically gets access to an equally named method that calls the server.
258
162
 
259
163
  ### Calling an endpoint from client class
260
164
 
@@ -262,40 +166,54 @@ By defining an endpoint like this:
262
166
 
263
167
  ```ruby
264
168
  class SimpleComponent < Netzke::Base
265
- endpoint :whats_up_server do |params, this|
169
+ endpoint :whats_up do |greeting|
266
170
  # ...
267
171
  end
268
172
  end
269
173
  ```
270
174
 
271
- ...the client class will obtain a method called `whatsUpServer`:
175
+ ...the client class will obtain a method called `whatsUp`, that can be called on the `this.server` object like this:
272
176
 
273
177
  ```javascript
274
- this.whatsUpServer(params, callback, scope);
178
+ this.server.whatsUp(greeting, callback, scope);
275
179
  ```
276
180
 
277
- Parameters:
181
+ The last 2 params are optional:
182
+
183
+ * `callback` - function to be called after the server successfully processes the endpoint call; the function will receive, as its only argument, the result of the `endpoint` block execution
184
+ * `scope` - context in which the callback function will be called; defaults to the component's instance
185
+
186
+ As of version 1.0, the endpoint may receive an arbitrary number of arguments, for example:
278
187
 
279
- * `params` will be passed to the endpoint block as the first parameter
280
- * `callback` (optional) receives a function to be called after the server successfully processes the endpoint call
281
- * `scope` (optional) is the scope in which the callback function will be called
188
+ ```javascript
189
+ this.server.doSomething('value 1', true, callback, scope);
190
+ ```
191
+
192
+ ```ruby
193
+ class SimpleComponent < Netzke::Base
194
+ endpoint :do_something do |arg_1, arg_2|
195
+ # arg_1 == 'value 1'
196
+ # arg_2 == true
197
+ end
198
+ end
199
+ ```
282
200
 
283
201
  ### Calling client class methods from endpoint
284
202
 
285
- An endpoint can instruct the client class to execute a set of methods after its execution, passing those methods arbitrary parameters. For example:
203
+ An endpoint can instruct the client instance of the component to execute a set of methods in response, passing those methods arbitrary parameters, by using the `client` method. For example:
286
204
 
287
205
  ```ruby
288
206
  class SimpleComponent < Netzke::Base
289
- endpoint :whats_up_server do |params, this|
290
- this.set_title("Response from server")
291
- this.my_method
207
+ endpoint :whats_up_server do
208
+ client.set_title("Response from server")
209
+ client.my_method
292
210
  end
293
211
  end
294
212
  ```
295
213
 
296
- Here the client class will call its `setTitle` method (defined in `Ext.panel.Panel`) with parameter passed from the endpoint. Then a custom method `myMethod` will be called with no parameters.
214
+ Here the client class will first call its `setTitle` method (defined in `Ext.panel.Panel`) with parameter passed from the endpoint. Then a custom method `myMethod` will be called with no parameters.
297
215
 
298
- For more details on client-server communication see [Netzke::Core::Services]("http://rdoc.info/github/netzke/netzke-core/Netzke/Core/Services").
216
+ For more details on client-server communication see [Netzke::Core::Services]("http://www.rubydoc.info/github/netzke/netzke-core/Netzke/Core/Services").
299
217
 
300
218
  ## Icons support
301
219
 
@@ -311,17 +229,33 @@ end
311
229
 
312
230
  The logout action will be configured with `public/assets/icons/door.png` as icon.
313
231
 
314
- For more details on using icons refer to [Netzke::Core::Actions]("http://rdoc.info/github/netzke/netzke-core/Netzke/Core/Actions").
232
+ For more details on using icons refer to [Netzke::Core::Actions]("http://www.rubydoc.info/github/netzke/netzke-core/Netzke/Core/Actions").
315
233
 
316
234
  ## I18n
317
235
 
318
236
  Netzke Core will automatically include Ext JS localization files based on current `I18n.locale`.
319
237
 
320
- Also, Netzke Core uses some conventions for localizing actions. Refer to [Netzke::Core::Actions](http://rdoc.info/github/netzke/netzke-core/Netzke/Core/Actions).
238
+ Also, Netzke Core uses some conventions for localizing actions. Refer to [Netzke::Core::Actions](http://www.rubydoc.info/github/netzke/netzke-core/Netzke/Core/Actions).
239
+
240
+ ## Routing
241
+
242
+ Any Netzke component can react on a specific hash-route in the URL, which can be achieved by specifying `netzkeRoutes`
243
+ hash on the client class, similarly to how Ext JS handles routes in its controllers:
321
244
 
322
- ## HAML support (experimental)
245
+ // e.g. in my_component/client/my_component.js
246
+ {
247
+ netzkeRoutes: {
248
+ 'users': 'onUsers',
249
+ 'users/:id': 'onUser'
250
+ },
323
251
 
324
- Netzke provides support for HAML templates in case you don't want to put HTML into Ruby files.
252
+ onUsers: function() {},
253
+
254
+ onUser: function(userId) {},
255
+ }
256
+
257
+ If a component gets loaded dynamically and it figures out that one of its routes is currently active, it'll trigger the
258
+ corresponding handler after being rendered.
325
259
 
326
260
  ## Requirements
327
261
 
@@ -374,10 +308,8 @@ If you feel particularily generous, you can support the author by donating a cou
374
308
  ## Useful links
375
309
 
376
310
  * [Project website](http://netzke.org)
377
- * [Live demo](http://netzke-demo.herokuapp.com) (features [Netzke Basepack](https://github.com/netzke/netzke-basepack), with sample code)
311
+ * [Live demo](http://demo.netzke.org) (features [Netzke Basepack](https://github.com/netzke/netzke-basepack), with sample code)
378
312
  * [Twitter](http://twitter.com/netzke) - latest news about the framework
379
313
 
380
314
  ---
381
- © 2008-2015 [Max Gorin](https://twitter.com/mxgrn), released under the MIT license (see LICENSE).
382
-
383
- **Note** that Ext JS is licensed [differently](http://www.sencha.com/products/extjs/license/), and you may need to purchase a commercial license in order to use it in your projects!
315
+ Copyright (c) 2009-2015 [Good Bit Labs](http://goodbitlabs.com/), released under the GPLv3 license