1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
It is critical that we describe filters using a consistent format. Every morsel of data provided in HTML is used by Javascript and CSS for context-specific behaviours and styles.
We need to support static HTML output with or without CSS, and with or without Javascript. So, don't expect it to be entirely elegant, but it works!
For brevity, this document uses standard CSS selectors to refer to elements. For example, #elemid refers to an element's ID attribute and .elemclass refers to a class attribute.
----- General overview -----
Here I will define the expected DOM hierarchy to be described in HTML and what it all means.
#container - Contains everything. This is important for CSS, to align the footer correctly.
#header - The top part of the page, consistent and visible on most pages.
span#pagetitle - The title, which is drawn as the leftmost part of the header with a special font.
img#sitelogo - Logo for the web site.
h1#sitename - The actual name of the site.
span#releasename - The name of the current release. Eg: Beta, Revision 201. Should be blank if it is a stable release. Printed as a subscript beside sitename.
span#userdata - Tools specific to logging in, or the logged in user.
#content - The portion of the page that changes specific to what is being looked at.
#filters - Contains the list of filters. Shows their current state and allows the user to interact with them, enabling / disabling filters and setting their values. Filters are explained in more detail later.
#results-pane - Container that holds results and surrounding widgets.
#results - Holds the list of packages that results from the selected filters.
#footer
#footnav - More technical links go in here...
#smallprint - The fine print. Contents are shrunken and ellipsized (where supported) to be really unobtrusive. When moused over, they are shown in more detail.
#copyright - Copyright notice.
#techdetails - Stuff geeks and Harvest hackers may want to know, like page generation time and SQL queries count.
-----Filters-----
A list of filters goes inside the element #filters. (These are probably FilterGroups, which contain more filters). A filter is described as follows:
<span class="filter editfilter pkgnamefilter" data-filter-fullname="filter-pkg:name">
The class is set to the actual Python class hierarchy of the Filter object in Django, with all Filter subclasses that influence its behaviour. The data-filter-fullname field is the full name of the Filter object in Django, as used in the querystring.
The immediate contents of each Filter object should be consistent:
.filter
.filter-label - The filter's label. This is its name, usually spanning a single line.
a.item-toggle - May not be present, but in most cases it is. See .filter.filtergroup .filter-value ul below for more information. Usually .item-toggle for a filter spans its entire .filter-label element.
.filter-value - (Optional) Contains a list, a text field or some other element corresponding to the value assigned to this filter, depending on its class.
Now I will describe the different .filter-value elements that are expected.
.filtergroup , .choicefilter
.filter-value ul - List items are all possible choices for the filter.
li - Needs the data-choice-id attribute, which specifies the exact ID of this choice relative to the current Filter. Add the data-selected attribute if this element is selected.
.checkbox - Must always be present. Contents indicate whether the element is selected. If it is currently selected, it must be populated with a check mark character (✓, U+2713, or ✓).
.choicefilter
ul > li > a.item-toggle - Expected to enable or disable the item. The href field should be a querystring that does this with static pages from Django, and Javascript will override that default behaviour.
.filtergroup
ul > li .filter > .filter-label > .item-toggle - Just like a.item-toggle with .choicefilter; just unfortunately placed for technical reasons.
.editfilter
.filter-value input - An HTML input field. Should not be attached to a form. For now, we are relying on Javascript to hande its value.
(##TODO##: require type="hidden" if Javascript dependency remains).
-----Standard Attributes-----
For .filter:
data-filter-fullname: Should be the full name of the filter, as it is in the querystring and in the FilterSystem in Django. (Eg: id="filter-pkg:set").
data-filter-value: The filter's value in serialized form. This attribute does not need to be filled initially, but our Javascript will fill it in as new values are generated.
For .filtergroup > ul > li and .choicefilter > ul > li:
data-item-name: The id of this item relative to the parent filter; not its full name. (Eg: data-item-name="netbook" for the choice with id_str="netbook").
data-selected: Add if the choice is currently selected.
|