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.
- data/CHANGELOG.md +65 -607
- data/Gemfile +1 -1
- data/LICENSE +2 -6
- data/README.md +77 -145
- data/javascripts/base.js +582 -96
- data/javascripts/core.js +62 -0
- data/javascripts/notifications.js +43 -0
- data/javascripts/remoting_provider.js +29 -0
- data/javascripts/routing.js +63 -0
- data/lib/netzke/base.rb +16 -83
- data/lib/netzke/core/action_config.rb +1 -5
- data/lib/netzke/core/actions.rb +59 -21
- data/lib/netzke/core/{client_class.rb → client_class_config.rb} +81 -73
- data/lib/netzke/core/client_code.rb +157 -0
- data/lib/netzke/core/component_config.rb +2 -2
- data/lib/netzke/core/composition.rb +85 -65
- data/lib/netzke/core/configuration.rb +26 -14
- data/lib/netzke/core/core_i18n.rb +17 -0
- data/lib/netzke/core/css_config.rb +6 -6
- data/lib/netzke/core/dynamic_assets.rb +17 -24
- data/lib/netzke/core/embedding.rb +2 -2
- data/lib/netzke/core/endpoint_response.rb +8 -2
- data/lib/netzke/core/inheritance.rb +33 -0
- data/lib/netzke/core/plugins.rb +1 -4
- data/lib/netzke/core/railz/action_view_ext.rb +1 -1
- data/lib/netzke/core/railz/controller_extensions.rb +21 -15
- data/lib/netzke/core/services.rb +61 -48
- data/lib/netzke/core/session.rb +0 -2
- data/lib/netzke/core/state.rb +11 -9
- data/lib/netzke/core/stylesheets.rb +3 -3
- data/lib/netzke/core/version.rb +1 -1
- data/lib/netzke/core.rb +3 -3
- data/lib/netzke/plugin.rb +2 -6
- data/stylesheets/core.css +2 -2
- metadata +11 -10
- data/TODO.md +0 -9
- data/javascripts/ext.js +0 -518
- data/lib/netzke/core/config_to_dsl_delegator.rb +0 -62
- data/lib/netzke/core/dsl_support.rb +0 -70
- data/lib/netzke/core/html.rb +0 -29
- data/lib/netzke/core/javascript.rb +0 -123
data/Gemfile
CHANGED
data/LICENSE
CHANGED
@@ -1,7 +1,3 @@
|
|
1
|
-
Copyright (c)
|
1
|
+
Copyright (c) 2009-2015 Good Bit Labs Limited
|
2
2
|
|
3
|
-
|
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 [![
|
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://
|
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
|
-
|
7
|
+
*Notes on versioning:*
|
8
8
|
|
9
|
-
|
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
|
-
|
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
|
-
|
32
|
+
client
|
133
33
|
some_dependency.js <-- optional external JS library
|
134
|
-
init_component.js <-- optional
|
135
|
-
extra_functionality.js <-- more
|
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
|
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.
|
51
|
+
Ext.define('Netzke.classes.HelloWorld', {"extend":"Ext.panel.Panel", "mixins":["Netzke.Base"]});
|
153
52
|
```
|
154
53
|
|
155
|
-
`Netzke.
|
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
|
-
|
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
|
-
|
73
|
+
client_class do |c|
|
175
74
|
c.extend = "Ext.tab.Panel"
|
176
|
-
c.
|
75
|
+
c.include :extra_functionality
|
177
76
|
end
|
178
77
|
end
|
179
78
|
```
|
180
79
|
|
181
|
-
|
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
|
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
|
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://
|
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
|
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://
|
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
|
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 :
|
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 `
|
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.
|
178
|
+
this.server.whatsUp(greeting, callback, scope);
|
275
179
|
```
|
276
180
|
|
277
|
-
|
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
|
-
|
280
|
-
|
281
|
-
|
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
|
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
|
290
|
-
|
291
|
-
|
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://
|
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://
|
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://
|
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
|
-
|
245
|
+
// e.g. in my_component/client/my_component.js
|
246
|
+
{
|
247
|
+
netzkeRoutes: {
|
248
|
+
'users': 'onUsers',
|
249
|
+
'users/:id': 'onUser'
|
250
|
+
},
|
323
251
|
|
324
|
-
|
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://
|
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
|
-
|
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
|