App Business Dropcap Bundle Laravel Package

Getting Started

Minimal Setup

1. Install AlphaLemon CMS Sandbox (if not already installed):

   git clone https://github.com/alphalemon/AlphaLemonCmsSandbox.git
   cd AlphaLemonCmsSandbox
   

2. Install the Bundle via Composer:

   composer require alphalemon/app-business-dropcap-bundle
   

3. Enable the Bundle in app/AppKernel.php:

   new AlphaLemon\Business\DropCapBundle\AlphaLemonBusinessDropCapBundle(),
   

4. Clear Cache:

   php app/console cache:clear --env=dev
   

First Use Case

• Add a DropCap Field to a Content Type: Extend an existing content type (e.g., Page) by adding the DropCap field in the CMS admin panel under "Content Types" > [Your Type] > "Fields".

  • Select "DropCap" as the field type.
  • Configure the drop cap style (e.g., first, all, or custom CSS classes).

• Render DropCaps in Templates: Use the Twig extension provided by the bundle:

  {{ alphalemon_dropcap(content.title, 'first') }}
  

  (Replace 'first' with 'all' or a custom class like 'custom-class' if configured.)

Implementation Patterns

Workflows

1. Content Type Integration:

   • Admin Workflow:
     1. Navigate to Content Types in the AlphaLemon CMS admin.
     2. Edit an existing content type or create a new one.
     3. Add a field of type "DropCap Title".
     4. Configure the field (e.g., label, help text, default drop cap style).
   • Frontend Workflow: Use the Twig filter in templates to render drop caps dynamically:

     {% for article in articles %}
         <h2>{{ article.title|alphalemon_dropcap('first') }}</h2>
         {{ article.content }}
     {% endfor %}
     

2. Dynamic Styling:

   • Override default styles by adding custom CSS classes in the field configuration.
   • Example: Configure the field to use dropcap-large and style it in your theme’s CSS:

     .dropcap-large:first-letter {
         font-size: 4em;
         float: left;
         line-height: 1;
         margin-right: 0.1em;
     }
     

3. Reusable Components:

   • Create a Twig macro for consistent drop cap usage across templates:

     {% macro dropCapTitle(title, style) %}
         <h2>{{ title|alphalemon_dropcap(style) }}</h2>
     {% endmacro %}
     

   • Include it in layouts or base templates.

Integration Tips

• Symfony Forms: If extending Symfony forms, manually render the drop cap in the template after form submission:

  {{ form_row(form.title) }}
  <h2>{{ form.title.vars.data|alphalemon_dropcap('first') }}</h2>
  

• API Responses: For JSON APIs, exclude the drop cap from responses (it’s a presentation layer feature). Use a custom serializer or filter:

  // In a serializer
  $normalizer->ignoreNull();
  $normalizer->setIgnoredAttributes(['dropCapStyle']);
  

• Localization: Translate drop cap labels and help text via AlphaLemon’s translation system (e.g., trans('DropCapBundle::dropcap.label')).

Gotchas and Tips

Pitfalls

1. Bundle Compatibility:

   • Symfony 2.1 Only: This bundle is not compatible with Symfony 3+ or 4+. If upgrading, check for forks or alternatives.
   • AlphaLemon Dependency: Ensure AlphaLemonCmsBundle is installed and configured. Missing dependencies will cause ClassNotFound errors.

2. Caching Issues:

   • After adding the bundle, clear all caches (including Twig and Symfony caches):

     php app/console cache:clear --env=all
     

   • If drop caps don’t render, verify the Twig extension is loaded (check app/config/config.yml for twig extensions).

3. Field Configuration:

   • Missing Field Type: If the "DropCap Title" option doesn’t appear in the admin, ensure:
     • The bundle is enabled in AppKernel.php.
     • The database schema is up to date (run migrations if applicable).
   • Default Styles: The bundle provides basic styles. Override them in your theme’s CSS to avoid unexpected rendering.

4. Twig Filter Scope:

   • The alphalemon_dropcap filter is Twig-only. Avoid using it in PHP templates or non-Twig contexts (e.g., Blade in Lumen).

Debugging

• Check Logs: Enable debug mode (app/config/config_dev.yml) and inspect app/logs/dev.log for:
  • ClassNotFoundException: Missing bundle or dependency.
  • RuntimeException: Invalid drop cap style or malformed input.
• Verify Twig Extensions: Dump registered Twig extensions to confirm the filter is loaded:

  // In a controller or CLI command
  $twig = $this->get('twig');
  dump(get_class_methods($twig->getExtension('alphalemon_dropcap')));
  

Tips

1. Custom Drop Cap Styles: Extend the bundle’s default behavior by creating a custom Twig extension:

   // src/AlphaLemon/YourBundle/Twig/DropCapExtension.php
   class DropCapExtension extends \Twig_Extension
   {
       public function getFilters()
       {
           return [
               new \Twig_SimpleFilter('custom_dropcap', [$this, 'renderDropCap']),
           ];
       }
   
       public function renderDropCap($text, $style = 'first')
       {
           // Custom logic (e.g., add icons, colors)
           return '<span class="dropcap-'.$style.'">'.$text.'</span>';
       }
   }
   

   Register it in services.yml:

   services:
       your_bundle.dropcap_extension:
           class: AlphaLemon\YourBundle\Twig\DropCapExtension
           tags:
               - { name: twig.extension }
   

2. Performance:

   • Lazy-Loading: Drop caps are rendered client-side. For large pages, consider lazy-loading them via JavaScript:

     // Add this to your theme's JS
     document.querySelectorAll('.dropcap').forEach(el => {
         el.innerHTML = el.textContent.replace(/^([^\s]+)/, '<span class="dropcap-first">$1</span>');
     });
     

   • CSS Containment: Use float or grid to prevent layout shifts caused by drop caps.

3. Testing:

   • Test drop cap rendering in multiple browsers (some CSS properties like first-letter behave differently in older browsers).
   • Use AlphaLemon’s test tools to verify admin field configurations:

     // Example functional test
     $client = static::createClient();
     $crawler = $client->request('GET', '/admin/content-types');
     $this->assertContains('DropCap Title', $crawler->html());