Developer reference

This is the Developers section of the help desk. Everything here is a public, supported extension point; anything not listed is internal and may change.

1. Template overrides

Copy any file from the plugin’s templates/ folder into your theme (or child theme) under scrumptious/, keeping the same path. Your copy wins.

Parts are shared by the full Recipe Card, the Recipe Part blocks and the recipe page template, so one override changes the section everywhere.

Variables in recipe-card.php: $recipe (recipe data), $ctx (images, url, terms, rating), $recipe_id, $title, $class (extra classes), $show (section visibility), $style (full|compact|minimal), $print_url, $features (scale|units|cook|rate), $rating (['average','count'] or null).

Variables in parts: $recipe, $recipe_id, $rating, $print_url.

Keep the swp-* class names and data-* attributes if you want scaling, unit conversion, check-off and ratings to keep working — the script finds elements by them (.swp-card, .swp-ingredient[data-amount], .swp-ingredient__amount, .swp-ingredient__unit, .swp-step, .swp-rating).

To load templates from a plugin instead of a theme, use the scrumptious_template filter (below).

Tip: when the plugin updates a template, check your override against the new version. Template changes are listed in the changelog.

2. Recipe data

$recipe is the normalized recipe array:

[
  'summary'            => '',            // HTML (kses)
  'servings'           => 4,
  'servings_unit'      => 'cookies',
  'times'              => [ 'prep' => 15, 'cook' => 10, 'rest' => 0, 'total' => 25 ], // minutes
  'ingredient_groups'  => [ [ 'title' => '', 'items' => [ [ 'raw','amount','amount_value','amount_max','unit','unit_key','name','notes','link' ] ] ] ],
  'instruction_groups' => [ [ 'title' => '', 'steps' => [ [ 'text','image_id','timer' ] ] ] ],
  'notes'              => '',
  'video_url'          => '',
  'keywords'           => '',
  'nutrition'          => [ 'calories' => '', ... ],
  'gallery'            => [ 45, 46 ],        // attachment IDs
  'source_url'         => '',                // "Adapted from" link
  'source_name'        => '',
]

Read it anywhere with Scrumptious\Recipe::get( $recipe_id ). Stored in post meta _swp_recipe (JSON) on the swp_recipe post type; also exposed over the REST API as meta._swp_recipe.

Taxonomies: swp_course, swp_cuisine, swp_diet.

3. PHP filters

4. PHP actions

Part names: summary, rating, meta, ingredients, instructions, notes, gallery, share, nutrition, actions.

Example — an affiliate “Shop the ingredients” box after the ingredients:

add_action( 'scrumptious_after_part_ingredients', function ( $recipe_id ) {
	echo '<p class="my-shop-link"><a href="/shop/?recipe=' . (int) $recipe_id . '">Shop the ingredients</a></p>';
} );

5. JavaScript events

Every card dispatches bubbling DOM events, so you can listen on document:

document.addEventListener( 'scrumptious:rated', ( e ) => {
	window.gtag && gtag( 'event', 'recipe_rated', { value: e.detail.rating } );
} );

Editor filters (wp.hooks) let you add input types to Paste & Parse. Scrumptious Pro uses them for Import from a link.

6. Styling

Cards use CSS custom properties; override them in your theme:

.swp-card, .swp-grid, .swp-jump {
	--swp-accent: #2b8a3e;  /* buttons, headings, step numbers, stars */
	--swp-muted: #5c5f66;
	--swp-border: #eee4e9;
	--swp-bg: #fff;
	--swp-radius: 14px;
}

The accent can also be set in Recipes → Settings. The default is Raspberry #e11d74 on a white card (4.5:1 contrast with white text). If you pick your own accent, check that white text on it stays readable. Style variants add .swp-card--compact / .swp-card--minimal; cook mode adds .is-cooking; checked-off items get .is-done.

7. Blocks and templates

• Blocks: scrumptious/recipe, scrumptious/jump, scrumptious/recipe-part (attribute part), scrumptious/recipe-grid. All are dynamic (server-rendered), so theme overrides apply to them.
• With public recipe pages on, block themes get Single Recipe (single-swp_recipe) and Recipe Index (archive-swp_recipe) templates, editable in the Site Editor. Classic themes can add single-swp_recipe.php / archive-swp_recipe.php as usual.
• Shortcode fallbacks: [scrumptious id="123"] and [scrumptious-jump label="" print="1"].

Scrumptious Pro (add-on)

| scrumptious_submission_data | $data, $fields | Change a submitted recipe before it’s saved. | | scrumptious_recipe_submitted (action) | $recipe_id, $fields | A submission was saved as a Pending recipe. | | scrumptious_submission_handled (action) | $recipe_id, $code, $fields | Every submit attempt, with $code ” or an error (spam, rate, missing…). | | scrumptious_submission_admin_email / scrumptious_submission_published_email | $email, $recipe_id | Change or cancel (to = ”) the emails. | | scrumptious_submit_form_context | $context | Template variables for the form. |

| scrumptious_bulk_ai_prompt / scrumptious_bulk_ai_changes | $prompt, $tasks / $changes, $recipe_id, $ai | Change the Bulk AI instructions, or adjust/skip changes before they’re saved. | | scrumptious_bulk_ai_processed (action) | $recipe_id, $changes | After Bulk AI changed a recipe. |

| scrumptious_meal_plan_button / scrumptious_meal_plan_url / scrumptious_meal_plan_browse_url | $show, $recipe_id / $url / $url | Meal planner: show the card button, its target page, the empty-plan browse link. | | scrumptious_import_url_max_image | $bytes | Largest photo Import from a link copies (default 10 MB). | | scrumptious_meal_plan_search_args | $args, $q | Meal planner: the WP_Query args behind a day’s + Add a recipe search. | | scrumptious_pro_support_email / scrumptious_pro_support_details / scrumptious_pro_support_mail | $email / $details / $mail | Priority support (Recipes → Support): where messages go (an agency can route them to itself), the site details attached, and the email before it’s sent. | | scrumptious_pro_support_sent (action) | $ok, $mail | After a support message was sent, or failed. | | scrumptious_shopping_list / scrumptious_shopping_aisles / scrumptious_shopping_list_url | $list, $recipes / $rules / $url | Shopping list: change the finished list, the aisle rules, the page the meal plan links to. | | scrumptious_url_import_result | $result, $url, $node | Adjust an Import from a link result (Pro) ($node is the schema.org Recipe found on the page, or null). | | scrumptious_import_url_ai_terms | $fill (bool, default true) | Return false to stop Import from a link (Pro) asking AI for a course, cuisine or diet the page left out. |

REST (Pro): GET /scrumptious-pro/v1/plan-recipes?ids=1,2 (anyone), GET /scrumptious-pro/v1/plan-search?q= (anyone; newest when empty), GET\|POST /scrumptious-pro/v1/meal-plan (logged-in users), POST /scrumptious-pro/v1/shopping-list { items: [ { id, servings } ] } (anyone; published recipes only), POST /scrumptious-pro/v1/import-url { url, photo, credit } (users who can edit posts; returns { title, recipe, source: 'schema'|'ai'|'basic', notice, terms, image_id }).

Template: {theme}/scrumptious/submit-recipe.php. DOM event: scrumptious:submitted.

PHP: Scrumptious_Pro\Plan::tier() and Scrumptious_Pro\Plan::can( 'submit_recipe' ).

8. REST API

PHP: Scrumptious\Recipe_Parser::parse( $text ) (no AI), Scrumptious\Parse_Api::parse( $text, 'auto' ) (AI when set up), Scrumptious\Tagger::suggest( $title, $recipe ) (AI course/cuisine/diet) and Scrumptious\Tagger::ids( [ 'swp_course' => [ 'Main' ] ] ) (names to term IDs, matching existing terms loosely and creating missing ones).

9. SEO model

• Public recipe pages off: the recipe lives in the post that shows it. That post gets the Recipe JSON-LD and is the recipe’s URL.
• Public recipe pages on: the recipe page (/recipe/slug/) is the primary page. It is self-canonical and is the only page that outputs the Recipe JSON-LD. Blog posts can still show the card, but don’t repeat the recipe data, so Google sees one recipe at one URL.