Project

General

Profile

Hacking Workbench » History » Version 5

Tom Clegg, 04/18/2014 06:11 PM

1 1 Tom Clegg
h1. Hacking Workbench
2
3
{{toc}}
4
5
h2. Source tree layout
6
7
Everything is in @/apps/workbench@.
8
9
Key pieces to know about before going much further:
10
11
|/|Usual Rails project layout|
12
|/app/controllers/application_controller.rb|Controller superclass with authentication setup, error handling, and generic CRUD actions|
13
|/app/controllers/*.rb|Actions other than generic CRUD (users#activity, jobs#generate_provenance, ...)|
14
|/app/models/arvados_base.rb|Default Arvados model behavior and ActiveRecord-like accessors and introspection features|
15
|/app/models/arvados_resource_list.rb|ActiveRelation-like class (what you get from Model.where() etc.)|
16
17
h2. Unlike a typical Rails project...
18
19
* Most responses are JSON. Very few HTML views. We don't normally talk to browsers, except during authentication.
20
* We assign UUID strings (see lib/assign_uuid.rb and app/models/arvados_model.rb)
21
* The Arvados query API is fairly limited and doesn't accept SQL statements, so Workbench has to work harder to get what it needs. (Things will improve when Arvados accepts SPARQL queries.)
22
* Workbench itself only has the privileges of the Workbench user: when making Arvados API calls, it uses the API token provided by the user.
23
24
h2. Unlike what you might expect...
25
26
* Workbench doesn't use the Ruby SDK. It uses a sort of baked-in Rails SDK.
27
** TODO: move it out of Workbench into a gem.
28
** TODO: use the Ruby SDK under the hood.
29
30
h2. Running in development mode
31
32 2 Misha Zatsman
h3. SSL certificates
33
34 4 Tom Clegg
You can get started quickly with SSL by generating a self-signed certificate:
35 1 Tom Clegg
36
 openssl req -new -x509 -nodes -out ~/self-signed.pem -keyout ~/self-signed.key -days 3650 -subj '/CN=arvados.example.com'
37
38
Alternatively, download a set from the bottom of the [[API server]] page.
39 2 Misha Zatsman
40
h3. Download and configure
41 1 Tom Clegg
42 2 Misha Zatsman
Follow "these instructions":http://doc.arvados.org/install/install-workbench-app.html to download the source and configure your workbench instance.
43 3 Misha Zatsman
44 4 Tom Clegg
h3. Start the server
45 1 Tom Clegg
46 4 Tom Clegg
Save something like the following at @~/bin/workbench@, make it executable[1], make sure @~/bin@ is in your path[2]:
47 1 Tom Clegg
48
 #!/bin/sh
49
set -e
50
cd ~/arvados/apps/workbench
51
export RAILS_ENV=development
52 5 Tom Clegg
bundle install --path=vendor/bundle
53 4 Tom Clegg
exec bundle exec passenger start -p 3031 --ssl --ssl-certificate ~/self-signed.pem --ssl-certificate-key ~/self-signed.key
54 1 Tom Clegg
55
The first time you run the above it will take a while to install all the ruby gems. In particular @Installing nokogiri@ takes a while
56
57
Once you see:
58
59
 =============== Phusion Passenger Standalone web server started ===============
60
61
You can visit your server at:
62
63 4 Tom Clegg
 @https://{ip-or-host}:3031/@
64
65
fn1. @chmod +x ~/bin/workbench@
66
67
fn2. In Debian systems, the default .profile adds ~/bin to your path, but only if it exists when you log in. If you just created ~/bin, doing @exec bash -login@ or @source .profile@ should make ~/bin appear in your path.
68
69
h2. Running tests
70
71
The test suite brings up an API server in test mode, and runs browser tests with Firefox.
72
73
Make sure API server has its dependencies in place.
74
75
<pre>
76 5 Tom Clegg
(cd ../../services/api && RAILS_ENV=test bundle install --path=vendor/bundle)
77 4 Tom Clegg
</pre>
78
79
Install headless testing tools.
80
81
<pre>
82
sudo apt-get install xvfb iceweasel
83
</pre>
84
85
(Install firefox instead of iceweasel if you're not using Debian.)
86
87
Run the test suite.
88
89
<pre>
90
RAILS_ENV=test bundle exec rake test
91
</pre>
92 1 Tom Clegg
93
h2. Loading state from API into models
94
95
If your model makes an API call that returns the new state of an object, load the new attributes into the local model with @private_reload@:
96
97
<pre><code class="ruby">
98
  api_response = $arvados_api_client.api(...)
99
  private_reload api_response
100
</code></pre>
101
102
h2. Features
103
104
h3. Authentication
105
106
ApplicationController uses an around_filter to make sure the user is logged in, redirect to Arvados to complete the login procedure if not, and store the user's API token in Thread.current[:arvados_api_token] if so.
107
108
The @current_user@ helper returns User.current if the user is logged in, otherwise nil. (Generally, only special pages like "welcome" and "error" get displayed to users who aren't logged in.)
109
110
h3. Default filter behavior
111
112
@before_filter :find_object_by_uuid@
113
114
* This is enabled by default, @except :index, :create@.
115
* It renames the @:id@ param to @:uuid@. (The Rails default routing rules use @:id@ to accept params in path components, but @params[:uuid]@ makes more sense everywhere else in our code.)
116
* If you define a collection method (where there's no point looking up an object with the :id supplied in the request), skip this.
117
118
<pre><code class="ruby">
119
  skip_before_filter :find_object_by_uuid, only: [:action_that_takes_no_uuid_param]
120
</code></pre>
121
122
h3. Error handling
123
124
ApplicationController has a render_error method that shows a standard error page. (It's not very good, but it's better than a default Rails stack trace.)
125
126
In a controller you get there like this
127
128
<pre><code class="ruby">
129
  @errors = ['I could not achieve what you wanted.']
130
  render_error status: 500
131
</code></pre>
132
133
You can also do this, anywhere
134
135
<pre><code class="ruby">
136
  raise 'My spoon is too big.'
137
</code></pre>
138
139
The @render_error@ method sends JSON or HTML to the client according to the Accept header in the request (it sends JSON if JavaScript was requested), so reasonable things happen whether or not the request is AJAX.
140
141
h2. Development patterns
142
143
h3. Add a model
144
145
Currently, when the API provides a new model, we need to generate a corresponding model in Workbench: it's not smart enough to pick up the list of models from the API server's discovery document.
146
147
_(Need to fill in details here)_
148
# @rails generate model ....@
149
# Delete migration
150
# Change base class
151
# (probably more steps to fill in here)
152
153
Model _attributes_, on the other hand, are populated automatically.
154
155
h3. Add a configuration knob
156
157
Same situation as API server. See [[Hacking API Server]].
158
159
h3. Add an API method
160
161
Workbench is not yet smart enough to look in the discovery document for supported API methods. You need to add a method to the appropriate model class before you can use it in the Workbench app.
162
163
h3. Writing tests
164
165
(TODO)
166
167
h3. AJAX using Rails UJS (remote:true with JavaScript response)
168
169
This pattern is the best way to make a button/link that invokes an asynchronous action on the Workbench server side, i.e., before/without navigating away from the current page.
170
171
# Add <code class="ruby">remote: true</code> to a link or button. This makes Rails put a <code class="html">data-remote="true"</code> attribute in the HTML element. Say, in @app/views/fizz_buzzes/index.html.erb@:
172
<pre><code class="ruby">
173
<%= link_to "Blurfl", blurfl_fizz_buzz_url(id: @object.uuid), {class: 'btn btn-primary', remote: true} %>
174
</code></pre>
175
# Ensure the targeted action responds appropriately to both "js" and "html" requests. At minimum:
176
<pre><code class="ruby">
177
class FizzBuzzesController
178
  #...
179
  def blurfl
180
    @howmany = 1
181
    #...
182
    respond_to do |format|
183
      format.js
184
      format.html
185
    end
186
  end
187
end
188
</code></pre>
189
# The @html@ view is used if this is a normal page load (presumably this means the client has turned off JS).
190
#* @app/views/fizz_buzz/blurfl.html.erb@
191
<pre><code>
192
<p>I am <%= @howmany %></p>
193
</code></pre>
194
# The @js@ view is used if this is an AJAX request. It renders as JavaScript code which will be executed in the browser. Say, in @app/views/fizz_buzz/blurfl.js.erb@:
195
<pre><code class="javascript">
196
window.alert('I am <%= @howmany %>');
197
</code></pre>
198
# The browser opens an alert box:
199
<pre>
200
I am 1
201
</pre>
202
# A common task is to render a partial and use it to update part of the page. Say the partial is in @app/views/fizz_buzz/_latest_news.html.erb@:
203
<pre><code class="javascript">
204
var new_content = "<%= escape_javascript(render partial: 'latest_news') %>";
205
if ($('div#latest-news').html() != new_content)
206
   $('div#latest-news').html(new_content);
207
</code></pre>
208
209
*TODO: error handling*
210
211
h3. AJAX invoked from custom JavaScript (JSON response)
212
213
(and error handling)
214
215
h3. Add JavaScript triggers and fancy behavior
216
217
Some guidelines for implementing stuff nicely in JavaScript:
218
* Don't rely on the DOM being loaded before your script is loaded.
219
** If you need to inspect/alter the DOM as soon as it's loaded, make a setup function that fires on "document ready" and "ajax:complete".
220
** jQuery's delegated event pattern can help keep your code clean. See http://api.jquery.com/on/
221
<pre><code class="javascript">
222
// worse:
223
$('table.fizzbuzzer tr').
224
    on('mouseover', function(e, xhr) {
225
        console.log("This only works if the table exists when this setup script is executed.");
226
    });
227
// better:
228
$(document).
229
    on('mouseover', 'table.fizzbuzzer tr', function(e, xhr) {
230
        console.log("This works even if the table appears (or has the fizzbuzzer class added) later.");
231
    });
232
</code></pre>
233
234
* If your code really only makes sense for a particular view, rather than embedding @<script>@ tags in the middle of the page,
235
** use this:
236
<pre><code class="ruby">
237
<% content_for :js do %>
238
console.log("hurray, this goes in HEAD");
239
<% end %>
240
</code></pre>
241
** or, if your code should run after [most of] the DOM is loaded:
242
<pre><code class="ruby">
243
<% content_for :footer_js do %>
244
console.log("hurray, this runs at the bottom of the BODY element in the default layout.");
245
<% end %>
246
</code></pre>
247
248
* Don't just write JavaScript on the @fizz_buzzes/blurfl@ page and rely on the fact that the only @table@ element on the page is the one you want to attach your special behavior to. Instead, add a class to the table, and use a jQuery selector to attach special behavior to it.
249
** In @app/views/fizz_buzzes/blurfl.html.erb@
250
<pre>
251
<table class="fizzbuzzer">
252
 <tr>
253
  <td>fizz</td><td>buzz</td>
254
 </tr>
255
</table>
256
</pre>
257
** In @app/assets/javascripts/fizz_buzzes.js@
258
<pre><code class="javascript">
259
<% content_for :js do %>
260
$(document).on('mouseover', 'table.fizzbuzzer tr', function() {
261
    console.log('buzz');
262
});
263
<% end %>
264
</code></pre>
265
** Advantage: You can reuse the special behavior in other tables/pages/classes
266
** Advantage: The JavaScript can get compiled, minified, cached in the browser, etc., instead of being rendered with every page view
267
** Advantage: The JavaScript code is available regardless of how the content got into the DOM (regular page view, partial update with AJAX)
268
269
h3. Invoking selected-things picker
270
271
(TODO)
272
273
h3. Tabs/panes on index & show pages
274
275
(TODO)
276
277
h3. User notifications
278
279
(TODO)
280
281
h3. Customizing breadcrumbs
282
283
(TODO)
284
285
h3. Making a page accessible before login
286
287
(TODO)
288
289
h3. Making a page accessible to non-active users
290
291
(TODO)