ListyPlugin

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

Simple

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.

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.

Custom formatting

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{"<collection>" ...}%

Parameter	Description	Default
topic		%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	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

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. Use "Find More Extensions" to get a list of available extensions. Select "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 http://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

Change History

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