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

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.

Favorites button

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.

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

%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
showtools	boolean flag to enable/disable the edit tools of a listy item	true
width	width of listy widget, e.g. =width="500px"
updatewidth	boolean flag to enable/disable remembering the initial minimum width when the listy was rendered	true
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
$params	json section holding all params that have been used to render this listy

FAVBUTTON

%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 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	>=7.00	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 for Foswiki < 1.1
Foswiki::Plugins::TopicTitlePlugin	>1.00	Required for Foswiki < 2.2

Change History

03 May 2022:	using tag REST handler of RenderPlugin now
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