47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
# 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 `<input type="number">` 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": "<!-- Standard Kadence 2-Column Row Block -> Column 1 (Label + Input) -> Column 2 (Label + Input) -> SEO Text Block -->"
|
|
}
|
|
```
|
|
|
|
### 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 `<script>...</script>`.
|
|
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":[<CALCULATOR_POST_ID>],"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.*
|