README.md 3.91 KB
Newer Older
Kjetil Thuen's avatar
Kjetil Thuen committed
1
2
3
ListEntryInfo
=============

4
5
6
7
This is a jQuery plugin that will place a fixed "sight scope" over a given html
list, and present further information (or perform some other action) on whatever
list element is currently under the sight scope. The plugin will scroll the page
so that one element is always positioned perfectly within the sight scope.
Kjetil Thuen's avatar
Kjetil Thuen committed
8

9
10
11
12
13
The plugin will add one or two DOM elements after your list. The first acts as
the sight scope, and will always be added. It will initially be positioned over
the first list entry. The other one is an element that holds the expanded
information relating to the selected list element. The second will only be added
to the DOM if its not already present.
Kjetil Thuen's avatar
Kjetil Thuen committed
14
15
16
17

Installation
------------

18
19
20
If you want to build the ListEntryInfo plugin yourself, you need
[npm](https://npmjs.org) and [Grunt](http://gruntjs.com).  Assuming npm is
installed, first install Grunt and dependencies like this:
Kjetil Thuen's avatar
Kjetil Thuen committed
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

```
> npm install grunt-cli -g
> npm install
```

Then you can build the package like this:

```
> grunt build
```

The package will be in the `dist` directory which you can copy to your app.

Usage
-----

38
39
40
41
ListEntryInfo can be included in your project using Bower by mentioning [The
ListEntryInfo git
repo](https://prosjekt.nsd.uib.no/gitlab/kjetil/listentryinfoplugin.git) in your
`bower.json` file.
Kjetil Thuen's avatar
Kjetil Thuen committed
42

43
44
To enrich a html list with the EntryInfo functionallity, call the plugin like
any other jQuery plugin:
Kjetil Thuen's avatar
Kjetil Thuen committed
45
46

```
47
$("#my-list").listEntryInfo({parameters})
Kjetil Thuen's avatar
Kjetil Thuen committed
48
49
```

50
51
52
53
54
55
56
57
58
59
60
The parameters object is a javascript object containing several optional
parameters to modify the behaviour of the plugin. All the parameters can be
functions or static values. They are:

 * `extendedInfoFunc`: The function to be called when a list entry has focus.
 The function should take a DOM id, build some html and then somehow manipulate
 the DOM. For convenience, a function that populates the revealDiv with a given
 string and then slides it into view is passed as the second argument. If you do
 not want to alter the DOM yourself, you need to call this function with the
 html snippet you want displayed. The default function just puts the given id
 into the DOM element:
Kjetil Thuen's avatar
Kjetil Thuen committed
61
62

```
63
function(id, displayCallbackFunc){displayCallbackFunc("<p><strong>" + id + "</strong> selected.</p>");}
Kjetil Thuen's avatar
Kjetil Thuen committed
64
65
```

66
67
68
69
70
71
 * `selectedClass`: The class to append to the selected list element. For
 styling. The default value is "listEntryInfoSelected".

 * `sightScopeId`: The DOM id of the scope area. The element must be created by
 the plugin. If an element with the given id already exists, the plugin
 initialisation will fail silently. The default value is "listSightScope".
Kjetil Thuen's avatar
Kjetil Thuen committed
72

73
74
75
76
77
78
 * `itemInfoDivId`: The DOM id of the div holding the extended info. The element
 will be created if it does not already exist. If you use your own element you
 can place it wherever you want. If the plugin determines that it needs to
 create the element, it will create a DIV right after the target area. The
 element will be hidden and shown depending on whether a list element is focused
 or not. The default value is "selectedEntryItemInfo".
Kjetil Thuen's avatar
Kjetil Thuen committed
79

80
81
 * `timeout`: How long to wait after scrolling has stopped before calling the
 callback function. In milliseconds. Default value is 100.
Kjetil Thuen's avatar
Kjetil Thuen committed
82

83
84
85
86
87
88
89
90
91
 * `rememberLastSelected`: Whether the plugin should store the last selected
 listentry in session storage (requires html5 compliant browser). If the plugin
 is reinitialized at a later point, it will automatically scroll the stored
 listentry into the sight scope. Set to false by default.

 * `initialElement`: The id of an element to initially select. If the
 initalelement value is set, but no list element is found with the given id, the
 first element of the list will be selected. The default value is undefined.

92
93
94
Both the sight scope and "further information" area are divs that can be styled
from your own CSS. Their default ids are "listSightScope" and
"selectedEntryItemInfoInfo", but both of these can be overridden.
Kjetil Thuen's avatar
Kjetil Thuen committed
95

Kjetil Thuen's avatar
Kjetil Thuen committed
96
See the file `example.html` for example usage.