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.
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)
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:
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 ...
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
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.