iws_help 0.5.0

Add documentation pages and contextual help to widgets using the IWS service.

IWS Help Package

A Flutter package that provides contextual help and documentation functionality by integrating with the IWS (InteraAD Web Services) documentation service. This package allows you to easily add help icons, dialogs, screens, and help lists to your Flutter applications.

Features

• Contextual Help Icons: Wrap any widget with a help icon that displays relevant documentation
• Help Dialogs: Show help content in modal dialogs (full-screen or compact)
• Help Screens: Display help content in dedicated full-screen views
• General Help Buttons: Add buttons that show lists of all available help topics
• Page-specific Help: Filter help content by page keys for organized documentation
• Markdown Support: Rich content display with markdown formatting and clickable links
• State Management: Built with BLoC pattern for reliable state management
• Customizable Content: Configure custom content builders for help display
• API Integration: Seamless integration with IWS documentation service

Getting Started

1. Add API Key Configuration

Add the IWS API key as a Dart define variable at compile time:

--dart-define=IWS_API_KEY=your_api_key_here

2. Initialize the Help Service

import 'package:flutter/material.dart';
import 'package:iws_help/iws_help.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final iwsHelp = IwsHelp();
  
  // Load help data from the server
  iwsHelp.loadHelp();
  
  runApp(MyApp());
}

3. Optional: Custom Content Builder

You can customize how help content is displayed:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final iwsHelp = IwsHelp();
  
  // Set custom content builder
  iwsHelp.contentBuilder = (documentation) {
    return Column(
      children: [
        Text(
          documentation.title,
          style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
        ),
        SizedBox(height: 10),
        Text(documentation.rawContent ?? 'Help not available'),
      ],
    );
  };
  
  iwsHelp.loadHelp();
  
  runApp(MyApp());
}

Usage Examples

1. Contextual Help Icon

Wrap any widget with a HelpIcon to add contextual help:

import 'package:iws_help/iws_help.dart';

// Compact help dialog
HelpIcon(
  helpKey: 'money_field',
  fullScreen: false,
  child: TextField(
    decoration: InputDecoration(labelText: 'Amount'),
  ),
)

// Full-screen help
HelpIcon(
  helpKey: 'password_recovery',
  fullScreen: true,
  alignment: WrapCrossAlignment.start,
  child: ElevatedButton(
    onPressed: () => resetPassword(),
    child: Text('Reset Password'),
  ),
)

HelpIcon Parameters:

• helpKey: String identifier for the help content
• fullScreen: Whether to show help in full screen (true) or dialog (false)
• child: The widget to wrap with help functionality
• icon: Custom help icon widget (optional)
• alignment: Cross-axis alignment for the help icon

2. General Help Button

Add a general help button to app bars or other locations:

Scaffold(
  appBar: AppBar(
    title: Text('My App'),
    actions: [
      // Button with label
      GeneralHelpButton(
        label: 'Help',
        pageKey: 'main_page', // Optional: filter by page
      ),
      
      // Icon-only button
      GeneralHelpButton(
        showLabel: false,
        icon: Icon(Icons.help_center),
      ),
    ],
  ),
  body: MyContent(),
)

GeneralHelpButton Parameters:

• pageKey: Filter help content by specific page (optional)
• label: Button text label
• icon: Custom icon widget
• showLabel: Whether to show text label or icon only

3. Programmatic Help Display

Show help content programmatically:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        ElevatedButton(
          onPressed: () {
            // Show specific help content
            IwsHelp().showHelp(context, 'help_key', fullScreen: true);
          },
          child: Text('Show Help'),
        ),
        
        ElevatedButton(
          onPressed: () {
            // Show help list for current page
            IwsHelp().showHelpList(context, pageKey: 'current_page');
          },
          child: Text('Show All Help'),
        ),
      ],
    );
  }
}

4. Advanced Usage - Custom Help Integration

class CustomHelpScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Advanced Help Example'),
        actions: [
          // Page-specific help
          GeneralHelpButton(
            pageKey: 'settings_page',
            label: 'Settings Help',
          ),
          
          // General help
          GeneralHelpButton(
            label: 'All Help',
          ),
        ],
      ),
      body: SingleChildScrollView(
        padding: EdgeInsets.all(16),
        child: Column(
          children: [
            // Form field with help
            HelpIcon(
              helpKey: 'username_field',
              fullScreen: false,
              child: TextFormField(
                decoration: InputDecoration(
                  labelText: 'Username',
                  border: OutlineInputBorder(),
                ),
              ),
            ),
            
            SizedBox(height: 20),
            
            // Complex widget with help
            HelpIcon(
              helpKey: 'date_picker_help',
              fullScreen: true,
              icon: Icon(Icons.info_outline, color: Colors.blue),
              child: Card(
                child: Padding(
                  padding: EdgeInsets.all(16),
                  child: DatePicker(),
                ),
              ),
            ),
            
            SizedBox(height: 20),
            
            // Action button with help
            Row(
              children: [
                Expanded(
                  child: ElevatedButton(
                    onPressed: () => submitForm(),
                    child: Text('Submit'),
                  ),
                ),
                HelpIcon(
                  helpKey: 'submit_process',
                  fullScreen: true,
                  child: SizedBox(), // Empty child, just the help icon
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

API Reference

IwsHelp Class

Main singleton class for managing help functionality:

// Get singleton instance
final iwsHelp = IwsHelp();

// Load help data
iwsHelp.loadHelp();

// Show specific help
iwsHelp.showHelp(context, 'help_key', fullScreen: true);

// Show help list
iwsHelp.showHelpList(context, pageKey: 'page_key');

// Access help data
Future<PaginatedData<Page>> pages = iwsHelp.getPages();
Future<PaginatedData<Documentation>> docs = iwsHelp.getDocuments();
Future<Documentation> doc = iwsHelp.getDocument(documentId);

// Custom content builder
iwsHelp.contentBuilder = (documentation) => CustomWidget();

Data Models

Documentation Model:

class Documentation {
  int id;
  int documentationPageId;
  String name;
  String title;
  String? rawContent;
  dynamic content;
  bool active;
  DateTime? createdAt;
  DateTime? updatedAt;
}

Page Model:

class Page {
  int id;
  String name;
  String title;
  DateTime? createdAt;
  DateTime? updatedAt;
}

Configuration

The package connects to the IWS documentation service with the following configuration:

• API Authority: ws.interaad.com.ar
• API Base Path: api/sdk/documentation/
• API Key: Provided via IWS_API_KEY environment variable

Best Practices

1. Load Help Early: Call IwsHelp().loadHelp() during app initialization
2. Use Meaningful Keys: Use descriptive helpKey values that match your documentation
3. Page Organization: Group related help content using pageKey parameters
4. Full Screen vs Dialog: Use full screen for detailed help, dialogs for quick tips
5. Custom Content: Implement custom content builders for consistent styling
6. Error Handling: The package handles API errors gracefully with fallback messages

Troubleshooting

• No Help Icons Appear: Ensure loadHelp() is called and API key is configured
• Help Content Not Loading: Check internet connection and API key validity
• Custom Styling: Use the contentBuilder property to customize help display