← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/notes/apps/browser.txt

  • Committer: mattgiuca
  • Date: 2008-01-25 06:20:32 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:313
test/test_framework: Updated examples, a bit of better descriptions, sample
    partial solutions, etc.

Added all sample subject material.
This has been copied from test/test_framework and modified slightly.
There is now a subject "sample" with 2 worksheets. The 1st worksheet has 3
exercises. These work in IVLE by default.

setup.py: Added code to install subjects into the designated directory. This
means that installing IVLE will result in the sample subjects being
immediately available.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/notes/apps/browser.txt
 
1
IVLE File Browser Design
 
2
========================
 
3
 
 
4
    Author: Matt Giuca
 
5
    Date: 7/12/2007
 
6
 
 
7
This is the design for the file browser *and* editor components of IVLE.
 
8
 
 
9
They are now very closely integrated, sharing a common backend.
 
10
 
 
11
A prototype is available that I hacked up in Ajax/Python, available at
 
12
/trunk/prototypes/browser.
 
13
 
 
14
Separation of components
 
15
------------------------
 
16
 
 
17
The issue has arisen as to how we will separate components in terms of
 
18
distinct browser pages. (Will things be on separate server-prepared pages or
 
19
will the JavaScript manipulate the one page accordingly).
 
20
 
 
21
We have settled on a mid-way solution. Each component (ie. the file browser,
 
22
the text editor), will have a distinct browser page with its own HTML,
 
23
JavaScript code, etc.
 
24
 
 
25
The choice of how to split up pages within each component is up to that
 
26
component. Most components will use JavaScript so they will have just a single
 
27
page.
 
28
 
 
29
The file browser will be a single page which uses JavaScript internally to
 
30
navigate around. So clicking on subdirectories will not reload a new page, it
 
31
will just change the current page.
 
32
 
 
33
The editor will of course be just a single page.
 
34
 
 
35
Architecture
 
36
------------
 
37
 
 
38
The server side is shared between the file browser and editor. It is written
 
39
in Python and acts as basically a "shell" to the file system and subversion
 
40
workspace.
 
41
 
 
42
Essentially it takes input in the form of an HTTP Request (GET and POST
 
43
accordingly), and returns material primarily as [JSON](http://www.json.org)
 
44
data. JSON is extremely easy to write and read in both Python and JavaScript.
 
45
It is effectively the common subset of JavaScript and Python data.
 
46
 
 
47
For instance, the client may wish to perform an "ls" command. Since this has
 
48
no side-effects on the server, it sends an "ls" request using GET to pass the
 
49
path name. The server then returns a directory listing in JSON which might
 
50
look like this:
 
51
 
 
52
        [
 
53
            {"svnstatus": "unversioned", "isdir": true, "size": 4096,
 
54
                "mtime": "Fri Dec 7 16:27:54 2007", "filename": "subdir"},
 
55
            {"svnstatus": "normal", "isdir": false, "size": 22,
 
56
                "mtime": "Fri Dec 7 12:21:24 2007", "filename": "data"}
 
57
        ]
 
58
 
 
59
This nicely separates the client/server with the server being completely
 
60
independent of the interface and the client being able to make things happen
 
61
by calling simple commands via Ajax.
 
62
 
 
63
Browser Interface
 
64
-----------------
 
65
 
 
66
The interface is split into 4 main sections. These parallel a common file
 
67
browser paradigm. The interface is designed to be familiar to Windows
 
68
Explorer, etc, but adapted for the browser.
 
69
 
 
70
Along the top there is the location bar. This contains a clickable set of
 
71
links showing the current directory path.
 
72
 
 
73
The main part of the page is the file list. This is a HTML table consisting of
 
74
the following columns:
 
75
 
 
76
* Checkboxes, for file selection.
 
77
* Icon (tooltip: textual file type)
 
78
* SVN Status icon (tooltip: textual SVN status)
 
79
* Filename (hyperlink, tooltip if the filename had to be condensed)
 
80
* Size (natural units)
 
81
* Date modified (naturalised, tooltip: full date)
 
82
 
 
83
Column headers are all clickable for sorting. All sorting is handled on the
 
84
client side (note: the prototype does sorting on the server, this will
 
85
disappear).
 
86
 
 
87
We try to represent information rather compactly in the table view. Tooltips
 
88
and/or sidebar gives more information. This is why there are tooltips for
 
89
basically each column giving additional info.
 
90
 
 
91
SVN Status icons are a separate column from the main one but represent the
 
92
same as TortoiseSVN. For example, green ticks for "normal", red bangs for
 
93
"modified", etc.
 
94
 
 
95
Filenames are condensed in the middle (so you see a fixed number of chars at
 
96
the beginning and end. For instance "A very long file with a long name" is
 
97
condensed into "A very long...long name").
 
98
 
 
99
Dates are condensed according to a "naturalisation" algorithm. Files modified
 
100
today or yesterday show "today" or "yesterday" accordingly, and the time.
 
101
Files modified in the last 5 days show "3 days ago". Other files just show the
 
102
date. The tooltip always gives the full date and time.
 
103
 
 
104
Along the bottom is a status bar showing some static things about the current
 
105
directory.
 
106
 
 
107
The main feature of interest is the side panel, which shows information and
 
108
buttons about the selected file(s). Note that in the prototype we have buttons
 
109
in the file list, which is quite ugly and difficult to use. It is much more
 
110
natural to select the files, then act on them. See "side panel" later.
 
111
 
 
112
### File selection ###
 
113
 
 
114
There are always 0 or more files selected. Selection can be controlled
 
115
precisely by checking or unchecking the checkboxes on the side. Clicking a
 
116
file's name selects it and deselects all the others. If we can detect Ctrl and
 
117
Shift we can do better selection algorithms.
 
118
 
 
119
Graphically I am picturing the file list rows to be shaded as:
 
120
 
 
121
* Interlacing shades of grey for deselected files.
 
122
* Interlacing shades of blue for selected files.
 
123
* White for rows with the mouse hovering.
 
124
 
 
125
### Side panel ###
 
126
 
 
127
The side panel is a dynamic area which changes whenever the selections change.
 
128
It displays detailed information and actions pertaining to the
 
129
currently-selected file(s).
 
130
 
 
131
If only one file is selected, it displays all the details about that file (eg.
 
132
file size, full date and time, and the widest range of buttons).
 
133
 
 
134
The buttons are:
 
135
 
 
136
* For Python files: "Run in Browser" and "Run in Console".
 
137
* For HTML files, PDFs, images, even text files, any other content that web
 
138
  browsers natively recognise: "View in Browser" (or just "Open").
 
139
* For directories: "Open"
 
140
* Edit (perhaps only for non-binary files - is there any point in letting
 
141
  students open binary files in the text editor? This could just be confusing
 
142
  as students might expect to see an image editor, for example)
 
143
* Rename
 
144
 
 
145
If multiple files are selected, it just displays the number of files, and
 
146
their total size.
 
147
 
 
148
The following buttons are available no matter how many files are selected (at
 
149
least 1):
 
150
 
 
151
* Download
 
152
* Cut (see "copy-paste")
 
153
* Copy
 
154
 
 
155
Finally there are the Subversion buttons. These vary depending on not only the
 
156
files selected, but their SVN statuses.
 
157
 
 
158
If just one file is selected, you see the following buttons:
 
159
 
 
160
* "Add", if the file is unversioned.
 
161
* "Commit", if the file is added, modified, etc.
 
162
* "Check for updates", always.
 
163
 
 
164
There may be others such as log, diff, depending on how detailed we go into
 
165
SVN.
 
166
 
 
167
If multiple files are selected, the "add" and "commit" buttons are visible if
 
168
one or more files are applicable to that button. However, to prevent
 
169
misunderstandings, only one button is ever seen at any time (with "add" taking
 
170
precedence). This way, if the user selects modified AND unversioned files,
 
171
they may click "commit" thinking it will add the unversioned ones (it won't).
 
172
So they are forced to click "add" first, then "commit".
 
173
 
 
174
"Check for updates" and "Commit all" will be available from the top toolbar
 
175
which applies to the whole directory and its subdirectories.
 
176
 
 
177
#### Discussion: Add and commit combined? ####
 
178
 
 
179
We don't really need separate "add" and "commit". Because you can selectively
 
180
commit, we may just dumb it down to having "commit" available on unversioned
 
181
files, and it automatically adds. You just select all the files you want to
 
182
add and hit "commit", along with any other files you changed.
 
183
 
 
184
### Opening the editor ###
 
185
 
 
186
The editor is a separate page. If a file is to be edited, it tries to open it
 
187
in a new window. This should encourage students to use browser tabs.
 
188
 
 
189
Directory-wide actions
 
190
----------------------
 
191
 
 
192
Some actions can be performed on the entire directory. These should also
 
193
appear in the side-bar, but in a separate section. Or they could be in a
 
194
toolbar along the top. They are:
 
195
 
 
196
* Paste
 
197
* Upload file
 
198
* New file (opens the editor)
 
199
* Check for updates
 
200
* Commit all
 
201
 
 
202
Mime type detection and usage
 
203
-----------------------------
 
204
 
 
205
We can use Python's builtin mimetypes module to detect mime types of the
 
206
files. Python should send the mime types along with the listing info.
 
207
 
 
208
We use mime types for the following purposes:
 
209
 
 
210
* File type icons and descriptions (note: Need a mapping from mime type to
 
211
  friendly description, eg "text/python-src" to "Python source code").
 
212
* Image types have previews in the side panel.
 
213
* Determining other actions. eg. Python source can be executed. HTML source
 
214
  and PDF files can be viewed in the browser.
 
215
* Editor warnings for binary types (though this may be best if we warn based
 
216
  on whether it contains invalid unicode chars instead).
 
217
 
 
218
Copy-paste
 
219
----------
 
220
 
 
221
We will have a full cut-copy-paste paradigm just the same as how modern
 
222
desktop file browsers work. The "clipboard" will be stored just on the client
 
223
side, as a global JavaScript variable, so it is not shared across browser
 
224
sessions or windows. (*Should it be?*)
 
225
 
 
226
Quite simply, "copy" replaces the clipboard with a "copy" action associated
 
227
with the selected files. "cut" does the same but associates a "move" action.
 
228
(Also shades the cut files somehow differently). "paste" executes the copy or
 
229
move.
 
230
 
 
231
Discussion: Trash bin?
 
232
----------------------
 
233
 
 
234
Do we need a trash bin, given that we're using Subversion? Students should
 
235
realise that "temporary files" are just that - if you delete them, they're
 
236
gone. "Permanent files" can be recovered (but we should make that process less
 
237
painful than it is currently in Subversion).
 
238
 
 
239
Perhaps "novice mode" should have a trash bin but expert mode should rely on
 
240
Subversion? (Will the transition be jarring??)
 
241
 
 
242
Editor Interface
 
243
----------------
 
244
 
 
245
The editor page will be a modified version of EditArea (basically with a
 
246
modified toolbar).
 
247
 
 
248
It will interact with the server simply as it reads and writes files, and also
 
249
has limited Subversion access.
 
250
 
 
251
The four major features being added to EditArea are:
 
252
 
 
253
* Save. Saves the file to a location in the user's directory (prompting first
 
254
  if it doesn't yet exist). Also Save As. Very familiar.
 
255
* Save and Commit. Saves the file AND automatically SVN commits.
 
256
* Reload. Reloads the file from the student's directory.
 
257
* Check for updates. Does a SVN update of the file and loads it. (Is this a
 
258
  bad idea?)
 
259
 
 
260
Note that EditArea's existing "save" feature is actually going to make the
 
261
browser offer the file as a download. This will be renamed to "download".
 
262
 
 
263
Commit logs
 
264
-----------
 
265
 
 
266
All the commit features will prompt for a commit log (either a JS prompt() or
 
267
a nicer popup floating element). But the commit log is an optional feature
 
268
which is turned off by default. That is, by default a log message like "No log
 
269
message provided." is written to the log. Once students are more familiar with
 
270
SVN, they can turn on log messages to be prompted when they commit.
 
271
 
 
272
(Alternatively this feature may automatically come with the "advanced"
 
273
interface).