pb_import

PB Import - Paragraphs Bundles Import

PB Import (Paragraphs Bundles Import) is a comprehensive Drupal module that streamlines bulk content operations through CSV file imports. Built specifically for Paragraphs Bundles, it provides enterprise-grade tools for importing and managing both nodes and complex paragraph structures with built-in validation, error handling, and security features.

Ideal for: Content migrations, bulk operations, automated workflows, and structured paragraph-based layouts.

Video Tutorials

• Part 1: Introduction & Overview
• Part 2: Node Import Workflow
• Part 3: Paragraph Import
• Part 4: Advanced Features

Key Features

• CSV-Based Import: Import nodes and paragraphs from well-structured CSV files with automatic validation and comprehensive error reporting
• File Management: Register files uploaded via SFTP/FTP with automatic file entity creation and validation
• Taxonomy Integration: Automatic term creation and assignment with multi-term support using pipe (|) delimiters
• Image Handling: Complete image field support including alt text, titles, and format validation (jpg, jpeg, png, gif, webp)
• Security Features: Path traversal prevention, input sanitization, and comprehensive validation throughout
• Error Tracking: Detailed logging, user-friendly error messages, and row-level skip reporting
• Drupal 11 Ready: Full PHP 8.1+ strict typing and modern API compliance

The Solo theme and Paragraphs Bundles module for Drupal

Comprehensive Landing Page Examples Showcasing All Paragraph Bundles

Blue Skyline - Bright Den - Calm Corner - Color Whirl - Dawn View - Dream Road - Dusk Deck - Earth Base - Green Park - Jewel Place - Ocean Field - Peace Beach - Red Hill - Ring Retreat - Secret Garden - Shadow Line - Shine Land - Sky Pattern - Space Art - Star Circle - Star Gate - Star Home - Summit Point - Sun Plains

The theme includes 50 professional predefined color schemes that can be installed with a single click.

Berry Blue Dreams - Blueberry Skies Quartet - Blushing Magnolia - Celestial Blue Depths - Charcoal Gray - Classic Ivory Lace - Cotton Candy Whispers - Crimson Denim Night - Deep Ocean Shadows - Deep Sea Echo - Denim Twilight - Dusk Shadow Fusion - Eclipse Noir - Enchanted Forest Zest - Ethereal White Harmony - Flaming Sapphire - Galactic Stone Hues - Gentle Ivory Breeze - Gunmetal Echo - Indigo Pulse - Ivory Whisper - Jungle Denim Fusion - Lemon Lime Forest - Luminous Alabaster - Magnolia Afternoon - Metallic Nebula - Midnight Denim Swirl - Midnight Garden Trio - Midnight Navy Duo - Midnight Whispers - Monochrome Splash - Mystic Ash Twilight - Nightfall in Paris - Nocturnal Velvet - Obsidian Cascade - Ocean Depths Mystery - Parisian Skyline - Porcelain Brilliance - Porpoise Dream - Pristine Porcelain Glow - Raspberry Nightfall - Razzle Onyx Elegance - Royal Azure Flame - Rustic Redwood Charm - Salmon Denim Fade - Silken Shadow Whisper - Smokey Quartz Symphony - Soft Silk Elegance - Twilight Ash Mystique - Urban Stone Shadows

Module Structure

After installation, PB Import adds a menu under Content → PB Import with four administrative interfaces:

Interface Path Purpose Paragraphs List /admin/content/paragraphs/paragraphs-list View, filter, edit, and delete all paragraphs in the system Register Uploaded Files /admin/content/paragraphs/register-uploaded-files Register files uploaded via SFTP to make them available to Drupal Import Nodes /admin/content/paragraphs/pb-import-node Bulk import content nodes from CSV files Import Paragraphs /admin/content/paragraphs/pb-import-para Import hierarchical paragraph structures from CSV files

Understanding "Register Files"

Drupal stores files in sites/[site-name]/files/. Files uploaded through Drupal's UI (such as the IMCE module) are automatically registered in the file management system. However, files uploaded directly via SFTP need to be registered manually before they can be referenced in CSV imports.

Why register files? Without registration, Drupal cannot:

• Reference files in entity fields (image fields, file fields, etc.)
• Track file usage and relationships between entities
• Manage file metadata such as alt text and titles
• Enforce file permissions and access control

Example workflow:

1. Upload images to sites/default/files/gallery/2024/ via SFTP
2. Navigate to Content → PB Import → Register Uploaded Files
3. Enter relative path: gallery/2024
4. Click "Register Files" - the system scans the directory and creates file entities
5. Files are now available for CSV import operations

Submodule: PB Import Node

The PB Import Node submodule streamlines bulk node creation with CSV imports, supporting images, taxonomy terms, and rich text content.

Features

• CSV-based node creation with header validation
• Image field population with alt text and titles
• Automatic taxonomy term creation and assignment
• Configurable content types and vocabularies
• Comprehensive error logging with skipped row tracking
• Support for nodes with images only, body only, or both

What Gets Created

Content Type: PB Import Node

Fields:

• Title (Text) - Required
• Image (Image field with alt text and title) - Optional
• Tags (Entity reference to taxonomy, unlimited) - Optional
• Body (Text long, formatted with full_html) - Optional

Vocabulary: pb_import_node - Created automatically

Import Form Fields

Field Description Default Value CSV File Upload your CSV file (must have exact headers) Required Image Folder Relative Path Path to images inside files directory (e.g., gallery/products) Optional Content Type Machine name of content type to create pb_import_node Vocabulary Name Machine name of vocabulary for taxonomy terms pb_import_node

CSV File Format for Nodes

Required Headers (exact order and spelling):

csv_image_url,csv_node_title,csv_image_alt,csv_image_title,csv_node_tag,csv_node_body

Example CSV Content:

csv_image_url,csv_node_title,csv_image_alt,csv_image_title,csv_node_tag,csv_node_body
product1.jpg,Product Name,Product image,Product title,Featured|New,"<p>Product description here</p>"
,FAQ Question 1,,,FAQ,"<p>Answer to FAQ without image</p>"
product2.jpg,Another Product,Alt text,Image title,Sale,

CSV Column Mapping

CSV Column Maps To Notes csv_image_url Image field Filename only (e.g., image.jpg). Leave empty if no image. csv_node_title Node title Required. Must not be empty. csv_image_alt Image alt text Optional. Ignored if no image. csv_image_title Image title attribute Optional. Ignored if no image. csv_node_tag Taxonomy terms Use pipe (|) for multiple: Tag1|Tag2|Tag3 csv_node_body Body field HTML allowed. Uses full_html format.

Important: Each row must have a title and either an image OR body content (or both). Rows with only a title will be skipped.

Submodule: PB Import Para (Paragraphs)

The PB Import Para submodule creates complex, hierarchical paragraph structures for slideshows, accordions, and tabs from CSV files.

Features

• Multi-level paragraph creation with three-tier hierarchy (parent → section → target)
• Support for Slideshow, Accordion, and Tabs paragraph bundles
• Dynamic form that shows only available paragraph bundle types
• Hierarchical entity reference management with revision tracking
• HTML content support with full_html format
• Per-bundle taxonomy vocabularies

Required Paragraph Bundle Modules

Before importing paragraphs, you must enable the corresponding Paragraphs Bundles module:

Paragraph Type Required Module Installation Command Slideshow paragraph_bundle_slideshow drush en paragraph_bundle_slideshow -y Accordion paragraph_bundle_accordion drush en paragraph_bundle_accordion -y Tabs paragraph_bundle_tabs drush en paragraph_bundle_tabs -y

What Gets Created

Content Type: PB Import Para

Fields:

• Title (Text)
• Add Paragraph (Paragraph reference, unlimited) - For manual paragraph creation
• Referenced Paragraph (Entity reference to paragraph) - For referencing imported paragraphs

Paragraph Bundle: Target Bundle (pb_target_bundle)

Fields:

• Tag (Entity reference to taxonomy, unlimited)
• Image (Image field with alt text and title)
• Body (Text long, formatted with full_html)

Vocabularies Created:

• pb_slideshow_tag - For slideshow paragraph tags
• pb_accordion_tag - For accordion paragraph tags
• pb_tabs_tag - For tabs paragraph tags

Import Form Fields

Field Description Example Paragraph Type Select which paragraph bundle to create Slideshow / Accordion / Tabs CSV File Upload your CSV file (must have exact headers) Required Image Folder Relative Path Path to images inside files directory slideshow/homepage Parent Title Title for the main parent paragraph bundle Homepage Slideshow

CSV File Format for Paragraphs

Required Headers (exact order and spelling):

csv_image_url,csv_image_alt,csv_image_title,csv_target_title,csv_target_tag,csv_target_body

Example CSV Content:

csv_image_url,csv_image_alt,csv_image_title,csv_target_title,csv_target_tag,csv_target_body
slide1.jpg,First slide,Slide 1 title,Welcome Section,Featured,"<p>Welcome to our site</p>"
slide2.jpg,Second slide,Slide 2 title,Features Section,Featured|Popular,"<p>Our key features</p>"
,,,,Information,"<p>Text-only slide without image</p>"

CSV Column Mapping

CSV Column Maps To Notes csv_image_url Target bundle image field Filename only. Leave empty for text-only sections. csv_image_alt Image alt text Optional. Ignored if no image. csv_image_title Image title attribute Optional. Ignored if no image. csv_target_title Section title field E.g., "Slideshow Section Title" field in section bundle csv_target_tag Target bundle taxonomy tags Use pipe (|) for multiple: Tag1|Tag2 csv_target_body Target bundle body field HTML allowed. Uses full_html format.

Important: Each row must have either an image OR body content (or both). Rows with neither will be skipped.

Understanding Paragraph Hierarchy (3 Levels)

The import creates a three-level paragraph structure:

Level 1: Parent Bundle (e.g., slideshow_bundle)
         Field: "Slideshow Section" (paragraph reference)
         │
         ├─→ Level 2: Section Bundle (e.g., slideshow_section_bundle)
                      Fields: 
                      - "Slideshow Section Title" (text field)
                      - "Slideshow Section Body" (paragraph reference)
                      │
                      └─→ Level 3: Target Bundle (pb_target_bundle)
                                   Fields:
                                   - Tag (taxonomy reference)
                                   - Image (image field)
                                   - Body (text field)

How it works:

1. One parent paragraph is created with the title you specify (e.g., "Homepage Slideshow")
2. For each row in the CSV, a section paragraph is created containing the section title (from csv_target_title)
3. Inside each section, a target paragraph is created with the image, tags, and body content
4. All sections are automatically linked to the parent paragraph

Important Notes About Paragraph Import

Orphaned Paragraphs: After import, the created parent paragraph exists but is not attached to any node. To use it:

1. Go to Content → Add Content → PB Import Para
2. Create a new node
3. In the "Referenced Paragraph" field, select your imported parent paragraph
4. Save the node - your paragraph structure is now displayed

Alternative: You can also view all paragraphs at /admin/content/paragraphs/paragraphs-list and edit them individually.

Installation

Using Composer (Recommended)

composer require drupal/pb_import

Using Drush

# Enable all submodules
drush en pb_import pb_import_node pb_import_para -y

# Or enable individually
drush en pb_import -y          # Core module only
drush en pb_import_node -y     # Node import functionality
drush en pb_import_para -y     # Paragraph import functionality

# Clear cache
drush cr

Manual Installation

1. Download the module from the project page
2. Extract to modules/contrib/pb_import or modules/custom/pb_import
3. Enable via admin interface: Extend → Search for "PB Import" → Enable desired modules
4. Clear caches

Quick Start: Importing Nodes

1. Upload images via SFTP to sites/default/files/products/
2. Register files: Go to Content → PB Import → Register Uploaded Files, enter products, click "Register Files"
3. Prepare CSV: Create CSV file with correct headers and content
4. Import: Go to Content → PB Import → Import Nodes, upload CSV, set Image Folder to products
5. Review: Check Content page to verify imported nodes

Quick Start: Importing Paragraphs

1. Enable required module: drush en paragraph_bundle_slideshow -y
2. Register files (if using images) as described above
3. Prepare CSV: Create CSV file with correct headers and content
4. Import: Go to Content → PB Import → Import Paragraphs, select "Slideshow", upload CSV, enter Parent Title
5. Attach to node: Create or edit a node → Reference the imported parent paragraph in the paragraph field

Common Issues & Solutions

File not found during import

Problem: CSV import reports "File not found" errors

Solution:

• Ensure files were registered using the "Register Uploaded Files" form first
• Verify file names in CSV match exactly (case-sensitive)
• Check files exist at sites/default/files/[your-folder]/
• Confirm file extensions are supported (jpg, jpeg, png, gif, webp)

No paragraph bundle modules are enabled

Problem: Import form shows error message

Solution: Enable the required Paragraphs Bundles module:

drush en paragraph_bundle_slideshow -y
drush cr

CSV header validation fails

Problem: Import fails with header validation error

Solution: Ensure CSV headers match exactly (case-sensitive):

• For nodes: csv_image_url,csv_node_title,csv_image_alt,csv_image_title,csv_node_tag,csv_node_body
• For paragraphs: csv_image_url,csv_image_alt,csv_image_title,csv_target_title,csv_target_tag,csv_target_body

Path traversal error

Problem: "Path cannot contain .." error message

Solution: Use only alphanumeric characters, hyphens, underscores, and forward slashes. Examples:

• Valid: gallery/2024, products/summer-sale
• Invalid: ../../../etc/passwd, gallery/../files

Import succeeds but images don't display

Problem: Nodes created but images are broken

Solution: Check file permissions:

chmod 755 sites/default/files
find sites/default/files -type d -exec chmod 755 {} \;
find sites/default/files -type f -exec chmod 644 {} \;

CSV Best Practices

• Encoding: Use UTF-8 without BOM
• Line endings: Unix (LF) or Windows (CRLF) both work
• Delimiter: Comma (,) only
• Quotes: Use double quotes for fields containing commas: "This, has a comma"
• Escaping quotes: Double up quotes inside quoted fields: "This is a ""quoted"" word"
• Image paths: Use filenames only, not full paths: image.jpg not /sites/default/files/image.jpg
• Multiple tags: Separate with pipe character: Tag1|Tag2|Tag3
• HTML content: Wrap in quotes if it contains commas: "<p>Text with, comma</p>"

Requirements

Drupal Core

• Drupal 10.0 or higher
• Drupal 11.0 or higher

PHP

• PHP 8.1 or higher

Required Modules

• Entity Reference Revisions
• Paragraphs
• Paragraphs Bundles

☝️ Back to top

Developed by Alaa Haddad

Licensed under GPL v2 or later

A Personal Thank You for Your Support

Every project you see here, including this one, reflects countless hours of work driven by my passion for making Drupal better for everyone. Your support truly makes a difference, and there are a few simple ways you can help these projects grow and reach others who might benefit:

• Use & Share Feedback: Have you found this project (or any of my other work) helpful? Let me know what worked well or how it could be improved. Real user input drives better tools for the entire community.
• Click "Like" on Drupal.org: It may seem small, but liking this project on Drupal.org helps others discover and trust these tools.
• Spread the Word: Share these projects on social media, Slack groups, or anywhere Drupal folks connect. Your word of mouth helps these tools find the people who need them.
• Explore More of My Work: Check out my other projects on Drupal.org to see what else might support your workflow or inspire your next build.

W3CSS Theme (d8w3css) - Solo - W3CSS Paragraphs - Paragraphs Bundles - Amun - Amunet - Anhur - Acquia Purge Varnish - Cloudflare Purge - Reference Blocked Users - Solo Copy Blocks - Solo Utilities - PB Import - VVJA - Accordion - VVJC - 3D Carousel - VVJB - Basic Carousel - VVJF - 3D FlipBox - VVJH - Hero - VVJL - Lightbox - VVJP - Parallax - VVJR - Reveal - VVJS - Slideshow - VVJT - Tabs - Module Matrix - Selectify - Utilikit

If you have any questions, ideas, or feedback about my Drupal.org projects, I’d love to hear from you! To keep things open and helpful for the entire community, I encourage you to post directly in the project's issue queue on Drupal.org. This way, your questions and the answers can benefit others who may have the same needs.

At the end of the day, my goal is to make Drupal easier and more enjoyable for everyone, especially small businesses and site builders who want to create professional sites without extra hassle. Together, we can build something even better. Thank you for your support, and for being part of this journey!