Adding In-App Help Tooltips

This guide explains how to add helpful tooltips to screens in the 4SCH application. The tooltip system pulls help text from documentation, ensuring in-app help and documentation stay in sync.

How the System Works

┌─────────────────────────────────────────────────────────────┐
│  /docs/docs/guides/*.md                                     │
│  (Markdown files with help_keys frontmatter)                │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼  php artisan help:generate
┌─────────────────────────────────────────────────────────────┐
│  public/assets/user-guide/inline-help.json                  │
│  (Auto-generated JSON file)                                 │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼  HelpService loads & caches
┌─────────────────────────────────────────────────────────────┐
│  <x-help-tooltip key="..." />                               │
│  (Blade component renders tooltip in views)                 │
└─────────────────────────────────────────────────────────────┘

Step 1: Add Help Content to Documentation

Add help_keys to the frontmatter of relevant markdown files in /docs/docs/guides/.

Example: Adding Help for Term Exams

File: docs/docs/guides/continuous-assessment.md

---
sidebar_position: 12
title: Continuous Assessment Guide
help_keys:
  term_exams:
    intro: "Term Exams organize your assessments and CA calculations."
    name: "Give it a clear name like 'Term 1 Exam'."
    start_date: "When this assessment period begins."
    end_date: "When this assessment period ends. Must be after start date."
  ca_config:
    intro: "Configure CA weightages. Total must equal 100%."
    weightage: "Percentage weight (0-100) of this CA component."
---

Best Practices for Help Text

Do:

✅ Keep text short (1-2 sentences ideal)
✅ Use friendly, end-user language
✅ Provide examples when helpful
✅ Explain why, not just what
✅ Include constraints (e.g., "Must equal 100%")

Don't:

❌ Don't use technical jargon
❌ Don't write paragraphs (use docs guides for that)
❌ Don't repeat the field label
❌ Don't include HTML (will be escaped)

Step 2: Generate the Help JSON

After adding/updating help_keys in documentation, regenerate the JSON:

cd /path/to/staging.4sch.com
php artisan help:generate

Expected output:

🔍 Generating inline help content from documentation...
📂 Scanning: /path/to/docs/docs
📄 Found 25 markdown files
  ✓ guides/continuous-assessment.md: 12 keys
  ✓ guides/offline-exams.md: 8 keys

📊 Summary:
  • Files processed: 25
  • Files with help_keys: 2
  • Total help keys: 20
  • Output path: public/assets/user-guide/inline-help.json

✅ Help content generated successfully!
🗑️  Cache cleared

Useful Command Options

# Dry run (preview without writing)
php artisan help:generate --dry-run

# Custom docs path
php artisan help:generate --docs-path=/custom/docs

# Custom output path
php artisan help:generate --output=/custom/path/inline-help.json

Step 3: Add Tooltips to Views

Use the <x-help-tooltip> component anywhere in your Blade templates.

Basic Usage

<label>{{ __('start_date') }} <x-help-tooltip key="term_exams.start_date" /></label>

Component Properties

Prop	Type	Default	Description
`key`	string	null	Help content key (e.g., 'term_exams.name')
`text`	string	null	Direct help text (overrides key lookup)
`placement`	string	'top'	Tooltip position: top, bottom, left, right
`icon`	string	'mdi-help-circle-outline'	Material Design icon
`class`	string	''	Additional CSS classes
`showWhen`	bool	true	Conditionally show tooltip

Examples

<x-help-tooltip key="term_exams.name" />

With Custom Placement

<x-help-tooltip key="ca_config.intro" placement="bottom" />

Direct Text (No Key Lookup)

<x-help-tooltip text="This field is auto-calculated based on CA scores" />

Conditional Display

<x-help-tooltip key="advanced_setting" :showWhen="$user->isAdmin()" />

Custom Styling

<x-help-tooltip key="term_exams.name" class="text-primary" />

Common Placement Patterns

<h3 class="page-title">
    {{ __('manage_term_exams') }}
    <x-help-tooltip key="term_exams.intro" placement="right" />
</h3>

2. Form Field Label

<label>
    {{ __('field_name') }} 
    <span class="text-danger">*</span>
    <x-help-tooltip key="screen.field_name" />
</label>

3. Card Header

<div class="card-header">
    <h6>{{ __('section_title') }} <x-help-tooltip key="screen.section" /></h6>
</div>

<h5 class="modal-title">
    {{ __('configure_settings') }}
    <x-help-tooltip key="screen.settings" placement="bottom" />
</h5>

Step 4: Test Your Tooltips

Manual Testing

Refresh the page in your browser
Hover over the help icon (small circle with question mark)
Verify the tooltip appears with correct text
Check positioning - tooltip shouldn't overflow viewport

Common Issues

Cause: Help key not found in inline-help.json

Fix:

Check the key exists in your docs frontmatter
Run php artisan help:generate
Clear cache: php artisan cache:clear

Wrong Text Displayed

Cause: Cache not refreshed after updating docs

Fix:

php artisan help:generate
php artisan cache:clear

Cause: Default placement doesn't fit

Fix: Use placement prop:

<x-help-tooltip key="..." placement="left" />

Coverage Guidelines

Phase 1: Critical Admin Screens

Priority screens to cover first:

✅ Term Exams (terms/index)
✅ CA Configuration modal
✅ Manage Exams (exams/index)
⏳ Schools, Classes, Subjects
⏳ Students, Staff, Grades
⏳ Sessions, Semesters

Always add tooltips to:

✅ Page titles (intro/overview)
✅ Required form fields (* marked)
✅ Configuration options with constraints
✅ Fields with non-obvious behavior
✅ Settings affecting calculations
✅ Permissions and access controls

Skip tooltips for:

❌ Self-explanatory fields (Name, Email, Address)
❌ Read-only displays
❌ Standard buttons (Save, Cancel, Close)
❌ Static informational text

Adding a New Screen's Tooltips

Step-by-Step Workflow

Identify the screen and its key fields
Open the relevant docs guide (or create one)

Add help_keys to frontmatter:

help_keys:
  screen_name:
    intro: "What this screen is for"
    field_1: "Help for field 1"
    field_2: "Help for field 2"

Generate JSON: php artisan help:generate

Edit the Blade view:

<h3>{{ __('page_title') }} <x-help-tooltip key="screen_name.intro" placement="right" /></h3>
<label>{{ __('field_1') }} <x-help-tooltip key="screen_name.field_1" /></label>

Test in browser
Commit your changes

Maintenance

When to Update Help Text

Update help_keys when:

🔄 Field behavior changes
🔄 New constraints are added
🔄 User feedback indicates confusion
🔄 New features added

Build Hook

The help generation can be automated in deployment:

// composer.json
{
    "scripts": {
        "post-update-cmd": [
            "@php artisan help:generate"
        ]
    }
}

Architecture Reference

File Locations

File	Purpose
`app/Services/HelpService.php`	Loads and caches help content
`app/Console/Commands/GenerateHelpContent.php`	Artisan command for generation
`resources/views/components/help-tooltip.blade.php`	Reusable tooltip component
`public/assets/user-guide/inline-help.json`	Generated help content (don't edit manually)
`resources/views/layouts/footer_js.blade.php`	Global tooltip initialization

Translation Support

Help text is currently in English. To add translations:

Add language-specific help_keys:

help_keys:
  en:
    term_exams:
      name: "Give it a clear name..."
  fr:
    term_exams:
      name: "Donnez-lui un nom clair..."

Update HelpService to use app()->getLocale()

Need Help?

If you have questions about adding tooltips:

Check existing tooltip implementations in terms/index.blade.php
Review the CA Configuration modal for complex examples
Open an issue if you find bugs in the help system

Tip: Good tooltips reduce support burden and improve user experience. Take time to write helpful, clear help text! 💡

Adding In-App Help Tooltips

How the System Works

Step 1: Add Help Content to Documentation

Example: Adding Help for Term Exams

Best Practices for Help Text

Step 2: Generate the Help JSON

Useful Command Options

Step 3: Add Tooltips to Views

Basic Usage

Component Properties

Examples

Basic Tooltip

With Custom Placement

Direct Text (No Key Lookup)

Conditional Display

Custom Styling

Common Placement Patterns

1. Page Title Tooltip

2. Form Field Label

3. Card Header

Step 4: Test Your Tooltips

Manual Testing

Common Issues

Tooltip Not Showing

Wrong Text Displayed

Tooltip Position Cut Off

Coverage Guidelines

Phase 1: Critical Admin Screens

What Deserves a Tooltip?

Adding a New Screen's Tooltips

Step-by-Step Workflow

Maintenance

When to Update Help Text

Build Hook

Architecture Reference

File Locations

Translation Support

Need Help?

How the System Works​

Step 1: Add Help Content to Documentation​

Example: Adding Help for Term Exams​

Best Practices for Help Text​

Step 2: Generate the Help JSON​

Useful Command Options​

Step 3: Add Tooltips to Views​

Basic Usage​

Component Properties​

Examples​

Basic Tooltip​

With Custom Placement​

Direct Text (No Key Lookup)​

Conditional Display​

Custom Styling​

Common Placement Patterns​

1. Page Title Tooltip​

2. Form Field Label​

3. Card Header​

4. Modal Title​

Step 4: Test Your Tooltips​

Manual Testing​

Common Issues​

Tooltip Not Showing​

Wrong Text Displayed​

Tooltip Position Cut Off​

Coverage Guidelines​

Phase 1: Critical Admin Screens​

What Deserves a Tooltip?​

Adding a New Screen's Tooltips​

Step-by-Step Workflow​

Maintenance​

When to Update Help Text​

Build Hook​

Architecture Reference​

File Locations​

Translation Support​

Related Documentation​

Need Help?​

How the System Works

Step 1: Add Help Content to Documentation

Example: Adding Help for Term Exams

Best Practices for Help Text

Step 2: Generate the Help JSON

Useful Command Options

Step 3: Add Tooltips to Views

Basic Usage

Component Properties

Examples

Basic Tooltip

With Custom Placement

Direct Text (No Key Lookup)

Conditional Display

Custom Styling

Common Placement Patterns

1. Page Title Tooltip

2. Form Field Label

3. Card Header

4. Modal Title

Step 4: Test Your Tooltips

Manual Testing

Common Issues

Tooltip Not Showing

Wrong Text Displayed

Tooltip Position Cut Off

Coverage Guidelines

Phase 1: Critical Admin Screens

What Deserves a Tooltip?

Adding a New Screen's Tooltips

Step-by-Step Workflow

Maintenance

When to Update Help Text

Build Hook

Architecture Reference

File Locations

Translation Support

Related Documentation

Need Help?