tutorials_readme.md

Creating a New Tutorial for MartyBlocks

This guide explains how to add a new tutorial (lesson) to MartyBlocks.

1. Create a New Tutorial File

• Navigate to:
  marty-blocks-lib/replacements/scratch-gui/src/lib/libraries/decks/general-lessons/
• Copy an existing tutorial file (e.g., cog-and-marty-dummy.js) and rename it for your new tutorial.

2. Edit the Tutorial File

• Update the exported object:
  • Change the id, name, type, urlId, description, img, tags, and collaborator fields as needed.
  • Add or modify the steps array to define the tutorial flow.
    • Each step can include:
      • type: e.g., "info", "end"
      • description: Use <FormattedMessage /> for i18n support.
      • image: (optional) URL to an image for the step (we use aws bucket).
      • nextStepActions: (optional) UI actions (see other tutorials for examples).
      • expectedCode: (optional) Array of block sequences to check for in the workspace.
      • hint: (optional) Hints for the user.

3. Add Images

• Upload any images referenced in your tutorial to the appropriate S3 bucket or public URL.
• Reference images in your steps using the img or image fields.

4. Register the Tutorial

• Open:
  marty-blocks-lib/replacements/scratch-gui/src/lib/libraries/decks/index.jsx
• Import your new tutorial at the top.
• Add it to the exported object, e.g.:

  import myNewTutorial from './general-lessons/my-new-tutorial';
  // ...existing code...
  export default {
      ...myNewTutorial,
      // ...existing code...
  }

5. Test

• Run the app and verify your tutorial appears and works as expected.

6. Tips

• Use <FormattedMessage /> for all user-facing text for localization.
• Use the steps array to guide users through the tutorial, using actions and hints as needed.
• Look at existing tutorials for examples of best practices.

---

File Responsibilities Summary

LessonUIHelper.js
Located at: marty-blocks-lib/replacements/scratch-gui/src/components/lessons/LessonUIHelper.js

• Provides static helper methods for UI interactions in tutorials, such as highlighting blocks or elements, animating block movements, and managing highlights.

LessonEngine.js
Located at: marty-blocks-lib/replacements/scratch-gui/src/components/lessons/LessonEngine.js

• Orchestrates the tutorial step logic, handling actions (like highlighting or animating), step transitions, and code evaluation for tutorial progress.

cog-and-marty-dummy.js
Located at: marty-blocks-lib/replacements/scratch-gui/src/lib/libraries/decks/general-lessons/cog-and-marty-dummy.js

• Example tutorial definition file. Exports a tutorial object with metadata and an array of steps, each describing UI actions, hints, and code checks.

index.jsx
Located at: marty-blocks-lib/replacements/scratch-gui/src/lib/libraries/decks/index.jsx

• Central registry for all tutorials and how-tos. Imports and aggregates tutorial objects for use in the app's tutorial system.