This guide explains how the bookmark feature is integrated into module pages and how to add it to new modules.
The bookmark feature allows users to save and restore module parameter configurations. It's automatically integrated into all module pages through the ModuleLayout component.
The BookmarkButton component is automatically included in the ModuleLayout header. All module pages that use ModuleLayout automatically get bookmark functionality.
Requirements:
- The module page must pass a
module-idprop toModuleLayout - The module page must listen to the
@load-bookmarkevent fromModuleLayout
When a user loads a bookmark, the ModuleLayout emits a load-bookmark event with the saved parameters. The module page handles this event to restore the configuration.
<template>
<ModuleLayout
title="Your Module Title"
description="Module description"
difficulty="beginner"
:estimated-time="30"
module-id="your-module-id"
:table-of-contents="tableOfContents"
@load-bookmark="handleLoadBookmark"
>
<!-- Your module content -->
</ModuleLayout>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { useModuleStore } from '~/stores/module';
import { useBookmarkRestore } from '~/composables/useBookmarkRestore';
const moduleStore = useModuleStore();
// Define your parameters
const parameters = ref({
learningRate: 0.01,
epochs: 100,
dataset: 'default-dataset',
// ... other parameters
});
// Your training/update function
const handleTrain = async () => {
// Your training logic
};
// Bookmark restoration - automatically handles parameter updates and dataset reloading
const { handleLoadBookmark } = useBookmarkRestore(parameters, handleTrain);
</script>The useBookmarkRestore composable handles the common logic for restoring bookmarks:
Parameters:
parameters(Ref): Reference to your module's parameters objectonRestore(Function, optional): Callback to execute after parameters are restored (e.g., re-train algorithm, update visualizations)
What it does:
- Updates the parameters with bookmark values
- Reloads the dataset if it changed
- Calls your custom restore logic (if provided)
- Handles errors gracefully
// For modules that need to re-train when parameters change
const { handleLoadBookmark } = useBookmarkRestore(parameters, handleTrain);// For modules that need to reinitialize visualizations
const { handleLoadBookmark } = useBookmarkRestore(parameters, initializeVisualization);// For modules that don't need automatic actions (parameters update is enough)
const { handleLoadBookmark } = useBookmarkRestore(parameters);The bookmark saves:
- Module ID: Identifies which module the bookmark belongs to
- Bookmark Name: User-provided name for the configuration
- All Parameters: Complete snapshot of the
parametersobject - Timestamp: When the bookmark was created/updated
The bookmark system includes automatic validation:
- Bookmark name: 1-100 characters
- Parameter size: < 10KB when serialized to JSON
- Deep cloning to prevent reference issues
- User authentication via JWT
- Parameter JSON size limit (10KB)
- Bookmark name length validation
- User adjusts parameters on a module page
- User clicks the bookmark button in the header
- User enters a name for the configuration
- System validates and saves the bookmark
- For authenticated users, bookmark syncs to cloud automatically
- User clicks the bookmark button
- User selects a saved bookmark from the dropdown
- System restores all parameters
- Module re-trains/updates automatically (if configured)
- User sees the restored configuration
The bookmark system integrates with the module store:
// Parameters are automatically synced to the module store
moduleStore.setParameters(parameters.value);
// Dataset changes are handled automatically
moduleStore.loadDataset(dataset.data);The system handles common errors gracefully:
- Offline Mode: Bookmarks save locally and sync when online
- Invalid Parameters: Shows user-friendly error messages
- Missing Modules: Preserves bookmarks even if module not found
- Sync Failures: Retries with exponential backoff
When adding bookmark support to a new module:
- Save Test: Adjust parameters and save a bookmark
- Load Test: Load the bookmark and verify parameters restore correctly
- Dataset Test: Change dataset, save bookmark, load and verify dataset changes
- Sync Test: (For authenticated users) Verify bookmark syncs to cloud
- Cross-Device Test: (For authenticated users) Verify bookmark appears on other devices
- Ensure
module-idprop is set onModuleLayout - Check that
ModuleLayoutis imported correctly
- Verify
@load-bookmark="handleLoadBookmark"is set onModuleLayout - Check that
useBookmarkRestoreis called with correct parameters - Ensure the
onRestorecallback is defined if needed
- Check user authentication status
- Verify network connectivity
- Check browser console for sync errors
This implementation satisfies the following requirements from the spec:
- Requirement 1.1: Save module configurations with custom names
- Requirement 2.1: Load saved configurations
- Requirement 2.2: Restore parameter values from bookmarks
- Requirement 2.3: Trigger side effects (re-training, visualization updates)
- Requirement 7.1: Bookmark button accessible on every module page
- Requirement 7.2: Display bookmark count on button
Potential improvements for the bookmark system:
- Bookmark sharing between users
- Bookmark categories/tags
- Bookmark search and filtering
- Bookmark export/import
- Bookmark versioning