diff --git a/agents/readme.md b/agents/readme.md new file mode 100644 index 0000000..2ac35ea --- /dev/null +++ b/agents/readme.md @@ -0,0 +1,46 @@ +# How Do You Convert - Agents Documentation + +This document explicitly defines the schema, architecture, and standard operating procedure for creating new calculators on `howdoyouconvert.com`. + +## 1. WordPress Environment Structure +The calculators are managed using the custom post type `calculator`. The REST API endpoint allows full CRUD operations: +- **Base Endpoint**: `/wp-json/wp/v2/calculator` +- Authentication is handled via Application Passwords `base64(username:password)` utilizing Basic Auth via HTTP Headers. +- *Crucial Node*: API requests to this endpoint must emulate browser requests via the `User-Agent` string (e.g., `Mozilla/5.0...`) or they will be blocked by Cloudflare (error 1010). + +## 2. Calculator Data Payload (HTML) +Calculators should use Kadence Block layout components to match the pre-existing grid on the site. Each calculator contains 2 main columns for bidirectional conversion. +All calculators *MUST* include the classes `calc-input` and `calc-field` on their `` tags, and unique IDs across the form (e.g. `input-1`, `input-2`). The UI should contain explicit labels. + +**Example JSON Payload Configuration:** +```json +{ + "title": "Unit A to Unit B", + "status": "publish", + "slug": "unita-to-unitb", + "content": "" +} +``` + +### 2.1. SEO Copy Guidelines +The SEO block appended at the end of the calculator `content` must strictly adhere to the following style: +- **Length**: Expand the text to 2-3 detailed paragraphs providing educational information on the units involved, their history, uses, and the conversion methodologies. +- **Tone**: The text must be strictly informative and **non-self-referential**. Do not refer to the calculator widget itself. Sentences like "This handy calculator automatically converts values as you type" or "Enter your value below" are explicitly prohibited. + +## 3. JavaScript Event Injection +The JavaScript that performs the actual mathematical conversion is *detached* from the calculator post itself. It is managed via the **Kadence Elements** system (`kadence_element` custom post type). + +### Creating the Logic Hook +Whenever a new calculator is created: +1. Capture the returned `id` of the published calculator. +2. Formulate the JS math conversion script wrapping events to the unique input IDs. +3. **CRITICAL: URL Parameter Support:** Ensure the script listens to the DOM `DOMContentLoaded` event and parses the `window.location.search` URL query parameters for `?v1=` (Input 1) and `?v2=` (Input 2). If present, the corresponding input must be automatically populated and the calculation function triggered. +4. Submit a new `kadence_element` POST request injecting the ``. +5. Apply these required metadata values so it correctly loads on your specific calculator: + - `_kad_element_hook`: `kadence_after_header` + - `_kad_element_show_conditionals`: `'[{"rule":"singular|calculator","select":"ids","ids":[],"mustMatch":false}]'` + +## 4. Calculator Registry +To avoid unnecessary scraping of the REST API, immediately update the `calculators_list.md` file located in the workspace directory with the details (Title, Post ID, Kadence Element ID) upon successful deployment. + +*By adhering to these steps, all calculators will natively match the design and function gracefully without requiring direct plugin access.* diff --git a/calculators.md b/calculators.md new file mode 100644 index 0000000..5d95d8e --- /dev/null +++ b/calculators.md @@ -0,0 +1,6 @@ +# Current Calculators on How Do You Convert + +Here is a list of all current calculators available on the site: + +1. **[Kilograms to Pounds](https://howdoyouconvert.com/calculator/kilograms-to-pounds/)** +2. **[Inches to Feet](https://howdoyouconvert.com/calculator/inches-to-feet/)** diff --git a/calculators_list.md b/calculators_list.md new file mode 100644 index 0000000..7ad748f --- /dev/null +++ b/calculators_list.md @@ -0,0 +1,10 @@ +# Active Calculators Registry + +This document lists all active calculators on `howdoyouconvert.com`. +Whenever a new calculator is published via the REST API, it must be appended here including its matching Javascript element ID. + +| Calculator Name | Page Post ID | Kadence JS Element ID | Slug | Conversion Factor | +| :--- | :--- | :--- | :--- | :--- | +| Inches to Feet | 16 | 57 | inches-to-feet | 12 | +| Kilograms to Pounds | 54 | 28 | kilograms-to-pounds | 0.453592 | +| Miles to Kilometers | 102 | 103 | miles-to-kilometers | 0.62137119 | diff --git a/test.txt b/test.txt deleted file mode 100644 index 9daeafb..0000000 --- a/test.txt +++ /dev/null @@ -1 +0,0 @@ -test diff --git a/upload_calculator.py b/upload_calculator.py deleted file mode 100644 index c8e3870..0000000 --- a/upload_calculator.py +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env python3 -"""Upload a Miles to Kilometers calculator to WordPress via REST API.""" -import urllib.request -import urllib.error -import json -import base64 - -url = "https://howdoyouconvert.com/wp-json/wp/v2/calculator" -creds = base64.b64encode(b"ben:6YGf wVxu gBpz pkqx BGZO lfVP").decode("utf-8") - -content = ( - '' - '
' - '
' - '\n\n' - '
\n' - '\n\n' - '\n' - '
\n\n\n' - '\n' - '
\n' - '\n' - '
\n\n' - '
' -) - -data = json.dumps({ - "title": "Miles to Kilometers", - "status": "publish", - "slug": "miles-to-kilometers", - "content": content, -}).encode("utf-8") - -req = urllib.request.Request(url, data=data, method="POST") -req.add_header("Content-Type", "application/json") -req.add_header("Authorization", "Basic " + creds) - -try: - resp = urllib.request.urlopen(req) - result = json.loads(resp.read().decode("utf-8")) - print("SUCCESS:", result.get("link")) - print("ID:", result.get("id")) -except urllib.error.HTTPError as e: - print("HTTP Error:", e.code) - print(e.read().decode("utf-8")[:500]) -except Exception as e: - print("Error:", e)