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.

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

NameVersionDescription
Foswiki::Plugins::RenderPlugin>=3.10Required.
Foswiki::Plugins::JQueryPlugin>=7.00Required.
Foswiki::Plugins::FilterPlugin>=4.00Required.
Foswiki::Contrib::JsonRpcContrib>=2.21Required.
Foswiki::Plugins::ZonePlugin>=3.1Required. 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

PackageForm edit

Author Michael Daum
Version 2.00
Release 23 Jan 2017
Description Fancy list manager
Repository https://github.com/foswiki/ListyPlugin
Copyright © 2015-2017 Michael Daum http://michaeldaumconsulting.com
License GPL (Gnu General Public License)
Home https://foswiki.org/Extensions/ListyPlugin
Support Foswiki:Support/ListyPlugin
Topic revision: r1 - 23 Jan 2017, UnknownUser
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback