wekan/docs/Design/Original-Positions.md

Original Positions Tracking Feature

This feature allows users to see the original positions of swimlanes, lists, and cards before the list naming feature was added in commit 719ef87efceacfe91461a8eeca7cf74d11f4cc0a.

Overview

The original positions tracking system automatically captures and stores the initial positions of all board entities (swimlanes, lists, and cards) when they are created. This allows users to:

• View the original position of any entity
• See if an entity has moved from its original position
• Track the original title before any changes
• View a complete history of original positions for a board

Features

1. Automatic Position Tracking

• Swimlanes: Tracks original sort position and title
• Lists: Tracks original sort position, title, and swimlane assignment
• Cards: Tracks original sort position, title, swimlane, and list assignment

2. Database Schema

The system uses a new PositionHistory collection with the following structure:

{
  boardId: String,           // Board ID
  entityType: String,        // 'swimlane', 'list', or 'card'
  entityId: String,          // Entity ID
  originalPosition: Object,  // Original position data
  originalSwimlaneId: String, // Original swimlane (for lists/cards)
  originalListId: String,    // Original list (for cards)
  originalTitle: String,     // Original title
  createdAt: Date,          // When tracked
  updatedAt: Date           // Last updated
}

3. UI Components

Individual Entity Display

• Shows original position information for individual swimlanes, lists, or cards
• Indicates if the entity has moved from its original position
• Displays original title if different from current title

Board-Level View

• Complete overview of all original positions on a board
• Filter by entity type (swimlanes, lists, cards)
• Search and sort functionality
• Export capabilities

Usage

1. Automatic Tracking

Position tracking happens automatically when entities are created. No manual intervention required.

2. Viewing Original Positions

In Templates

<!-- Show original position for a swimlane -->
{{> originalPosition entityId=swimlane._id entityType="swimlane"}}

<!-- Show original position for a list -->
{{> originalPosition entityId=list._id entityType="list"}}

<!-- Show original position for a card -->
{{> originalPosition entityId=card._id entityType="card"}}

In JavaScript

import { addOriginalPositionToSwimlane, addOriginalPositionToList, addOriginalPositionToCard } from '/client/lib/originalPositionHelpers';

// Track original position for a swimlane
addOriginalPositionToSwimlane(swimlaneId);

// Track original position for a list
addOriginalPositionToList(listId);

// Track original position for a card
addOriginalPositionToCard(cardId);

3. Server Methods

Track Original Positions

// Track swimlane
Meteor.call('positionHistory.trackSwimlane', swimlaneId);

// Track list
Meteor.call('positionHistory.trackList', listId);

// Track card
Meteor.call('positionHistory.trackCard', cardId);

Get Original Position Data

// Get swimlane original position
Meteor.call('positionHistory.getSwimlaneOriginalPosition', swimlaneId);

// Get list original position
Meteor.call('positionHistory.getListOriginalPosition', listId);

// Get card original position
Meteor.call('positionHistory.getCardOriginalPosition', cardId);

Check if Entity Has Moved

// Check if swimlane has moved
Meteor.call('positionHistory.hasSwimlaneMoved', swimlaneId);

// Check if list has moved
Meteor.call('positionHistory.hasListMoved', listId);

// Check if card has moved
Meteor.call('positionHistory.hasCardMoved', cardId);

Get Board History

// Get all position history for a board
Meteor.call('positionHistory.getBoardHistory', boardId);

// Get position history by entity type
Meteor.call('positionHistory.getBoardHistoryByType', boardId, 'swimlane');
Meteor.call('positionHistory.getBoardHistoryByType', boardId, 'list');
Meteor.call('positionHistory.getBoardHistoryByType', boardId, 'card');

Integration Examples

1. Add to Swimlane Template

<template name="swimlane">
  <div class="swimlane">
    <!-- Existing swimlane content -->
    
    <!-- Add original position info -->
    {{> originalPosition entityId=_id entityType="swimlane"}}
  </div>
</template>

2. Add to List Template

<template name="list">
  <div class="list">
    <!-- Existing list content -->
    
    <!-- Add original position info -->
    {{> originalPosition entityId=_id entityType="list"}}
  </div>
</template>

3. Add to Card Template

<template name="card">
  <div class="card">
    <!-- Existing card content -->
    
    <!-- Add original position info -->
    {{> originalPosition entityId=_id entityType="card"}}
  </div>
</template>

4. Add Board-Level View

<template name="board">
  <div class="board">
    <!-- Existing board content -->
    
    <!-- Add original positions view -->
    {{> originalPositionsView}}
  </div>
</template>

Configuration

1. Enable/Disable Tracking

Position tracking is enabled by default. To disable it, comment out the tracking hooks in the model files:

// In models/swimlanes.js, models/lists.js, models/cards.js
// Comment out the tracking hooks:
/*
Meteor.setTimeout(() => {
  const entity = Collection.findOne(doc._id);
  if (entity) {
    entity.trackOriginalPosition();
  }
}, 100);
*/

2. Customize Display

Modify the CSS files to customize the appearance:

• client/components/common/originalPosition.css
• client/components/boards/originalPositionsView.css

Database Migration

No database migration is required. The system automatically creates the PositionHistory collection when first used.

Performance Considerations

• Position tracking adds minimal overhead to entity creation
• Original position data is only stored once per entity
• Database indexes are created for efficient querying
• UI components use reactive data for real-time updates

Troubleshooting

1. Original Position Not Showing

• Check if the entity has been created after the feature was implemented
• Verify that the position tracking hooks are enabled
• Check browser console for any JavaScript errors

2. Performance Issues

• Ensure database indexes are created (happens automatically on startup)
• Consider limiting the number of entities displayed in the board view
• Use the filter functionality to reduce the number of displayed items

3. Data Inconsistencies

• Original position data is only captured when entities are created
• Existing entities will not have original position data
• Use the refresh functionality to re-scan the board

Future Enhancements

• Export original position data to CSV/JSON
• Bulk operations for managing original positions
• Integration with board templates
• Advanced filtering and search capabilities
• Position change notifications
• Historical position timeline view

Support

For issues or questions about the original positions tracking feature, please:

1. Check the browser console for errors
2. Verify that all required files are present
3. Test with a new board to ensure the feature works correctly
4. Report issues with detailed error messages and steps to reproduce