# Extending the Tutorial System
Guide for adding new features to the Tutorial Engine and Step Builder.
---
## Part 1: Adding a New Engine Extension
Engine extensions are self-contained plugins that hook into the tutorial lifecycle without modifying `TutorialEngine.js`.
### Step 1: Create the Extension File
Create a file in `tutorials/extensions/YourExtension.js`:
```js
export const YourExtension = {
name: 'yourFeature',
// Called once when engine.use() registers the plugin
install(engine) {
// Store engine ref if needed
this.engine = engine;
},
// Called BEFORE each step renders. Return false to skip the step.
beforeStep(step, index, engine) {
if (!step.yourProperty) return; // no-op if feature not used
// Your logic here
// return false; // to skip step
},
// Called AFTER the typewriter finishes typing
afterTyping(step, isLast, engine) {
// Good place to add interactive elements, start observers, etc.
},
// Called when the tutorial DOM is first built
onBuildDOM(engine) {},
// Called when animations/state are cleaned up between steps
onCleanup(engine) {
// IMPORTANT: clean up any DOM, listeners, or observers here
},
// Called when the tutorial closes
onClose(engine) {
// Final cleanup
},
};
```
### Step 2: Register the Extension
In `tutorials/TutorialEngine.js`, add the import at the top and register in the constructor:
```js
import { YourExtension } from './extensions/YourExtension.js';
// In constructor, after the existing .use() calls:
this.use(YourExtension);
```
### Step 3: Add Config Defaults (if needed)
If your feature needs configurable options, add defaults to `tutorials/TutorialConfig.js`:
```js
static DEFAULTS = {
// ... existing defaults ...
yourFeatureColor: '#ff0000',
yourFeatureEnabled: true,
};
```
Read them in your extension via `engine.config.get('yourFeatureColor')`.
### Available Hooks
| Hook | Arguments | Return | When |
|------|-----------|--------|------|
| `install` | `(engine)` | — | Once on `engine.use()` |
| `beforeStep` | `(step, index, engine)` | `false` to skip | Before step renders |
| `afterTyping` | `(step, isLast, engine)` | — | After typewriter finishes |
| `onBuildDOM` | `(engine)` | — | After initial DOM construction |
| `onCleanup` | `(engine)` | — | Between step transitions |
| `onClose` | `(engine)` | — | Tutorial closes |
### Example: The HideIf Extension
```js
// tutorials/extensions/HideIfExtension.js
export const HideIfExtension = {
name: 'hideIf',
beforeStep(step, index, engine) {
if (!step.hideIf) return;
if (engine.config.get('devMode')) return;
if (document.querySelector(step.hideIf)) return false;
},
};
```
Registered in TutorialEngine constructor: `this.use(HideIfExtension);`
---
## Part 2: Adding a New Step Builder Section (Card)
Step builder cards are child Vue components that edit step properties.
### Step 1: Create the Card Component
Create a file in `components/step-builder/cards/SbYourCard.vue`:
```vue
YOUR CARD{{ sb.cards.yourCard ? '▼' : '▶' }}
```
### Step 2: Register in the Parent
In `components/VlTutorialStepBuilder.vue`:
1. **Import:**
```js
import SbYourCard from './step-builder/cards/SbYourCard.vue';
```
2. **Register:**
```js
components: {
// ... existing components ...
SbYourCard,
},
```
3. **Add to cards data:**
```js
cards: {
// ... existing cards ...
yourCard: false, // false = collapsed by default
},
```
4. **Add to template** (inside the `.sb-detail` div):
```html
```
### Step 3: Add Styles (if needed)
Append any new CSS classes to `tutorials/tutorial.scss`. All styles are global with `sb-` prefix.
```scss
// ─── Your Card ───
.sb-your-special-input { /* ... */ }
```
Do NOT add `