@canvas-lms/tab-positioner

Utilities for positioning and reordering course tabs in Canvas LMS.

Installation

npm install @canvas-lms/tab-positioner @canvas-lms/core

Quick Start

import { CanvasAPI } from '@canvas-lms/core';
import { TabPositioner } from '@canvas-lms/tab-positioner';

const api = new CanvasAPI('https://your-school.instructure.com', 'your-api-token');
const tabPositioner = new TabPositioner(api);

// Move a specific tab to position 2
await tabPositioner.moveTab('123', 'assignments', 2);

// Move one tab to be after another
await tabPositioner.moveTabAfter('123', 'Course Integrity', 'Submit Final Grades');

// Reorder multiple tabs according to a preferred order
await tabPositioner.reorderTabs('123', [
  'Home', 
  'Announcements', 
  'Assignments', 
  'Discussions',
  'Grades'
]);

Features

• 🎯 Precise Positioning - Move tabs to exact positions
• 🔄 Relative Positioning - Position tabs relative to other tabs
• 📋 Bulk Reordering - Reorder multiple tabs at once
• 🎓 Course Processing - Process multiple courses efficiently
• 🔍 Tab Discovery - Find tabs by ID or label
• ⚡ Built on Core - Uses the robust @canvas-lms/core API client

API Reference

TabPositioner

Main class for tab positioning operations.

Constructor

import { TabPositioner } from '@canvas-lms/tab-positioner';
import { CanvasAPI } from '@canvas-lms/core';

const api = new CanvasAPI(baseURL, token);
const tabPositioner = new TabPositioner(api);

Methods

Basic Tab Movement

moveTab(courseId, tabId, position)

Move a tab to a specific position in a course.

// Move the Assignments tab to position 1 (second position, 0-indexed)
await tabPositioner.moveTab('123', 'assignments', 1);

// You can also use tab labels instead of IDs
await tabPositioner.moveTab('123', 'Assignments', 1);

Parameters:

• courseId (string) - The course ID
• tabId (string) - The tab ID or label to move
• position (number) - The new position (0-based index)

Relative Positioning

moveTabAfter(courseId, tabToMove, afterTab)

Move a tab to be positioned after another specific tab.

// Move "Course Integrity" tab to be after "Submit Final Grades"
await tabPositioner.moveTabAfter('123', 'Course Integrity', 'Submit Final Grades');

Parameters:

• courseId (string) - The course ID
• tabToMove (string) - The tab ID or label to move
• afterTab (string) - The tab ID or label to position after

Bulk Operations

reorderTabs(courseId, preferredOrder)

Reorder multiple tabs according to a preferred order array.

const preferredOrder = [
  'Home',
  'Announcements', 
  'Assignments',
  'Discussions',
  'Grades',
  'People',
  'Pages',
  'Files',
  'Syllabus'
];

await tabPositioner.reorderTabs('123', preferredOrder);

Parameters:

• courseId (string) - The course ID
• preferredOrder (string[]) - Array of tab labels in desired order

Multi-Course Processing

processCourses(courseIds, positioningFunction)

Process multiple courses with a positioning function.

const courseIds = ['123', '456', '789'];

const results = await tabPositioner.processCourses(courseIds, async (courseId) => {
  return await tabPositioner.moveTabAfter(courseId, 'Course Integrity', 'Submit Final Grades');
});

// Results array contains success/failure status for each course
results.forEach(result => {
  if (result.success) {
    console.log(`Course ${result.courseId}: Success`);
  } else {
    console.error(`Course ${result.courseId}: ${result.error}`);
  }
});

Parameters:

• courseIds (string[]) - Array of course IDs to process
• positioningFunction (Function) - Function to call for each course

Utility Methods

getTabs(courseId)

Get all tabs for a course with their current positions.

const tabs = await tabPositioner.getTabs('123');
console.log(tabs.map(tab => `${tab.label}: position ${tab.position}`));

moveCourseIntegrityAfterFinalGrades(courseId)

Legacy convenience method for a common tab positioning task.

await tabPositioner.moveCourseIntegrityAfterFinalGrades('123');

Common Use Cases

Standard Tab Order

Many institutions prefer a consistent tab order across courses:

const standardOrder = [
  'Home',
  'Announcements',
  'Assignments', 
  'Discussions',
  'Grades',
  'People',
  'Pages',
  'Files',
  'Syllabus',
  'Course Integrity',
  'Submit Final Grades'
];

// Apply to multiple courses
const courseIds = ['123', '456', '789'];
const results = await tabPositioner.processCourses(courseIds, async (courseId) => {
  return await tabPositioner.reorderTabs(courseId, standardOrder);
});

Specific Tab Positioning

Position integrity-related tabs at the end:

// Move Course Integrity tab after Submit Final Grades
await tabPositioner.moveTabAfter('123', 'Course Integrity', 'Submit Final Grades');

// Or move to a specific position (e.g., last position)
const tabs = await tabPositioner.getTabs('123');
const lastPosition = tabs.length - 1;
await tabPositioner.moveTab('123', 'Course Integrity', lastPosition);

Batch Processing with Error Handling

const courseIds = ['123', '456', '789'];
const results = await tabPositioner.processCourses(courseIds, async (courseId) => {
  try {
    // Apply standard tab ordering
    await tabPositioner.reorderTabs(courseId, standardOrder);
    return { success: true, message: 'Tabs reordered successfully' };
  } catch (error) {
    throw new Error(`Failed to reorder tabs: ${error.message}`);
  }
});

// Report results
const successful = results.filter(r => r.success).length;
const failed = results.filter(r => !r.success).length;
console.log(`Processed ${courseIds.length} courses: ${successful} successful, ${failed} failed`);

Error Handling

The TabPositioner provides detailed error information:

try {
  await tabPositioner.moveTab('123', 'NonexistentTab', 1);
} catch (error) {
  console.error('Tab positioning failed:', error.message);
  // Error: Tab "NonexistentTab" not found in course 123
}

Performance Considerations

• Batch Operations: Use processCourses() for multiple courses to get detailed results
• Tab Lookups: Tabs can be referenced by ID or label - IDs are faster but labels are more readable
• Rate Limiting: Built on @canvas-lms/core which handles Canvas API rate limiting

Related Packages

• @canvas-lms/core - Core Canvas API client (required dependency)
• @canvas-lms/gradebook - Gradebook management utilities
• @canvas-lms/assignment-utils - Assignment management utilities

License

ISC © Matthew Hepworth