Turtle Template Form Knitter Development

ver-1.0.7

First fork the https://turtleengr.github.io/WP-turtle-template-form-knitter/ repository.

Requirements for building

Packages

Install these packages

• emacs (org-mode) - if you want to edit the *.org files
• git
• git-flow - optional
• make
• pandoc - convert org files to markdown format
• perl - for the pod2* programs. Needed by org2html.sh
• php
• pod2markdown - libpod-markdown-perl pkg
• pod2pdf - optional
• sed
• tidy - needed by org2html.sh
• zip

Custom Scripts

The scripts in ./bin and are used in Makefile

• bin/org2html.sh - convert org files to html
• bin/rm-trailing-sp - an convert tabs to spaces
• bin/pre-commit - enforces some basic formatting (see [gitproj "hook"])

Copy bin/pre-commit to WP-turtle-template-form-knitter/.git/hooks

git config

• Append contents of ./bin/gitconfig to ./.git/config

[alias]
    br = branch
    ci = commit
    co = checkout
    df = diff
    st = status -s

[gitproj "hook"]
    verbose = true
    pre-commit-enabled = true
    check-file-names = true
    check-in-raw = true
    check-whitespace = true
    check-for-tabs = true
    tab-include-list = .sh .inc .pod .md .php
    tab-exclude-list = Makefile .phar
    check-for-big-files = true
    binary-file-size = 40k

• If using git-flow, first time setup, run:
  • git flow init

To Build

Modify the Makefile

Define the location of where the plugin's zip file will be saved.

mServer = example.com
mPubDev = /rel/development/$(mProj)
mPubRel = /rel/released/$(mProj)

Build steps

=make=

• This will verify the required packages and files exist.
• Then it will list the main steps to make and deploy the plugin.

=make update=

• Pull the latest develop branch from github

=make build=

• Create a branch, if there are major changes
• Build the zip file in the dist/ dir
• Change files and repeat until it is worth saving

=make save=

• Save a development version for testing.
• Checkin all changes, push to github
• Publish to the release server (change mServer to your release server).

=make publish=

• This can only be done on the develop branch (i.e. merged branches)
• Save a stable (tested) development version
• Tag the version, push to develop
• Merge develop to main

=make release=

• if accepted by WordPress.org TBD
• copy the relevant files to SVN…

How it works

• For details on how this code was generated by Claude, with references to the existing plugins it needs, see the files in the spec/ directory. Note: this plugin was initially named "contact-2-post."

• The "save image upload" code was referenced from https://wordpress.org/plugins/store-file-uploads-for-contact-form-7/ by Mircea N. (version 1.3.0). That code was then enhanced to normalize the image file names and to prevent overwriting existing images.

• The post's author is the user with the site's admin_email.

• If publish-date is valid, the date is fixed (post_date_gmt is set), so publishing keeps it; a future date makes the post "Scheduled". If there is no valid publish-date, the post date "floats": it is set when the post is published.

• ttfk_fOnBeforeCf7SendMail() is hooked to wpcf7_before_send_mail. It saves each uploaded image with ttfk_fCreateAttachment(), and collects the attachment IDs with ttfk_fSaveAttachId().

• Upload error messages are saved with ttfk_fErrorLog(). Calling ttfk_fErrorLog() with no argument returns the list. The list is a static variable, and each form submission is one PHP request with its own memory, so a post only gets the errors from its own submission, even when several people submit at the same time. The messages are not kept after the request ends.

• These filters can change how uploads are saved: ttfk_fCreateAttachment_file_name (the destination path), ttfk_should_skip_save_attachment_to_media_library (return true to only copy the file), and ttfk_before_insert_attachment (the attachment array).

• Flamingo saves the message in wpcf7_submit, then fires wpcf7_after_flamingo with flamingo_inbound_id. This plugin hooks that action, so no post is made when Flamingo does not store the message (do_not_store: true), or for spam.

• The form's "create_post" and "post_template" Additional Settings are read with WPCF7_ContactForm::is_true() and pref().

• The template page is split with parse_blocks(). Attribute blocks are removed, {field} is replaced only in the block HTML (not in the block comment JSON), then serialize_blocks().

Function Outline

Call tree of the functions in turtle-template-form-knitter.php, in the order they run when a Contact Form 7 form is submitted.

Indent = "calls". Functions without a ttfk_ prefix are WordPress, CF7, Flamingo, or PHP functions, listed only where they matter to the flow.

(recursive) marks a function that calls itself.

0. Setup (every page load, before any submission)

plugins_loaded (anonymous function)

• If WPCF7 or Flamingo_Inbound_Message is missing:

add_action admin_notices -> error notice; no hooks below are added.

• add_action wpcf7_before_send_mail -> ttfk_fOnBeforeCf7SendMail
• add_action wpcf7_after_flamingo -> ttfk_fAfterFlamingo
• add_filter wpcf7_feedback_response -> ttfk_fFeedbackResponse
• add_action wpcf7_enqueue_scripts -> ttfk_fEnqueuePasteScript

add_filter plugin_row_meta -> ttfk_fMetaLinks (always added)

add_action admin_init -> ttfk_fMakeAttachMeta (always added)

1. Form page is shown (before submit)

wpcf7_enqueue_scripts

• ttfk_fEnqueuePasteScript

wp_enqueue_script js/ttfk-paste.js (cleans pasted HTML in textareas; shows ttfk_errors popup)

2. Form is submitted (one request, hooks fire in this order)

2.1 wpcf7_before_send_mail - save uploaded images

ttfk_fOnBeforeCf7SendMail

• WPCF7_Submission::get_instance()->uploaded_files()
• ttfk_fCreateAttachment (once per uploaded file)

wp_check_filetype, wp_get_image_mime (image checks)

ttfk_fErrorLog (on any failure)

ttfk_fNormalizeFileName

apply_filters ttfk_fCreateAttachment_file_name

ttfk_fUniqueFileName

copy() to uploads dir

apply_filters ttfk_should_skip_save_attachment_to_media_library

apply_filters ttfk_before_insert_attachment

wp_insert_attachment (on failure: ttfk_fErrorLog, wp_delete_file)

add_post_meta _ttfk_need_meta (image sizes are made later, see 3)

ttfk_fSaveAttachId (stores the ID in a static list)

2.2 wpcf7_after_flamingo - create the pending post

ttfk_fAfterFlamingo

• Return early if: no Flamingo/form ID, spam, or form option create_post is not true.
• Get template page from form option post_template

ttfk_fErrorLog (not set / page not found)

• new Flamingo_Inbound_Message -> fields
• Build HTML field list from textarea form tags
• ttfk_fSaveAttachId() (read the IDs saved in 2.1)
• ttfk_fCreatePost

parse_blocks(template)

for each top-level block:

• ttfk_fGetAttrLines (ATTR-BEGIN … ATTR-END lines)

ttfk_fReplaceFields (plain text, see 2.4)

• ttfk_fReplaceInBlock (recursive, for innerBlocks)

ttfk_fSplitParagraph (core/paragraph only)

• ttfk_fBlockHtmlValue

ttfk_fValueToString

ttfk_fCleanHtml

• ttfk_fTextBlock

ttfk_fReplaceFields (HTML, see 2.4)

• ttfk_fHtmlToBlocks (see 2.5)

ttfk_fReplaceFields (HTML, see 2.4)

ttfk_fReplaceInBlock (each inner block)

ttfk_fErrorLog (ATTR-END not found)

ttfk_fGetAdminId (post author)

serialize_blocks

ttfk_fParseDate (publish-date)

wp_insert_post (status pending) (on failure: ttfk_fErrorLog)

ttfk_fGetTermIdList (categories, then tags)

• wp_set_object_terms

ttfk_fParseDate, ttfk_fParseTime (expire-date, expire-time)

• update_post_meta _njtape_expiration_date
• ttfk_fErrorLog (invalid expire-date)

for each saved attachment ID:

• wp_update_post (post_parent = new post)
• set_post_thumbnail (first image only)

2.3 wpcf7_feedback_response - report errors to the browser

ttfk_fFeedbackResponse

• ttfk_fErrorLog() (read the list saved during 2.1 and 2.2)
• Adds ttfk_errors to the JSON reply (shown by js/ttfk-paste.js)

2.4 Shared: ttfk_fReplaceFields

ttfk_fReplaceFields ({field} -> value, single pass)

• ttfk_fValueToString
• if plain text: return value
• if HTML:

ttfk_fCleanHtml (only for textarea fields)

no tags: esc_html, nl2br, encode [ ]

has tags:

• ttfk_fLoadHtml
• ttfk_fNodeHtml (see 2.5)

2.5 Shared: HTML -> blocks helpers

ttfk_fHtmlToBlocks

• ttfk_fLoadHtml
• ttfk_fNodeHtml (recursive)

ttfk_fTidyInline

• ttfk_fTidyInline
• ttfk_fParagraphBlock

ttfk_fMakeBlock

• ttfk_fListBlock (recursive, nested ul/ol)

ttfk_fNodeHtml

ttfk_fTidyInline

ttfk_fMakeBlock (core/list-item, core/list)

• ttfk_fMakeBlock (core/heading)

3. Admin pages (not part of a submission)

admin_init (any admin page)

• ttfk_fMakeAttachMeta (up to 10 attachments per page load)

get_posts (attachments with meta _ttfk_need_meta)

delete_post_meta _ttfk_need_meta

wp_generate_attachment_metadata, wp_update_attachment_metadata

plugin_row_meta (Plugins page)

• ttfk_fMetaLinks (Documentation and Support links)

4. Dependency order (leaves first)

Each function only depends on functions above it in this list.

1. ttfk_fErrorLog
2. ttfk_fSaveAttachId
3. ttfk_fValueToString
4. ttfk_fNormalizeFileName
5. ttfk_fUniqueFileName
6. ttfk_fParseDate
7. ttfk_fParseTime
8. ttfk_fGetAdminId
9. ttfk_fGetTermIdList
10. ttfk_fCleanHtml
11. ttfk_fTidyInline
12. ttfk_fLoadHtml
13. ttfk_fMakeBlock
14. ttfk_fNodeHtml (self)
15. ttfk_fParagraphBlock (13)
16. ttfk_fListBlock (self, 11, 13, 14)
17. ttfk_fHtmlToBlocks (11-16)
18. ttfk_fReplaceFields (3, 10, 12, 14)
19. ttfk_fBlockHtmlValue (3, 10)
20. ttfk_fTextBlock (18)
21. ttfk_fSplitParagraph (17, 19, 20)
22. ttfk_fReplaceInBlock (self, 18, 21)
23. ttfk_fGetAttrLines (18)
24. ttfk_fCreateAttachment (1, 2, 4, 5)
25. ttfk_fCreatePost (1, 6-9, 22, 23)
26. Hook entry points:

ttfk_fOnBeforeCf7SendMail (24)

ttfk_fAfterFlamingo (1, 2, 25)

ttfk_fFeedbackResponse (1)

ttfk_fEnqueuePasteScript

ttfk_fMetaLinks

ttfk_fMakeAttachMeta

Notes

This outline traces a submission through three hooks, in the order they run in the same request:

1. wpcf7_before_send_mail: saves the uploaded images.
2. wpcf7_after_flamingo: builds the pending post from the template page.
3. wpcf7_feedback_response: adds any saved errors to the reply sent to the browser.

The outline also has:

a short setup section (plugins_loaded, plus the script loaded when the form page is shown);

separate sections for the two shared helpers, ttfk_fReplaceFields and the HTML-to-blocks functions;

a numbered list of every function with its dependencies listed before it, so the simplest functions come first.

All 31 ttfk_ functions in turtle-template-form-knitter.php are reachable from a hook. Three of them call themselves: ttfk_fReplaceInBlock, ttfk_fListBlock and ttfk_fNodeHtml.

Test

test/setup.php and test/submit.php are run with wp-cli on a test site with all the plugins active. They are not in the dist zip.

wp eval-file test/setup.php
wp eval-file test/submit.php full attach   # post, attachment, expiry
wp eval-file test/submit.php notitle       # title UNDEFINED
wp eval-file test/submit.php nostore       # no post
wp eval-file test/submit.php nocreate      # no post
wp eval-file test/submit.php badslug       # no post, error_log
wp eval-file test/submit.php full spam     # no post
wp post list --post_type=post --post_status=pending