Skip to content

Basic Usage

  1. To enable import for a Page model, it should inherit from ContentImportMixin (wagtail_content_import.models.ContentImportMixin). By default, content will be imported into into a StreamField called body (see Changing Import Fields for how to change this).

  2. You'll then need to create a Mapper, which maps the parsed document into your StreamField blocks. Create a class deriving from wagtail_content_import.mappers.streamfield.StreamFieldMapper:

    from wagtail_content_import.mappers.converters import ImageConverter, RichTextConverter, TableConverter, TextConverter
    from wagtail_content_import.mappers.streamfield import StreamFieldMapper
    
    class MyMapper(StreamFieldMapper):
        html = RichTextConverter('my_paragraph_block')
        image = ImageConverter('my_image_block')
        heading = TextConverter('my_heading_block')
        table = TableConverter('my_table_block')
    

    This would map to an example StreamField defined as:

    from wagtail.images.blocks import ImageChooserBlock
    from wagtail.blocks import CharBlock, RichTextBlock, StreamBlock
    from wagtail.contrib.table_block.blocks import TableBlock
    
    class BaseStreamBlock(StreamBlock):
        """
        Define the custom blocks that `StreamField` will utilize
        """
        my_heading_block = CharBlock()
        my_paragraph_block = RichTextBlock()
        my_image_block = ImageChooserBlock()
        my_table_block = TableBlock()
    

    Note that the converters require the fields rather than the block classes: 'my_heading_block', not CharBlock.

    The above example assumes use of the simple blocks included with Wagtail. For StructBlocks, see Working with StructBlocks.

  3. Set mapper_class on your Page model to your new mapper class (or set WAGTAILCONTENTIMPORT_DEFAULT_MAPPER to your mapper use it for all imports by default).

  4. You should now see a button near the action menu when creating a new Page of your class in the admin, giving you the option to import a document.