Fancy list manager
This plugin implements an interactive list manager. A "Listy" is a collection of text or links that can be
maintained easily using modal dialogs, dragged and dropped to sort or move around between multiple listies.
There are a couple of ways to use a Listy:
- as a customizable sidebar navigation
- as a list of links on a frontpage
- as a kanban-like task manager
All of these use cases have in common that you may freely interact with items on a listy.
Technically speaking, a listy is stored as
MetaData attached to a topic. A listy is
made up of multiple entries of the form
%META:LISTY
to the same topic. Multiple independent listies can
be stored on a single topic by defining the "collection" identifier. Also, multiple independent listies of the
same collection can be stored in separate topics.
Usage
Create a Listy
Just type
%LISTY%
anywhere on a topic to get started. Data will be stored into the current topic.
My Links
To store "My Links" of the currently logged in user, use:
%LISTY{
"mylinks"
topic="%WIKIUSERNAME%"
}%
This will store the set of links organized by this widget into the user's profile page and have them in a "mylinks" collection.
The
%FAVBUTTON
macro lets add a topic to a listy. By default it adds the current topic to your "mylinks" collections (see above):
%FAVBUTTON%
Note that any "mylinks" listy on the same page will automatically be updated as you click on the favbutton. Clicking on it again
will remove it from the listy again.
Scrum Board
(with the help of
GridLayoutPlugin)
%BEGINGRID{border="on"}%
%BEGINCOL{"4"}%
---++ Todo
%LISTY{
"todo"
collections="todo, inprogress, done"
}%
%BEGINCOL{"4"}%
---++ In progress
%LISTY{
"inprogress"
collections="todo, inprogress, done"
}%
%BEGINCOL{"4"}%
---++ Done
%LISTY{
"done"
collections="todo, inprogress, done"
}%
%ENDGRID%
This will display three listies next to each
other, a "todo", an "inprogress" and a "done" listy. You will be able to create entries for each listy, assign them to one of the
collections and move them around using drag and drop.
Dynamic Listies
Listy entries may be generated based on a query over topics, for instance topics that have some kind of
TaskForm
attached to it:
| *Name* | *Type* | *Size* | *Values* | *Description* | *Attributes* | *Default* |
| Summary | text | 80 | | | | |
| Owner | text | 20 | | | | |
| Status | radio | 5 | created, todo, inprogress, done | | | created |
Tasks are created as part of a wiki application and them might be managed using a scrum board extending above example:
%BEGINGRID{gutter="1" border="off"}%
%BEGINCOL{"3"}%
---++ Backlog
%LISTY{"created"
collections="created, todo, inprogress, done"
type="query"
query="form='TaskForm' AND ! Status=~'\b(todo|inprogress|done)\b'"
collection_formfield="Status"
}%
%BEGINCOL{"3"}%
---++ Todo
%LISTY{
"todo"
collections="created, todo, inprogress, done"
type="query"
query="form='TaskForm' AND Status='\btodo\b'"
collection_formfield="Status"
}%
%BEGINCOL{"3"}%
---++ In progress
%LISTY{
"inprogress"
collections="created, todo, inprogress, done"
type="query"
query="form='TaskForm' AND Status='\binprogress\b'"
collection_formfield="Status"
}%
%BEGINCOL{"3"}%
---++ Done
%LISTY{
"done"
collections="created, todo, inprogress, done"
type="query"
query="form='TaskForm' AND Status='\bdone\b'"
collection_formfield="Status"
}%
%ENDGRID%
Note that each listy is of
type="query"
and thus prefilled by entries that refer to the found topics. The parameter
collection_formfield="Status"
then informs the listy
to alter the
Status
formfield of the related topic while an entry is dragged from one listy to the next.
A listy can be integrated in a wiki application specifying a customized formatting for each listy item. Below
renders each topic in a listy by displaying an image and part of its
DataForm.
(with the help of
ImagePlugin and
FlexFormPlugin and a custom DataForm for movies)
%LISTY{
type="topic"
width="500px"
buttons="both"
format="<div class='$class clearfix'>$tools
$percntIMAGE{\"$percntFORMFIELD{\"Image\"}$percnt\" size=\"100\" align=\"left\" type=\"plain\"}$percnt
<h3>
<span class='foswikiGrayText foswikiRight foswikiSmall'>#$index</span>
<a href='$url'>$title</a>
</h3>
<div class='foswikiGrayText'>
$percntRENDERFORDISPLAY{
fields=\"Rating, Release, AgeRating_i, Genre\"
format=\"$title: $value\"
separator=\"%BR%\"
hidenull=\"on\"
}$percnt
</div>
</div>"
}%
Syntax
LISTY
%LISTY{"<collection>" ...}%
Parameter |
Description |
Default |
topic |
location where all entries of this listy are stored |
%BASETOPIC% |
collection |
the collection ID, can be just any string; leave it empty to refer to the "default" collection |
<empty> |
collections |
list of known collections stored at topic ; this lets you move a listy item between collectiosn without having a drag'n drop |
|
collection_formfield |
name of a formfield to be altered when dragging topic listies among collections |
|
collection_value |
value to set a topic item's formfield to |
collection |
hidenull |
boolean flag to hide the listy when there are no items in it |
false |
showcollections |
boolean flag to show/hide the collections select box in the item editor |
true |
sort |
sort listies using the specified property; possible values are index , title , summary , date , topictitle |
index |
reverse |
boolean flag to reverse the sorting order as specified in sort |
off |
types |
specify types of listy items, possible values are topic , text , external |
topic, text, external |
autosave |
boolean flag to enable/disable saving changes automatically on every action; if switched off you will need to hit the "save" button to make any changes to the listy permanent; if switched on (default) any change will be stored immediately |
true |
format , topic_format , text_format , external_format |
format string of listy items; there are a number of variables to be used in the format (see below) |
defined in listyplugin.tmpl |
buttons |
specify where the UI buttons are located; possible values are top , bottom , both and off |
bottom |
width |
width of listy widget, e.g. =width="500px" |
|
class |
additional css class to be added to the listy widget |
|
query |
search query for topics to pre-fill a listy with items; this is either a normal QuerySearch or a query using Foswiki:Extensions/DBCachePlugin in case it is installed |
|
The parameters
format
,
topic_format
,
text_format
,
external_format
may use the following variables:
Name |
Description |
$class |
css class of a listy item |
$date |
date when the listy item was last changed |
$index |
index of listy item within collection |
$json |
listy item as a json object; this is used by the widget to interact with the backend |
$name |
name/id of this listy item |
$summary |
summary |
$title |
title text of listy item |
$tools |
expands to the tools to interact with a listy item |
$topic |
topic value of a "topic" listy item |
$type |
type of this item ("topic", "text" or "external") |
$url |
link url of listy item |
$web |
web value of a "topic" listy item |
There are a couple of additional variables that are used in the
listyplugin.tmpl
default strings:
Name |
Description |
$item |
inserts the listy item into the result |
$buttons |
button format |
$topbuttons |
buttons located at the top |
$bottombuttons |
buttons located at the bottom |
$sourceweb |
|
$sourcetopic |
|
$collection |
collection id |
$collectionformfield |
name of formfield managed by this listy |
$collectionvalue |
value set to a collection formfield if this listy receives a new item using drag& drop |
$showcollections |
true/false |
$types |
selected types of this listy |
$autosave |
true/false |
$count |
number of listy items |
$style |
extra css |
$class |
extra class |
$allcollections |
list of collections known by the current listy |
$listyID |
id of the current listy |
$tml |
url-escaped TML used to render this listy; this is used to re-render the widget after an update |
%FAVBUTTON{...}
Parameter |
Description |
Default |
"..." or source |
topic to be added to the listy |
current user's profile page |
web , topic |
topic to be added to the list |
current topic |
collection |
name of the listy collection to add the favorite to |
mylisty |
favtext |
button text to be displayed when the source topic has not been favorited yet |
Favorite |
favicon |
button icon |
fa-star-o |
favtitle |
button tooltip |
Add to favorites |
unfavtext |
button text to be displayed when the source topic has been favorited |
Unavorite |
unfavicon |
button icon |
fa-star |
unfavtitle |
button tooltip |
Remove from favorites |
class |
css class to be added to the button element |
|
style |
css styles to be added to the button element |
|
animate |
animation to be added to the button, see System.VarJQICON |
|
showlabel |
boolean flag to show/hide the button label |
on |
showicon |
boolean flag to show/hide the button icon |
on |
Example:
%FAVBUTTON{
showlabel="off"
favicon="fa-heart-o"
unfavicon="fa-heart"
class="foswikiLarge foswikiAlert"
}%
Importing standard ...LeftBar
A standard Foswiki installation using PatternSkin allows to store a custom sidebar for each user into a separate
...LeftBar
topic for each user.
These can be converted to a setup based on ListyPlugin that stores those links into personal
mylinks
using a REST handler of the ListyPlugin.
Use the following commandline:
cd <foswiki-directory>
./rest /ListyPlugin/importSideBar param=value ...
Parameter |
Description |
Default |
web |
user web to search for ...LeftBar topics |
Main |
suffix |
suffix of topics to search for |
LeftBar |
include |
regular expressions of topics to include in the conversion process |
|
exclude |
regular expressions of topics to prevent from being processed |
|
debug |
boolean flag to enable debug outout |
off |
verbose |
boolean flag to enable verbose progress output |
off |
target |
target web to store create listy entries |
Main |
collection |
collection name to store entries to |
mylinks |
Note that the conversion process tries to clean up as good as possible entries in the ...LeftBar topics. However, as this is a free-form
topic any kind of content may be found, only some of it may be converted into a listy.
Installation Instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.
Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button.
Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will
not show up in the
search results.
You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
If you have any problems, or if the extension isn't available in
configure
, then you can still install manually from the command-line. See
https://foswiki.org/Support/ManuallyInstallingExtensions for more help.
Dependencies
Name | Version | Description |
---|
Foswiki::Plugins::RenderPlugin | >=3.10 | Required. |
Foswiki::Plugins::JQueryPlugin | >=7.00 | Required. |
Foswiki::Plugins::FilterPlugin | >=4.00 | Required. |
Foswiki::Contrib::JsonRpcContrib | >=2.21 | Required. |
Foswiki::Plugins::ZonePlugin | >=3.1 | Required. required for Foswiki < 1.1 |
Foswiki::Plugins::TopicTitlePlugin | >1.00 | Required for Foswiki < 2.2 |
Change History
01 Jul 2019: |
fixes along the new tabpane api; recording author, modification date, create author and create date now |
29 Jan 2019: |
added %FAVBUTTON macro; added solr index handler to make individual listy entries searchable; depend on TopicTitlePlugin now |
02 Feb 2017: |
added sidebar importer that allows to convert a WikiUserLeftBar to a listy |
23 Jan 2017: |
new features: populate listies using a search query; change formfields of a topic behind a listy item drag&droping them between listies |
22 Sep 2015: |
first final relase |
31 Aug 2015: |
fourth beta release |
17 Jul 2015: |
third beta release |
24 Jan 2014: |
renamed from BookmarksPlugin to ListyPlugin |