[[PageOutline(2-5,Contents,pullout)]]

= Sorting cards in stacks

== Description

This macro `[[Cards(...)]]` shows a whiteboard containing index cards organized in stacks. Adding new cards interactively by clicking a button, move cards by drag-and-drop and double-click cards for editing, changing color or deleting.

Cards are stored in a new table in the Trac database.

=== Example

The following code in the Trac wiki page:

`[[Cards(stack=todo|wip|done,label=To Do|Work in Progress|Done, width=800)]]`

will produce the following capabilities:

[[Image(cards-example-screenshot.png)]]

=== Collaboration support

* Edit conflicts are detected automatically.
* A refresh button allows manually reloading the cards at any time.
* The cards are automatically reloaded every ten seconds while they are in view.

=== Known Limitations

* There is no history or undo functionality.
* There is no tracking of users. Everyone with `CARDS_ADMIN` permission can freely edit any card.

=== Parameters

* `stack`: `|`-separated list of stack names. (Required)
* `label`: `|`-separated list of stack labels shown instead of the stack names. (Defaults to the stack names.)
* `width`: Width of the whiteboard. (Defaults to 400.)

See also: [[ListTagged(realm:wiki cards)]]

== !Bugs/Feature Requests

Existing bugs and feature requests for CardsPlugin are 
[report:9?COMPONENT=CardsPlugin here].

If you have any issues, create a 
[/newticket?component=CardsPlugin new ticket].

[[TicketQuery(component=CardsPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:cardsplugin here].

== Source

You can check out CardsPlugin from [/svn/cardsplugin here] using Subversion, or [source:cardsplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

 1. Install as follows:
    * Trac >=1.4: `$ easy_install https://trac-hacks.org/svn/cardsplugin/trunk`.
    * Trac >=1.2: `$ easy_install https://trac-hacks.org/svn/cardsplugin/tags/cardsplugin-1.3`.
    * Trac 1.0: `$ easy_install https://trac-hacks.org/svn/cardsplugin/tags/cardsplugin-1.2`.
 1. Enable the plugin in Trac's plugin admin page or in your `trac.ini` file:
   {{{#!ini
   [components]
   cards.* = enabled
   }}}
 1. Update database: `trac-admin path/to/trac/environment upgrade`.

== Configuration

Assign the `CARDS_ADMIN` permission to the users who need this plugin's functionality, for example in permission admin panel.

Optionally, some `trac.ini` options can be changed from the defaults:
{{{#!ini
[cards]
auto_refresh = True
auto_refresh_interval = 10
}}}

== Recent Changes

[[ChangeLog(cardsplugin, 3)]]

== !Author/Contributors

**Author:** [wiki:psuter] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**