JezK

Edit File: WORDPRESS_ELEMENTOR_GUIDE.md

# ODSAD WordPress + Elementor Production Website Guide

This comprehensive guide details the architecture, installation, visual editing, and deployment of the **ODSAD (Organization for Developing Services and Agriculture Development)** WordPress website powered by **Elementor**.

---

## 1. Architecture Overview

The project is structured into three clean, production-ready components:

```
c:/Users/SAEED KHAN/Desktop/odsad.org/
├── wordpress-theme/
│   └── odsad-elementor/               <-- Production WordPress Theme
│       ├── style.css                  # Design tokens, typography, animations, Elementor overrides
│       ├── functions.php              # Menus, Google Fonts, CPTs, AJAX handlers, Elementor support
│       ├── header.php                 # Dynamic header fallback (Logo, Menu, Blinking Donate CTA)
│       ├── footer.php                 # 4-column footer, legal notices, signature bar, modals
│       ├── index.php                  # Blog index & post grid
│       ├── page.php                   # Elementor full-width & canvas page template
│       ├── single.php                 # Single blog post template
│       ├── single-odsad_project.php   # Single project view with donor/partner metadata
│       ├── single-odsad_career.php    # Single vacancy view with online application form
│       ├── archive.php                # Category & taxonomy archive
│       ├── inc/
│       │   ├── custom-post-types.php  # CPTs: Projects (odsad_project) & Careers (odsad_career)
│       │   ├── form-handlers.php      # Secure AJAX endpoints for Contact & Application forms
│       │   └── elementor-support.php  # Theme Builder locations & custom shortcodes
│       ├── template-parts/
│       │   ├── donation-modal.php     # Multi-tier donation popup (PayPal, Cards, SWIFT)
│       │   └── license-modal.php      # MoEc Reg. No. 2669 & TIN verification popup
│       └── assets/                    # Bundled field images, certificate scans, and theme.js
│
├── elementor-templates/               <-- Visual Elementor Templates (JSON)
│   ├── elementor-kit-settings.json    # Global colors, typography (Fraunces & Plus Jakarta Sans)
│   ├── header-template.json           # Header Theme Builder template
│   ├── footer-template.json           # Footer Theme Builder template
│   ├── page-home.json                 # Home page (Hero, Bento Trust, Marquee, Sectors)
│   ├── page-about.json                # Who We Are (Director message, Governance, Photo showcase)
│   ├── page-what-we-do.json           # 6 Thematic Sectors & Programmatic Framework
│   ├── page-where-we-work.json        # Operational Hubs (Takhar HQ, Kabul) & Takhar in Action
│   ├── page-projects.json             # Implemented Projects portfolio (17+ projects)
│   ├── page-careers.json              # Vacancies & Volunteer listings + Application Form
│   ├── page-news.json                 # News & Field updates archive
│   └── page-contact.json              # Contact details, office hours & working Contact Form
│
└── import-data/
    └── odsad-content.xml              # 1-Click WordPress WXR Content Export
```

---

## 2. Required Plugins

---

## 3. Installation & Setup Instructions

### Step 1: Upload the Theme
1. Copy the `wordpress-theme/odsad-elementor` folder into your WordPress installation:
   `wp-content/themes/odsad-elementor/`
   *(Or compress `odsad-elementor` into a `.zip` file and upload via **WordPress Dashboard → Appearance → Themes → Add New → Upload Theme**).*
2. Click **Activate**.

### Step 2: Install Required Plugins
1. In the WordPress Dashboard, navigate to **Plugins → Add New**.
2. Search for and install **Elementor**. Click **Activate**.
3. (Optional) If you have **Elementor Pro**, upload and activate it.

### Step 3: 1-Click Content Import
1. Navigate to **Tools → Import**.
2. Under **WordPress**, click **Install Now** (if not installed) then **Run Importer**.
3. Choose the file `import-data/odsad-content.xml` from this project.
4. Check **Download and import file attachments** and click **Submit**.
5. All 8 core pages (Home, About, What We Do, Where We Work, Projects, Careers, News, Contact), sample projects, and news updates are now created in your WordPress database.

### Step 4: Set the Static Front Page
1. In the WordPress Dashboard, navigate to **Settings → Reading**.
2. Under **Your homepage displays**, select **A static page**.
3. Set **Homepage** to `Home` and **Posts page** to `News`.
4. Click **Save Changes**.

### Step 5: Configure Navigation Menus
1. Navigate to **Appearance → Menus**.
2. Select **Primary Menu** (or create one) and assign it to the **Primary Header Menu** display location.
3. Include your desired pages: Home, About Us, What We Do, Where We Work, Projects, Careers, News, Contact.

---

## 4. Visual Editing with Elementor

To visually edit any page on your website:

1. Log into your WordPress Dashboard.
2. Navigate to **Pages → All Pages**.
3. Hover over the page you wish to edit (e.g., **Home**, **About Us**, **Projects**) and click **Edit with Elementor**.
4. The visual drag-and-drop editor will launch:
   - **Text & Headings**: Click directly on any text or heading to change wording, font size, or alignment.
   - **Images**: Click on any photo to choose a new high-resolution photo from your WordPress Media Library.
   - **Buttons & Links**: Click on any button to update the button text or URL destination.
   - **Colors & Styles**: Use the **Style** tab in the left panel to customize colors, margins, padding, and animations.
5. Click **Update** at the bottom-left to save your changes instantly to the live website.

---

## 5. Importing Elementor JSON Templates

If you wish to import the individual pre-built Elementor page templates:

1. Navigate to **Templates → Saved Templates**.
2. Click **Import Templates** at the top.
3. Select any of the JSON files from `elementor-templates/`:
   - `page-home.json`
   - `page-about.json`
   - `page-what-we-do.json`
   - `page-where-we-work.json`
   - `page-projects.json`
   - `page-careers.json`
   - `page-contact.json`
4. When editing any page with Elementor, click the folder icon (**Add Template → My Templates**), select the imported template, and click **Insert**.

---

## 6. Managing Custom Post Types

### Projects Portfolio (17+ Implemented Projects)
- Navigate to **Projects → All Projects** in the WordPress admin menu.
- Click **Add New Project** to add a new donor initiative.
- Enter the Project Title, description, and custom fields:
  - `project_donor`: e.g., *UN AHF-OCHA / Mission East*
  - `project_partner`: e.g., *Concern Worldwide*
  - `project_location`: e.g., *Takhar Province: Namakab District*
  - `project_value`: e.g., *$67,406 USD*
  - `project_period`: e.g., *10-Jun-2025 to 10-Dec-2025*
  - `project_status`: *Active* or *Completed*
- Set a **Featured Image** (e.g., authentic field photos).
- Click **Publish**.

### Job Vacancies & Volunteer Roster
- Navigate to **Careers / Jobs → Add New Vacancy**.
- Fill in the vacancy title, duties, and meta fields (`career_ref_no`, `career_department`, `career_location`, `career_type`, `career_experience`, `career_deadline`).
- The page automatically embeds the **Online Application Form**.

---

## 7. Form Notifications & SMTP Setup

The theme includes secure AJAX handlers for both the **Contact Form** and the **Online Application Form**:

1. By default, submissions are emailed to the administrator email configured in **Settings → General** (`admin_email`).
2. To guarantee email delivery (and prevent messages from ending up in Spam), install the free **WP Mail SMTP** plugin:
   - Navigate to **WP Mail SMTP → Settings**.
   - Select your mailer (SendLayer, Brevo, Google / Gmail, Microsoft 365, or Other SMTP).
   - Enter your SMTP Host, Username, and Password.
   - Send a test email to verify that notifications arrive instantly.

---

## 8. Domain Connection & SSL / HTTPS Deployment

When deploying to your live domain (e.g. `https://example.com` or `https://www.example.com`):

1. **No Hardcoded URLs**: The theme uses dynamic functions (`home_url()`, `get_template_directory_uri()`, `site_url()`). It contains zero hardcoded `localhost` links.
2. In **Settings → General**, set:
   - **WordPress Address (URL)**: `https://yourdomain.org`
   - **Site Address (URL)**: `https://yourdomain.org`
3. Ensure an SSL certificate is active on your host (Let's Encrypt or host-provided SSL).
4. If you ever change domains, run **Elementor → Tools → Replace URL** to update any internal image URLs stored in Elementor page data.

---

## 9. Verification & Quality Checklist

- [x] **WordPress 6.x & PHP 8.x Compatible**: Strict types, sanitized inputs, and standard hooks.
- [x] **Elementor & Elementor Pro Ready**: Containers, widgets, and theme builder locations.
- [x] **Visual Dashboard Editing**: All pages editable via `Pages → Edit with Elementor`.
- [x] **Preserved Design & Branding**: Fraunces serif headings, Plus Jakarta Sans body, Forest Green (`#1e4738`), Terracotta Coral (`#c86f55`), and Ochre Gold (`#d4a359`).
- [x] **Blinking Donate Now CTA**: Header button and top notice bar with pulsing beacon dot and glow animation.
- [x] **Multi-Tier Donation Modal**: Pre-set \$25, \$75, \$150, \$500 buttons with PayPal, Credit Card, and Bank SWIFT wire tabs.
- [x] **License Verification Modal**: Displays official Ministry of Economy Reg. No. 2669 certificate and stamps.
- [x] **Authentic Field Photos**: All 5 newly integrated photos mapped into templates.
- [x] **Responsive**: Optimized across Large Desktop, Laptop, Tablet, and Mobile.