Project

General

Profile

Hacking Workbench » History » Version 13

Tom Clegg, 09/17/2014 06:23 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 12 Tom Clegg
h2. Background resources
18
19
Workbench is a Rails 4 application.
20
21
* "Getting started with Rails":http://guides.rubyonrails.org/getting_started.html at rubyonrails.org
22
* "AJAX in Rails 3.1":http://blog.madebydna.com/all/code/2011/12/05/ajax-in-rails-3.html blog post (still relevant in Rails 4)
23
24 1 Tom Clegg
h2. Unlike a typical Rails project...
25
26 7 Peter Amstutz
* ActiveRecord in Workbench doesn't talk to the database directly, but instead queries the Arvados API as REST client.
27
* The Arvados query API is somewhat limited and doesn't accept SQL statements, so Workbench has to work harder to get what it needs.
28 1 Tom Clegg
* Workbench itself only has the privileges of the Workbench user: when making Arvados API calls, it uses the API token provided by the user.
29
30
h2. Unlike what you might expect...
31
32
* Workbench doesn't use the Ruby SDK. It uses a sort of baked-in Rails SDK.
33
** TODO: move it out of Workbench into a gem.
34
** TODO: use the Ruby SDK under the hood.
35
36
h2. Running in development mode
37
38 2 Misha Zatsman
h3. SSL certificates
39
40 4 Tom Clegg
You can get started quickly with SSL by generating a self-signed certificate:
41 1 Tom Clegg
42
 openssl req -new -x509 -nodes -out ~/self-signed.pem -keyout ~/self-signed.key -days 3650 -subj '/CN=arvados.example.com'
43
44
Alternatively, download a set from the bottom of the [[API server]] page.
45 2 Misha Zatsman
46
h3. Download and configure
47 1 Tom Clegg
48 2 Misha Zatsman
Follow "these instructions":http://doc.arvados.org/install/install-workbench-app.html to download the source and configure your workbench instance.
49 3 Misha Zatsman
50 4 Tom Clegg
h3. Start the server
51 1 Tom Clegg
52 4 Tom Clegg
Save something like the following at @~/bin/workbench@, make it executable[1], make sure @~/bin@ is in your path[2]:
53 1 Tom Clegg
54
 #!/bin/sh
55
set -e
56
cd ~/arvados/apps/workbench
57
export RAILS_ENV=development
58 5 Tom Clegg
bundle install --path=vendor/bundle
59 4 Tom Clegg
exec bundle exec passenger start -p 3031 --ssl --ssl-certificate ~/self-signed.pem --ssl-certificate-key ~/self-signed.key
60 1 Tom Clegg
61
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
62
63
Once you see:
64
65
 =============== Phusion Passenger Standalone web server started ===============
66
67
You can visit your server at:
68
69 4 Tom Clegg
 @https://{ip-or-host}:3031/@
70
71 6 Misha Zatsman
You can kill your server with @ctrl-C@ but if you get disconnected from the terminal, it will continue running. You can kill it by running
72
73
 @ps x |grep nginx |grep master@
74
75
And then
76
77
 @kill ####@
78
79
Replacing #### with the number in the left column returned by ps
80
81 4 Tom Clegg
fn1. @chmod +x ~/bin/workbench@
82
83
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.
84
85
h2. Running tests
86
87
The test suite brings up an API server in test mode, and runs browser tests with Firefox.
88
89
Make sure API server has its dependencies in place.
90
91
<pre>
92 5 Tom Clegg
(cd ../../services/api && RAILS_ENV=test bundle install --path=vendor/bundle)
93 4 Tom Clegg
</pre>
94
95
Install headless testing tools.
96
97
<pre>
98
sudo apt-get install xvfb iceweasel
99
</pre>
100
101
(Install firefox instead of iceweasel if you're not using Debian.)
102
103 10 Tom Clegg
Install phantomjs. (See http://phantomjs.org/download.html for latest version.)
104
105
<pre>
106
wget -P /tmp https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2
107
sudo tar -C /usr/local -xjf /tmp/phantomjs-1.9.7-linux-x86_64.tar.bz2
108
sudo ln -s ../phantomjs-1.9.7-linux-x86_64/bin/phantomjs /usr/local/bin/
109
</pre>
110
111 4 Tom Clegg
Run the test suite.
112
113
<pre>
114
RAILS_ENV=test bundle exec rake test
115 1 Tom Clegg
</pre>
116 9 Tom Clegg
117 13 Tom Clegg
h3. When tests fail...
118
119
When an integration test fails (or skips) a screenshot is automatically saved in @arvados/apps/workbench/tmp/workbench-fail-1.png@, etc.
120
121
By default, @rake test@ just shows F when a test fails (and E when a test crashes) and doesn't tell you which tests had problems until the entire test suite is done. During development it makes more sense to use TESTOPTS=-v@. This reports after each test the test class and name, outcome, and elapsed time:
122
* <pre>
123
$ RAILS_ENV=test bundle exec rake test TESTOPTS=-v
124
[...]
125
ApplicationControllerTest#test_links_for_object = 0.10 s = .
126
[...]
127
CollectionsTest#test_combine_selected_collection_files_into_new_collection = 10.89 s = F
128
Saved ./tmp/workbench-fail-2.png
129
[...]
130
</pre>
131
132 9 Tom Clegg
133 1 Tom Clegg
h2. Loading state from API into models
134
135
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@:
136
137
<pre><code class="ruby">
138
  api_response = $arvados_api_client.api(...)
139
  private_reload api_response
140
</code></pre>
141
142
h2. Features
143
144
h3. Authentication
145
146
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.
147
148
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.)
149
150
h3. Default filter behavior
151
152
@before_filter :find_object_by_uuid@
153
154
* This is enabled by default, @except :index, :create@.
155
* 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.)
156
* If you define a collection method (where there's no point looking up an object with the :id supplied in the request), skip this.
157
158
<pre><code class="ruby">
159
  skip_before_filter :find_object_by_uuid, only: [:action_that_takes_no_uuid_param]
160
</code></pre>
161
162
h3. Error handling
163
164
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.)
165
166
In a controller you get there like this
167
168
<pre><code class="ruby">
169
  @errors = ['I could not achieve what you wanted.']
170
  render_error status: 500
171
</code></pre>
172
173
You can also do this, anywhere
174
175
<pre><code class="ruby">
176
  raise 'My spoon is too big.'
177
</code></pre>
178
179
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.
180
181
h2. Development patterns
182
183
h3. Add a model
184
185
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.
186
187
_(Need to fill in details here)_
188
# @rails generate model ....@
189
# Delete migration
190 8 Peter Amstutz
# Change base class to ArvadosBase
191
# @rails generate controller ...@ 
192 1 Tom Clegg
193
Model _attributes_, on the other hand, are populated automatically.
194
195
h3. Add a configuration knob
196
197
Same situation as API server. See [[Hacking API Server]].
198
199
h3. Add an API method
200
201
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.
202
203
h3. Writing tests
204
205
(TODO)
206
207
h3. AJAX using Rails UJS (remote:true with JavaScript response)
208
209
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.
210
211
# 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@:
212
<pre><code class="ruby">
213
<%= link_to "Blurfl", blurfl_fizz_buzz_url(id: @object.uuid), {class: 'btn btn-primary', remote: true} %>
214
</code></pre>
215
# Ensure the targeted action responds appropriately to both "js" and "html" requests. At minimum:
216
<pre><code class="ruby">
217
class FizzBuzzesController
218
  #...
219
  def blurfl
220
    @howmany = 1
221
    #...
222
    respond_to do |format|
223
      format.js
224
      format.html
225
    end
226
  end
227
end
228
</code></pre>
229
# The @html@ view is used if this is a normal page load (presumably this means the client has turned off JS).
230
#* @app/views/fizz_buzz/blurfl.html.erb@
231
<pre><code>
232
<p>I am <%= @howmany %></p>
233
</code></pre>
234
# 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@:
235
<pre><code class="javascript">
236
window.alert('I am <%= @howmany %>');
237
</code></pre>
238
# The browser opens an alert box:
239
<pre>
240
I am 1
241
</pre>
242
# 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@:
243
<pre><code class="javascript">
244
var new_content = "<%= escape_javascript(render partial: 'latest_news') %>";
245
if ($('div#latest-news').html() != new_content)
246
   $('div#latest-news').html(new_content);
247
</code></pre>
248
249
*TODO: error handling*
250
251
h3. AJAX invoked from custom JavaScript (JSON response)
252
253
(and error handling)
254
255
h3. Add JavaScript triggers and fancy behavior
256
257
Some guidelines for implementing stuff nicely in JavaScript:
258
* Don't rely on the DOM being loaded before your script is loaded.
259
** 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".
260
** jQuery's delegated event pattern can help keep your code clean. See http://api.jquery.com/on/
261
<pre><code class="javascript">
262
// worse:
263
$('table.fizzbuzzer tr').
264
    on('mouseover', function(e, xhr) {
265
        console.log("This only works if the table exists when this setup script is executed.");
266
    });
267
// better:
268
$(document).
269
    on('mouseover', 'table.fizzbuzzer tr', function(e, xhr) {
270
        console.log("This works even if the table appears (or has the fizzbuzzer class added) later.");
271
    });
272
</code></pre>
273
274
* If your code really only makes sense for a particular view, rather than embedding @<script>@ tags in the middle of the page,
275
** use this:
276
<pre><code class="ruby">
277
<% content_for :js do %>
278
console.log("hurray, this goes in HEAD");
279
<% end %>
280
</code></pre>
281
** or, if your code should run after [most of] the DOM is loaded:
282
<pre><code class="ruby">
283
<% content_for :footer_js do %>
284
console.log("hurray, this runs at the bottom of the BODY element in the default layout.");
285
<% end %>
286
</code></pre>
287
288
* 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.
289
** In @app/views/fizz_buzzes/blurfl.html.erb@
290
<pre>
291
<table class="fizzbuzzer">
292
 <tr>
293
  <td>fizz</td><td>buzz</td>
294
 </tr>
295
</table>
296
</pre>
297
** In @app/assets/javascripts/fizz_buzzes.js@
298
<pre><code class="javascript">
299
<% content_for :js do %>
300
$(document).on('mouseover', 'table.fizzbuzzer tr', function() {
301
    console.log('buzz');
302
});
303
<% end %>
304
</code></pre>
305
** Advantage: You can reuse the special behavior in other tables/pages/classes
306
** Advantage: The JavaScript can get compiled, minified, cached in the browser, etc., instead of being rendered with every page view
307
** Advantage: The JavaScript code is available regardless of how the content got into the DOM (regular page view, partial update with AJAX)
308
309 11 Tom Clegg
h3. Invoking chooser
310
311
Example from @app/views/projects/_show_contents.html.erb@:
312
313
<pre>
314
    <%= link_to(
315
          choose_collections_path(
316
            title: 'Add data to project:',
317
            multiple: true,
318
            action_name: 'Add',
319
            action_href: actions_path(id: @object.uuid),
320
            action_method: 'post',
321
            action_data: {selection_param: 'selection[]', copy_selections_into_project: @object.uuid, success: 'page-refresh'}.to_json),
322
          { class: "btn btn-primary btn-sm", remote: true, method: 'get', data: {'event-after-select' => 'page-refresh'} }) do %>
323
      <i class="fa fa-fw fa-plus"></i> Add data...
324
    <% end %>
325
</pre>
326
327
Tour:
328 1 Tom Clegg
329
(TODO)
330
331
h3. Tabs/panes on index & show pages
332
333
(TODO)
334
335
h3. User notifications
336
337
(TODO)
338
339
h3. Customizing breadcrumbs
340
341
(TODO)
342
343
h3. Making a page accessible before login
344
345
(TODO)
346
347
h3. Making a page accessible to non-active users
348
349
(TODO)