Routing

The Prismic module provides a flexible routing system that allows you to map Prismic documents to URLs in your Magento store. This system integrates with Magento's URL rewrite functionality to maintain SEO-friendly URLs and proper redirects.

URL Rewrite Configuration

Basic Setup

1. Go to Stores > Configuration > Elgentos > Prismic.IO
2. Navigate to the URL Rewrites section
3. Select which content types should generate automatic URL rewrites
4. Configure webhook settings to enable automatic URL generation

Database Structure

The module uses two main tables for routing: - prismicio_route - Stores the main route information - prismicio_route_store - Maps routes to specific store views

Automatic URL Generation

The module can automatically generate URLs based on your Prismic documents:

1. Content Type Selection

   <prismicio>
       <url_rewrites>
           <content_types>blog_post,landing_page</content_types>
       </url_rewrites>
   </prismicio>
   

2. Webhook Integration

3. Set up a webhook in Prismic pointing to your Magento instance
4. Configure the webhook secret in Magento
5. The module will automatically generate URLs when content is published

Manual Route Management

You can manually manage routes through the Magento admin:

<route id="custom_route" frontName="blog">
    <module name="Elgentos_PrismicIO" />
</route>

URL Structure

Default Pattern

/{content-type}/{uid}
example: /blog/summer-fashion-trends

Custom URL Fields

You can specify custom URL fields in your Prismic content types:

{
  "Main": {
    "url_key": {
      "type": "Text",
      "config": {
        "label": "URL Key",
        "placeholder": "custom-url-key"
      }
    }
  }
}

Multi-store Support

The routing system supports Magento's multi-store setup:

1. Store-Specific Routes
2. Routes can be assigned to specific store views

3. Different URLs can be used for the same content in different stores

4. Language-Based Routing

   // Example store-specific URL pattern
   /en/blog/post-title    // English store
   /nl/blog/post-titel    // Dutch store
   

Layout Handles

The module generates specific layout handles for Prismic routes:

<!-- For a blog post content type -->
<handle id="prismicio_by_type_blog_post">
    <reference name="content">
        <block class="Elgentos\PrismicIO\Block\Template" name="blog.content" template="blog/post.phtml"/>
    </reference>
</handle>

Cache Management

The routing system integrates with Magento's cache:

1. Cache Tags
2. Routes are tagged appropriately for cache invalidation

3. Content updates trigger relevant cache flushes

4. Configuration

   <prismicio>
       <cache_flush>
           <content_types>blog_post,landing_page</content_types>
       </cache_flush>
   </prismicio>
   

Troubleshooting

Common routing issues and solutions:

1. URLs Not Generating
2. Verify webhook configuration
3. Check content type is selected in URL rewrites configuration

4. Ensure proper permissions are set

5. 404 Errors

6. Verify route exists in prismicio_route table
7. Check store assignment in prismicio_route_store

8. Confirm content type is properly configured

9. Multiple Redirects

10. Check for conflicting URL rewrites
11. Verify store view configuration
12. Review custom URL keys

Best Practices

1. URL Structure
2. Use consistent patterns across content types
3. Keep URLs clean and meaningful

4. Consider SEO implications

5. Performance

6. Enable caching for routes
7. Use webhooks for automatic updates

8. Monitor URL rewrite table size

9. Maintenance

10. Regularly review and clean up unused routes
11. Maintain proper redirects for changed URLs
12. Document custom routing patterns