Help Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   # Add to deps file (as per README)
   [DezullHelpBundle]
       git=git://github.com/dezull/HelpBundle.git
       target=/bundles/Dezull/Bundle/HelpBundle
   

   Run php bin/vendors install and register the bundle in AppKernel.php.

2. Database Setup: Run the provided SQL schema (e.g., CREATE TABLE help_...) to create tables for help topics and content. Alternatively, use Doctrine migrations if configured.

3. Basic Routing: Add the required route in routing.yml:

   DezullHelpBundle:
       prefix: /help
       resource: "@DezullHelpBundle/Resources/config/routing/main.yml"
   

4. First Use Case:

   • Access /help to view the default two-pane help browser.
   • Use the admin interface (if enabled) to add/edit help topics via /help/admin.

Where to Look First

• Admin Panel: /help/admin (if configured) for managing help content.
• Frontend Template: @DezullHelpBundle/Browser/index.html.twig for customizing the help layout.
• Doctrine Entities: Dezull\Bundle\HelpBundle\Entity\HelpTopic and HelpContent for extending data models.

Implementation Patterns

Workflows

1. Content Management:

   • Use the admin panel to create HelpTopic (categories) and HelpContent (articles).
   • Example workflow:

     // Create a new topic via service (if admin API is exposed)
     $topic = new \Dezull\Bundle\HelpBundle\Entity\HelpTopic();
     $topic->setTitle('API Reference');
     $em->persist($topic);
     $em->flush();
     

2. Frontend Integration:

   • Embed help links in your app:

     <a href="{{ path('help_topic', { title: 'Getting Started' }) }}">Help</a>
     

   • Override the default template by extending:

     {% extends '@DezullHelpBundle/Browser/index.html.twig' %}
     {% block help_content %}{{ content }}{% endblock %}
     

3. Dynamic Help Routing:

   • Use annotations for topic-specific routes:

     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Dezull\Bundle\HelpBundle\Annotation\HelpTopic;
     
     /**
      * @Route("/custom-help", name="custom_help")
      * @HelpTopic("Custom Guide")
      */
     public function customHelpAction() { ... }
     

Integration Tips

• CKEditor Integration (Optional): If TrsteelCkeditorBundle is installed, enable rich-text editing for help content in the admin panel.

• Localization: Extend the HelpContent entity to support translations:

  // In your custom entity
  use Gedmo\Mapping\Annotation as Gedmo;
  
  /**
   * @Gedmo\Translatable
   */
  class CustomHelpContent extends HelpContent { ... }
  

• API Access: Expose help content via API (e.g., using FOSRestBundle):

  # routing.yml
  help_api:
      type:     rest
      resource: "@DezullHelpBundle/Resources/config/routing/api.yml"
  

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The bundle is incompatible with Symfony 2.1.x. Ensure you’re using Symfony 2.3+ or 3.x/4.x (if backported).

2. Database Schema:

   • The provided SQL is minimal. Extend the schema if you need custom fields (e.g., HelpContent metadata like last_updated).

3. Admin Panel Security:

   • The admin routes (/help/admin) are not secured by default. Add firewall rules in security.yml:

     access_control:
         - { path: ^/help/admin, roles: ROLE_ADMIN }
     

4. Routing Conflicts:

   • The !{title} in _help_topic route uses a wildcard. Ensure no other routes conflict with /help/*.

Debugging

• Missing Admin Panel: Verify the DezullHelpBundle is enabled in AppKernel.php and the main.yml routes are loaded.

• Blank Help Pages: Check if the HelpTopic and HelpContent tables are populated. Run:

  php app/console doctrine:schema:validate
  

• Template Overrides: Clear the cache after modifying Twig templates:

  php app/console cache:clear
  

Extension Points

1. Custom Fields: Extend the HelpContent entity and update the admin form:

   // src/Dezull/Bundle/HelpBundle/Resources/config/doctrine/HelpContent.orm.yml
   Dezull\Bundle\HelpBundle\Entity\HelpContent:
       fields:
           customField:
               type: string
               nullable: true
   

2. Event Listeners: Hook into help content updates (e.g., send notifications):

   // src/Dezull/Bundle/HelpBundle/EventListener/HelpListener.php
   use Dezull\Bundle\HelpBundle\Event\HelpContentEvent;
   
   public function onHelpContentUpdate(HelpContentEvent $event) {
       // Logic here
   }
   

   Register in services.yml:

   services:
       dezull.help.listener:
           class: Dezull\Bundle\HelpBundle\EventListener\HelpListener
           tags:
               - { name: kernel.event_listener, event: help.content.update, method: onHelpContentUpdate }
   

3. Custom Templates: Override the entire admin panel by copying:

   vendor/bundles/Dezull/Bundle/HelpBundle/Resources/views/Admin/
   

   to app/Resources/DezullHelpBundle/views/Admin/.

Configuration Quirks

• Prefixing: The prefix in routing (/help) is hardcoded in the bundle’s main.yml. To change it, override the entire routing file.

• Doctrine Migrations: If using migrations, create a custom migration for the help_* tables instead of manual SQL.

• Asset Paths: Static assets (CSS/JS) are loaded from the bundle’s Resources/public. For custom assets, extend the base template and update paths.