Technical documentation for developers integrating with the plugin
Overview #
This guide provides technical information for developers who want to extend, customize, or integrate with Submittal & Spec Sheet Builder. It covers the REST API, WordPress hooks, template overrides, and advanced customization options.
Target Audience:
- Theme developers
- Plugin developers
- Technical implementers
- Advanced users with coding experience
REST API #
The plugin exposes a comprehensive REST API for accessing and managing product data.
API Base URL #
Authentication #
Public Endpoints:
- Product retrieval (GET requests)
- No authentication required
Protected Endpoints:
- Product creation/editing (POST, PUT, DELETE)
- Requires authentication via nonce or OAuth
Available Endpoints #
Get All Nodes (Product Tree)
GET /wp-json/sfb/v1/nodes
Returns complete product hierarchy with all categories, products, types, and models.
Get Single Product
GET /wp-json/sfb/v1/nodes/{composite_key}
Example: GET /wp-json/sfb/v1/nodes/c-studs:steel-studs:20-gauge:362s162-20
Create Node
POST /wp-json/sfb/v1/nodes
Create new product, type, product, or category with POST request containing name, type, parent, and specs.
Update Node
PUT /wp-json/sfb/v1/nodes/{composite_key}
Update existing node with new name, specs, or other properties.
Delete Node
DELETE /wp-json/sfb/v1/nodes/{composite_key}
Delete product or node from hierarchy.
Search Products
GET /wp-json/sfb/v1/search?q={query}
Example: GET /wp-json/sfb/v1/search?q=362
Returns all products matching search query.
Get Field Definitions
GET /wp-json/sfb/v1/field-definitions
Returns current specification field names and types.
Using the API #
Example: Fetch All Products
Fetch all products and log them to console.
Example: Search Products
Search for products matching a query string.
Example: Create Product
Create new product with POST request, including nonce for security.
WordPress Hooks #
The plugin provides numerous hooks for customization.
Action Hooks #
After PDF Generated
do_action('sfb_pdf_generated', $pdf_path, $product_ids, $project_name);
Fires after PDF is successfully generated. Use to send notifications, log data, or trigger workflows.
Before Product Created
do_action('sfb_before_product_create', $product_data);
Fires before new product added to catalog. Use to validate or modify product data.
After Product Created
do_action('sfb_after_product_create', $product_id, $product_data);
Fires after product successfully added to database.
Before Settings Saved
do_action('sfb_before_settings_save', $settings);
Fires before settings saved to database.
Filter Hooks #
Modify PDF Output
apply_filters('sfb_pdf_html', $html, $products, $branding);
Use to add watermarks, modify layout, insert custom content into PDFs.
Modify Product Data
apply_filters('sfb_product_data', $product, $composite_key);
Use to add custom fields or modify product information displayed to users.
Modify Search Results
apply_filters('sfb_search_results', $results, $query);
Use to boost certain products, reorder results, or filter search output.
Modify Branding Settings
apply_filters('sfb_branding_settings', $branding);
Use to dynamically change logo, colors, or company info based on conditions.
Customize PDF Filename
apply_filters('sfb_pdf_filename', $filename, $project_name, $timestamp);
Use to customize PDF filename format or add prefixes/suffixes.
Template Overrides #
Customize the frontend builder appearance by overriding templates in your theme.
Template Hierarchy #
Plugin templates located in:
wp-content/plugins/submittal-spec-sheet-builder/templates/
Override in your theme:
wp-content/themes/your-theme/submittal-builder/
Available Templates #
Main Builder Template – templates/builder.php
Override in: your-theme/submittal-builder/builder.php
Product Card – templates/partials/product-card.php
Override in: your-theme/submittal-builder/partials/product-card.php
Product List Row – templates/partials/product-row.php
Review Panel – templates/partials/review-panel.php
PDF Cover Page – templates/pdf/cover.php
PDF Table of Contents – templates/pdf/toc.php
PDF Spec Sheet – templates/pdf/spec-sheet.php
Example Template Override #
Create a custom product card by overriding the template with your own HTML and PHP markup.
Extending Functionality #
Add Custom Product Fields #
Example: Add “Manufacturer” field
Use filter hook to add custom fields to product data structure.
Custom PDF Sections #
Example: Add compliance section
Insert custom HTML content into PDF by modifying PDF HTML filter.
Integrate with Third-Party Services #
Example: Send data to CRM
After PDF generation, send product data to external CRM or API endpoint using wp_remote_post.
JavaScript API #
Interact with the builder via JavaScript on frontend pages.
Global Objects #
sfbData
Localized script data available on frontend builder pages with AJAX URL, nonce, REST URL, settings, and branding info.
Events #
Product Selected
document.addEventListener('sfb:product-selected', function(event) { ... });
Fired when user selects a product.
Product Deselected
document.addEventListener('sfb:product-deselected', function(event) { ... });
Fired when user deselects a product.
PDF Generation Started
document.addEventListener('sfb:pdf-generating', function(event) { ... });
Fired when PDF generation begins.
PDF Generation Complete
document.addEventListener('sfb:pdf-complete', function(event) { ... });
Fired when PDF is ready for download.
Methods #
Get Selected Products – window.SFB.getSelected();
Select Product Programmatically – window.SFB.selectProduct('composite-key');
Deselect Product – window.SFB.deselectProduct('composite-key');
Clear All Selections – window.SFB.clearSelections();
Generate PDF – window.SFB.generatePDF({products: ['key1', 'key2'], project: 'Project Name'});
CSS Customization #
Override default styles for complete design control.
CSS Classes #
.sfb-builder – Main builder wrapper
.sfb-product-grid – Product card container
.sfb-product-card – Individual product card (with .selected state)
.sfb-search – Search input
.sfb-filters – Filter container
Example: Custom Styling #
Add custom CSS to your theme’s style.css to override default product card styles, search box, and other UI elements.
Code Examples #
Example 1: Automatic Email After PDF Generation #
Send notification email to sales team when PDF is generated with project name and product count.
Example 2: Add Custom Data to Products #
Fetch stock status from external API and add it to product data for display in frontend.
Example 3: Custom PDF Watermark (Pro Users Only) #
Add “SAMPLE” watermark to PDFs for non-logged-in users using CSS and HTML modification.
Example 4: Integrate with Google Analytics #
Track product selections and PDF generations in Google Analytics using custom events.
Security Considerations #
Sanitization #
Always sanitize data when extending the plugin using sanitize_text_field(), sanitize_email(), and esc_url_raw().
Nonce Verification #
Verify nonces for all form submissions and AJAX requests using wp_verify_nonce().
Capability Checks #
Check user capabilities before allowing actions using current_user_can() with appropriate capability string.
Performance Optimization #
Caching #
Use WordPress transients for expensive operations like fetching product data to improve performance.
Lazy Loading #
Lazy load product images using HTML5 loading attribute or JavaScript to improve page load times.
Additional Resources #
Official Documentation #
- Complete API Reference
- WordPress Hooks Reference
- UI Customization Guide
External Resources #
- WordPress Plugin Handbook: https://developer.wordpress.org/plugins/
- REST API Handbook: https://developer.wordpress.org/rest-api/
- WordPress Coding Standards: https://developer.wordpress.org/coding-standards/
