Commit a2e714f5 authored by Kjetil Thuen's avatar Kjetil Thuen

Added some documentation.

parent b2c089ef
ListEntryInfo
=============
This is a jQuery plugin that will place a "target-area" over a given html list,
and present further information (or perform some other action) on whatever list
element is currently under the target.
The target and "further information" area are both divs that should be styled
from your own CSS. Their default ids are "listPeakTargetArea" and
"listPeakRevealArea", but both of these can be overridden.
Installation
------------
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:
```
> 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
-----
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.
To enrich a html list with the EntryInfo functionallity, call the plugin like
any other jQuery plugin:
```
$("#my-list").listEntryInfo(arguments-object)
```
The arguments object is a javascript object containing several optional
arguments to modify the behaviour of the plugin. They are:
* `extendedInfoFunc`: The function to be called when a list entry has focus. The function should accept an DOM id as its argument and either directly manipulate the DOM or call some function that does so. For convenience, a function, `defaultPopulateRevealDivFunc` that populates the revealDiv with a given string and then slides it into view. The default function just puts the given id into the DOM element:
```
function(id){defaultPopulateRevealDivFunc("<strong>" + id + "</strong>");}
```
foo.
* `selectedClass`: The class to append to the selected list element. For styling. The default value is "listPeekSelected".
* `targetId`: The DOM id of the target area. The element must be created by the plugin. If and element with the given id already exists, the plugin initialisation will fail silently. The default value is "listPeekTargetArea".
* `revealDivId`: 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 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 "listPeekRevealArea".
* `timeout`: How long to wait after scrolling has stopped before calling the callback function. In milliseconds. Default value is 100.
See the file `example.html` for example usage.
...@@ -25,22 +25,25 @@ ...@@ -25,22 +25,25 @@
color: #eee; color: #eee;
} }
/*
#listPeekTargetArea and #listPeakRevealArea are the default ids for
the target and info divs. If needed, you can pass other ids in the
arguments object
*/
#listPeekTargetArea { #listPeekTargetArea {
background-color: rgba(0,0,0,1); background-color: rgba(0,0,0,1);
} }
#listPeakRevealArea { #listPeekRevealArea {
background-color: rgba(0,0,0,1); background-color: rgba(0,0,0,1);
padding: 0em 1em 1em 1em; padding: 0em 1em 1em 1em;
color: white; color: white;
max-height: 10em !important;
margin-bottom: 0.5em; margin-bottom: 0.5em;
overflow: auto; overflow: auto;
} }
</style> </style>
<script src="lib/jquery/jquery.js"></script> <script src="lib/jquery/jquery.js"></script>
<script src="dist/listentryinfo.min.js"></script> <script src="dist/listentryinfo.js"></script>
<script> <script>
var philosophers = [ var philosophers = [
"Abhinavagupta", "Abhinavagupta",
...@@ -169,38 +172,51 @@ ...@@ -169,38 +172,51 @@
"White Thomas" "White Thomas"
]; ];
var display_philosopher_article = function (name) { /*
$.getJSON("http://en.wikipedia.org/w/api.php?action=query&prop=extracts&format=json&exintro=1&callback=?", {titles:name}, function(data) { This function will be called with the id of the selected list
var article; element (name), and the default function for populating a DOM element with
the computed information (displayFunc).
*/
var display_philosopher_article = function (name, displayFunc) {
var article;
if (data && data.query && data.query.pages) { $.getJSON("http://en.wikipedia.org/w/api.php?action=query&prop=extracts&format=json&exintro=1&callback=?", {titles:name}, function(data) {
var pages = data.query.pages;
for (var id in pages) { if (data && data.query && data.query.pages) {
article = pages[id].extract; var pages = data.query.pages;
}
} else {
article="<p>No article found on " + name;
// error: No pages returned / other problems!
}
$("#listPeakRevealArea").html(article); console.log(article)}); for (var id in pages) {
} // There should be only one page, so we just overwrite if
// there is more
article = pages[id].extract;
}
} else {
article="<p>No article found on " + name + "</p>";
}
var build_philosopher_list = function () { displayFunc(article);
var philosopherList = $("#philosopherList"); });
philosophers.forEach(function (philosopher) { }
philosopherList.append("<li id='" + philosopher +"'>" + philosopher + "</li>");
});
}
$(document).ready(function() { /*
build_philosopher_list(); Populates the list with the phiosophers from the philosophers array defined above
$('#philosopherList').listEntryInfo({ */
extendedInfoFunc: display_philosopher_article var build_philosopher_list = function (philosopherlist) {
}); var philosopherListElem = $("#philosopherList");
}); philosopherlist.forEach(function (philosopher) {
philosopherListElem.append("<li id='" + philosopher +"'>" + philosopher + "</li>");
});
}
if (typeof $ === 'undefined') {
alert("Cannot find jQuery. Have you read the Readme?");
} else {
$(document).ready(function() {
build_philosopher_list(philosophers);
// Apply the plugin and pass it the callback to be called for selected elements
$('#philosopherList').listEntryInfo({ extendedInfoFunc: display_philosopher_article });
});
}
</script> </script>
</head> </head>
<body> <body>
...@@ -208,8 +224,8 @@ ...@@ -208,8 +224,8 @@
<h1>ListEntryInfo Demo</h1> <h1>ListEntryInfo Demo</h1>
<p> <p>
This demo displays a static list of philosophers of mind, and This demo displays a static list of philosophers of mind, and
fetches their articles from wikipedia when their list entry fetches their articles from Wikipedia when their list entry
has focus. gains focus.
</p> </p>
<ul id="philosopherList"></ul> <ul id="philosopherList"></ul>
</div> </div>
......
...@@ -42,7 +42,9 @@ module.exports = function(grunt) { ...@@ -42,7 +42,9 @@ module.exports = function(grunt) {
} }
} }
}, },
clean: ["dist", "lib"] clean: {
build: ["dist/*", "lib/*"]
}
}); });
// Load libs // Load libs
......
...@@ -15,13 +15,23 @@ ...@@ -15,13 +15,23 @@
settings = $.extend({ settings = $.extend({
selectedClass: "listPeekSelected", selectedClass: "listPeekSelected",
targetId: "listPeekTargetArea", targetId: "listPeekTargetArea",
revealDivId: "listPeakRevealArea", revealDivId: "listPeekRevealArea",
timeout: 100, timeout: 100,
backgroundColor: "white", extendedInfoFunc: function(id){defaultPopulateRevealDivFunc("<strong>" + id + "</strong>");}
extendedInfoFunc: function(id){ return "<strong>" + id + "</strong>";}
}, options ); }, options );
peekedList = this; peekedList = this;
if (typeof peekedList.position() !== 'object') {
console.log("Unable to find list element");
return;
}
if ($("#" + settings.targetId).length !== 0) {
console.log("Target element already exists");
return;
}
targetTop = peekedList.position().top; targetTop = peekedList.position().top;
$('<div></div>').attr('id', settings.targetId).css({ $('<div></div>').attr('id', settings.targetId).css({
...@@ -34,15 +44,17 @@ ...@@ -34,15 +44,17 @@
top: targetTop top: targetTop
}).insertAfter(peekedList); }).insertAfter(peekedList);
$('<div></div>').attr('id', settings.revealDivId).css({ if ($("#" + settings.revealDivId).length === 0) {
position: 'fixed', $('<div></div>').attr('id', settings.revealDivId).css({
width: '70%', position: 'fixed',
left: '15%', width: '70%',
'z-index': 2, left: '15%',
display: 'none', 'z-index': 2,
'max-height': '70%', display: 'none',
top: targetTop + $('#' + settings.targetId).height() 'max-height': '70%',
}).insertAfter(peekedList); top: targetTop + $('#' + settings.targetId).height()
}).insertAfter(peekedList);
}
horizontalCenter = Math.floor(window.innerWidth/2); horizontalCenter = Math.floor(window.innerWidth/2);
centerOfHeadline = $('#' + settings.targetId).offset().top - $(window).scrollTop() + ($('#' + settings.targetId).height() / 2); centerOfHeadline = $('#' + settings.targetId).offset().top - $(window).scrollTop() + ($('#' + settings.targetId).height() / 2);
...@@ -77,6 +89,15 @@ ...@@ -77,6 +89,15 @@
}; };
}; };
var defaultPopulateRevealDivFunc = function (content) {
if (content !== null) {
$('#' + settings.revealDivId).html(content);
$('#' + settings.revealDivId).slideDown('fast', function() {
scrollListenersEnabled = true;
});
}
};
var showExpandedInfo = function() { var showExpandedInfo = function() {
var listElem = peekedList.children("li." + settings.selectedClass), var listElem = peekedList.children("li." + settings.selectedClass),
details, details,
...@@ -98,16 +119,9 @@ ...@@ -98,16 +119,9 @@
$('body').animate({scrollTop: scrollVal}, 'fast'); $('body').animate({scrollTop: scrollVal}, 'fast');
details = settings.extendedInfoFunc(listElem.attr('id')); settings.extendedInfoFunc(listElem.attr('id'), defaultPopulateRevealDivFunc);
//listElem.find("div.abstract").html();
scrollInProgress = false; scrollInProgress = false;
if (details !== null) {
$('#' + settings.revealDivId).html(details);
$('#' + settings.revealDivId).slideDown('fast', function() {
scrollListenersEnabled = true;
});
}
}; };
var setSelectedElement = function (element, asap) { var setSelectedElement = function (element, asap) {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment