Log inRegister
You are here: System » ListyPlugin

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.

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  
querytype can be search, dbquery or solr; note dbquery will use DBCachePlugin if installed and solr will use SolrPlugin if installed or plain search otherwise; the query language will vary depending on the query type

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
autosubscribe boolean flag to automatically subscribe/unsubscribe to a topic if it is fav'ed %LISTY_AUTOSUBSCRIBE{default="off"}%

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

NameVersionDescription
Foswiki::Plugins::RenderPlugin>=7.00Required
Foswiki::Plugins::JQueryPlugin>=7.00Required
Foswiki::Plugins::FilterPlugin>=4.00Required
Foswiki::Contrib::JsonRpcContrib>=2.21Required
Foswiki::Plugins::ZonePlugin>=3.1Required for Foswiki < 1.1
Foswiki::Plugins::TopicTitlePlugin>1.00Required for Foswiki < 2.2

Change History

31 Jan 2024: added autosubscribe to %FAVBUTTON
19 Oct 2023: made js and css a proper jQuery module
04 Sep 2023: added querytype parameter and support for SolrPlugin
22 Jun 2023: fixed reading the a topic title if the web property is empty
03 Jun 2022: fixed i18n for %FAVBUTTON macro
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