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

Kjetil Thuen's avatar
Kjetil Thuen committed
4
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
5

6
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
7
8
9
10

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

Kjetil Thuen's avatar
Kjetil Thuen committed
11
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
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

```
> 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
-----

Kjetil Thuen's avatar
Kjetil Thuen committed
29
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
30

Kjetil Thuen's avatar
Kjetil Thuen committed
31
To enrich a html list with the EntryInfo functionallity, call the plugin like any other jQuery plugin:
Kjetil Thuen's avatar
Kjetil Thuen committed
32
33

```
34
$("#my-list").listEntryInfo({parameters})
Kjetil Thuen's avatar
Kjetil Thuen committed
35
36
```

37
The parameters object is a javascript object containing several optional parameters to modify the behaviour of the plugin. They are:
Kjetil Thuen's avatar
Kjetil Thuen committed
38

39
 * `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
40
41
 
```
42
function(id, displayCallbackFunc){displayCallbackFunc("<p><strong>" + id + "</strong> selected.</p>");}                  
Kjetil Thuen's avatar
Kjetil Thuen committed
43
44
```
 
Kjetil Thuen's avatar
Kjetil Thuen committed
45
 * `selectedClass`: The class to append to the selected list element. For styling. The default value is "listEntryInfoSelected".
Kjetil Thuen's avatar
Kjetil Thuen committed
46

47
 * `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
48

Kjetil Thuen's avatar
Kjetil Thuen committed
49
 * `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
50
51
52

 * `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
53
54
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
55
See the file `example.html` for example usage.