Hanson.xyz Dev
351 lines
10 KiB
Markdown
351 lines
10 KiB
Markdown
# HomeProz WordPress Website Development
|
|
|
|
## Project Overview
|
|
|
|
**Client:** HomeProz Real Estate (Albert Lea, MN area)
|
|
**Developer:** Hanson.xyz
|
|
**Contract:** $6,000 development + $600/yr hosting
|
|
|
|
**Goal:** Build a custom WordPress theme with ACF-powered property listing system, replacing their current GoDaddy Website Builder site while maintaining their dark/rust brand aesthetic.
|
|
|
|
## Reference Documents
|
|
|
|
All planning documents located in:
|
|
`/var/www/html/contract/Contracts/WordPress-Website/_scratch/site_analysis/`
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| `DESIGN-DOCUMENT.md` | Visual design specs, colors, typography, layouts, all template specifications |
|
|
| `IMPLEMENTATION-PLAN.md` | Technical architecture, ACF fields, CPT structure, phase breakdown |
|
|
| `homepage-full.png` | Screenshot of existing site (full page) |
|
|
| `homepage-viewport.png` | Screenshot of existing site (above fold) |
|
|
|
|
Contract documents in parent directory:
|
|
- `CONTRACT-AT-A-GLANCE.txt`
|
|
- `DRAFT-HomeProz-WordPress-Website-Contract.txt`
|
|
|
|
---
|
|
|
|
## Development Mandates
|
|
|
|
### Communication & Output
|
|
|
|
1. **No emojis** - Never use emojis in code, website output, commit messages, documentation, or conversation. This is a professional project.
|
|
|
|
### UI & Styling
|
|
|
|
1. **Use Tailwind CSS** as the UI framework
|
|
2. **Use SCSS** for custom styles, compiled via Vite
|
|
3. **Page-scoped SCSS**: Every page-specific SCSS file must be wrapped:
|
|
```scss
|
|
.The_Page_Name {
|
|
// all rules for this page go here
|
|
}
|
|
```
|
|
4. **Page body classes**: Every page template must add a class to the `<body>` tag:
|
|
```php
|
|
<body class="Home_Page">
|
|
<body class="Properties_Archive">
|
|
<body class="Single_Property">
|
|
<body class="About_Page">
|
|
<body class="Contact_Page">
|
|
<body class="Blog_Archive">
|
|
<body class="Single_Post">
|
|
```
|
|
|
|
### JavaScript
|
|
|
|
1. **Use jQuery** for all JS functionality
|
|
2. **Page-scoped JS**: All page-specific JS must start with early return:
|
|
```javascript
|
|
(function($) {
|
|
if (!$('.The_Page_Name').length) return;
|
|
|
|
// page-specific code here
|
|
})(jQuery);
|
|
```
|
|
3. **No inline scripts** - all JS in external files
|
|
4. **No inline event handlers** - use jQuery event binding
|
|
5. **Use Vite** to bundle JS/CSS
|
|
|
|
### File Organization
|
|
|
|
1. **Co-locate related files** - JS and SCSS files live alongside their related PHP templates, NOT in separate `/js/` or `/css/` directories
|
|
2. Example structure:
|
|
```
|
|
template-parts/
|
|
├── property/
|
|
│ ├── property-card.php
|
|
│ ├── property-card.scss
|
|
│ └── property-card.js
|
|
├── components/
|
|
│ ├── hero-section.php
|
|
│ ├── hero-section.scss
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
1. **No empty catch blocks** - never write `try {} catch() { /* error occurred */ }`
|
|
2. **Let errors surface** - only use try/catch when genuinely required for functionality
|
|
3. **No fallback/legacy implementations** - assume modern browser, assume libraries exist
|
|
4. Dual implementations create security holes and maintenance nightmares
|
|
|
|
### Rendering
|
|
|
|
1. **Server-side render everything** - no client-side template rendering
|
|
2. **No preloaders/spinners** except:
|
|
- AJAX lookups (property filtering, search)
|
|
- Only show spinner on FIRST data load
|
|
- Subsequent AJAX calls show stale data until new data arrives
|
|
3. **Exception**: Search page will be AJAX-based and refined iteratively
|
|
|
|
### Animations
|
|
|
|
1. **No custom animations** - no hover effects, no transitions, no "slide up on scroll"
|
|
2. **Exception**: Animations built into Tailwind/UI library are acceptable
|
|
3. Keep it static and fast
|
|
|
|
### Version Control
|
|
|
|
1. **Git is for SNAPSHOTS** - not optimized for public/collaboration
|
|
2. After every development phase:
|
|
```bash
|
|
mysqldump -u [user] -p [database] > db-snapshot-phase-X.sql
|
|
git add -A
|
|
git commit -m "Phase X: [description]"
|
|
```
|
|
3. Database dumps committed alongside code
|
|
|
|
### Decision Making
|
|
|
|
1. **ASK before implementing** when facing architectural choices
|
|
2. Examples of decisions requiring developer input:
|
|
- CSS framework choice
|
|
- Preprocessor choice
|
|
- JS library choice
|
|
- Plugin alternatives
|
|
- Data structure approaches
|
|
3. Get clarity, then proceed
|
|
|
|
---
|
|
|
|
## Technology Stack
|
|
|
|
| Component | Choice |
|
|
|-----------|--------|
|
|
| CMS | WordPress 6.x |
|
|
| PHP | 8.1+ |
|
|
| Database | MySQL/MariaDB |
|
|
| CSS Framework | Tailwind CSS |
|
|
| CSS Preprocessor | SCSS |
|
|
| JavaScript | jQuery |
|
|
| Build Tool | Vite |
|
|
| Custom Fields | ACF Pro |
|
|
| Forms | Contact Form 7 |
|
|
| SEO | Yoast SEO |
|
|
|
|
## Tools Available
|
|
|
|
### WP-CLI
|
|
|
|
WP-CLI is installed at `/usr/local/bin/wp`. Use it for WordPress administration tasks:
|
|
|
|
```bash
|
|
# Theme management
|
|
wp theme list
|
|
wp theme activate homeproz
|
|
|
|
# Plugin management
|
|
wp plugin install <plugin-name> --activate
|
|
wp plugin list
|
|
|
|
# Database operations
|
|
wp db export backup.sql
|
|
wp db import backup.sql
|
|
|
|
# Cache and transients
|
|
wp cache flush
|
|
wp transient delete --all
|
|
|
|
# User management
|
|
wp user list
|
|
wp user create username email@example.com --role=administrator
|
|
|
|
# Options
|
|
wp option get siteurl
|
|
wp option update blogname "HomeProz Real Estate"
|
|
|
|
# Rewrite rules
|
|
wp rewrite flush
|
|
|
|
# Run with --allow-root since we're running as root
|
|
# All commands should use: wp --allow-root <command>
|
|
```
|
|
|
|
**Note:** Always use `--allow-root` flag when running as root user.
|
|
|
|
### dev_commit.sh
|
|
|
|
A helper script for development checkpoints. Located at `/var/www/html/dev_commit.sh`.
|
|
|
|
```bash
|
|
# Usage
|
|
./dev_commit.sh "Step X.X: Description of what was done"
|
|
|
|
# What it does:
|
|
# 1. Dumps database to db-snapshots/db-snapshot.sql (overwrites each time)
|
|
# 2. Runs git add -A
|
|
# 3. Commits with your message
|
|
```
|
|
|
|
**MANDATE:** Use `./dev_commit.sh` after completing each step in the implementation plan. This ensures we have a database snapshot with every code commit.
|
|
|
|
Example:
|
|
```bash
|
|
./dev_commit.sh "Step 1.3: Configure theme.json with brand colors"
|
|
```
|
|
|
|
---
|
|
|
|
## Theme Structure
|
|
|
|
```
|
|
themes/homeproz/
|
|
├── assets/
|
|
│ └── images/
|
|
├── src/ # Vite source files
|
|
│ ├── main.js # JS entry point
|
|
│ ├── main.scss # SCSS entry point
|
|
│ └── tailwind.css # Tailwind imports
|
|
├── dist/ # Vite build output
|
|
├── inc/
|
|
│ ├── acf-fields.php
|
|
│ ├── custom-post-types.php
|
|
│ ├── enqueue.php
|
|
│ ├── theme-setup.php
|
|
│ └── template-functions.php
|
|
├── template-parts/
|
|
│ ├── header/
|
|
│ │ ├── site-header.php
|
|
│ │ ├── site-header.scss
|
|
│ │ └── navigation.js
|
|
│ ├── footer/
|
|
│ │ └── site-footer.php
|
|
│ ├── property/
|
|
│ │ ├── property-card.php
|
|
│ │ ├── property-card.scss
|
|
│ │ ├── property-filters.php
|
|
│ │ ├── property-filters.js
|
|
│ │ └── property-filters.scss
|
|
│ └── components/
|
|
│ ├── agent-card.php
|
|
│ ├── agent-card.scss
|
|
│ └── ...
|
|
├── patterns/
|
|
├── front-page.php
|
|
├── page.php
|
|
├── page-about.php
|
|
├── page-contact.php
|
|
├── archive.php
|
|
├── single.php
|
|
├── archive-property.php
|
|
├── single-property.php
|
|
├── search.php
|
|
├── 404.php
|
|
├── header.php
|
|
├── footer.php
|
|
├── functions.php
|
|
├── style.css
|
|
├── theme.json
|
|
├── package.json
|
|
├── vite.config.js
|
|
├── tailwind.config.js
|
|
└── postcss.config.js
|
|
```
|
|
|
|
---
|
|
|
|
## Brand Specifications
|
|
|
|
### Colors
|
|
|
|
| Name | Hex | Usage |
|
|
|------|-----|-------|
|
|
| Background Dark | `#0A0A0A` | Primary background |
|
|
| Background Card | `#161616` | Elevated surfaces |
|
|
| Accent Primary | `#9F3730` | CTAs, buttons |
|
|
| Accent Hover | `#C8473F` | Button hover |
|
|
| Accent Light | `#BF524B` | Links |
|
|
| Text Primary | `#F5F5F5` | Headlines |
|
|
| Text Muted | `#B0B0B0` | Body text |
|
|
| Border | `#2A2A2A` | Dividers |
|
|
| Success | `#2E7D32` | Active listings |
|
|
| Warning | `#F9A825` | Pending listings |
|
|
| Sold | `#757575` | Sold listings |
|
|
|
|
### Typography
|
|
|
|
| Element | Font |
|
|
|---------|------|
|
|
| Headlines | Abril Fatface |
|
|
| Body | Inter (or Droid Sans) |
|
|
|
|
---
|
|
|
|
## Page Class Names Reference
|
|
|
|
| Template | Body Class |
|
|
|----------|------------|
|
|
| `front-page.php` | `Home_Page` |
|
|
| `page.php` | `Default_Page` |
|
|
| `page-about.php` | `About_Page` |
|
|
| `page-contact.php` | `Contact_Page` |
|
|
| `archive.php` | `Blog_Archive` |
|
|
| `single.php` | `Single_Post` |
|
|
| `archive-property.php` | `Properties_Archive` |
|
|
| `single-property.php` | `Single_Property` |
|
|
| `search.php` | `Search_Page` |
|
|
| `404.php` | `Error_404` |
|
|
|
|
---
|
|
|
|
## Development Phases
|
|
|
|
1. **Foundation** - Theme scaffold, Vite setup, Tailwind config, header/footer
|
|
2. **Property System** - CPT, ACF fields, archive, single, filters
|
|
3. **Page Templates** - Homepage, About, Contact, Blog, 404, Search
|
|
4. **Block Patterns** - Reusable Gutenberg patterns
|
|
5. **Content & SEO** - Schema markup, meta tags, initial content
|
|
6. **Performance & Security** - Caching, optimization, security hardening
|
|
7. **Testing & Training** - QA, documentation, client training
|
|
|
|
Each phase ends with:
|
|
```bash
|
|
mysqldump homeproz > db-snapshot-phase-X.sql
|
|
git add -A
|
|
git commit -m "Phase X complete: [description]"
|
|
```
|
|
|
|
---
|
|
|
|
## Open Decisions (Resolve Before Starting)
|
|
|
|
1. ~~CSS Framework~~ → **Tailwind CSS** (confirmed)
|
|
2. ~~JS Library~~ → **jQuery** (confirmed)
|
|
3. ~~Preprocessor~~ → **SCSS** (confirmed)
|
|
4. ~~Build tool~~ → **Vite** (confirmed)
|
|
5. Agents: ACF options page vs Agent CPT?
|
|
6. Testimonials: Static content vs Testimonial CPT?
|
|
7. Maps: Embed codes vs Google Maps API?
|
|
8. Form notifications: Which email address(es)?
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Dark theme is unconventional for real estate but matches client brand
|
|
- Property images use 16:10 aspect ratio (better for real estate than 16:9)
|
|
- No individual agent pages - all agents on single About page
|
|
- Sold properties remain visible (social proof)
|
|
- MLS numbers are display-only (no API integration)
|