AJAX Commentary

How It Works

Auto-Refresh System:

• JavaScript timer polls server every X seconds (user pref: 3, 5, 7, 10, 20, 30, or 60 seconds)
• Fetches new comments since last ID via AJAX call to /ajaxcommentary.php
• Updates commentary div with new content (no page reload)
• Resets timer for next poll

Posting Comments:

• Type comment in form
• Submit via jQuery AJAX form submission
• Comment posted instantly without page reload
• Form clears after successful post

Inactivity Detection:

• Page time counter tracks time since last user interaction
• After 6 minutes of inactivity: Auto-refresh stops
• Message displayed: "Live Update stopped due to inactivity, click here to reactivate it"
• Click link → Resets timer and resumes auto-refresh

User Preferences

• Would you like to use the Live Chat System? (bool, default: 1/yes)
• How long would you like between refreshes? (enum, default: 7 seconds)
  • 3 Seconds (fastest, most network traffic)
  • 5 Seconds
  • 7 Seconds (default)
  • 10 Seconds
  • 20 Seconds
  • 30 Seconds
  • 60 Seconds / 1 minute (slowest)

To Enable/Disable:

• Go to Preferences → Live Chat
• Toggle "Would you like to use the Live Chat System?"
• Adjust refresh interval to preference
• Submit preferences

Technical Details

JavaScript Libraries:

• jQuery (jquery.pack.js) - AJAX, DOM manipulation
• jQuery Form Plugin (jquery.form.js) - AJAX form submission

Database Table:

• chatareakeys: Stores unique MD5 keys per commentary section
• Columns: chatarea (section name), areakey (MD5 hash), settime (timestamp)
• Purpose: Secure identification of commentary areas for AJAX calls

AJAX Endpoint:

• URL: /ajaxcommentary.php
• Modes: manualrefresh (fetch new comments), addcomment (post comment)
• Parameters: lastid, acctid, section, areakey, talkline
• Response: JSON with new commentary HTML, replaceform flag, lastid

Key Generation:

• Per-area unique key generated from section name + timestamp + random.org 500 integers
• MD5 hashed for security
• Prevents unauthorized AJAX polling of commentary sections

Benefits

For Users:

• Real-time chat experience without manual refresh
• Faster conversation flow in village commentary
• No lost text when typing during page refresh
• Customizable update speed (3-60 seconds)

For Server:

• Lower bandwidth than full page reloads
• Auto-pause after 6 minutes saves server resources
• Efficient JSON responses vs full HTML pages

Limitations

• Requires JavaScript: No live chat without JS enabled (falls back to manual refresh)
• Network Overhead: Fast refresh rates (3-5 seconds) increase server load
• No Offline Queuing: If connection lost, comments don't queue (user must refresh)
• 6-Minute Timeout: Must manually reactivate after inactivity

Comparison to Manual Refresh

Without AJAX Commentary:

• Must manually click "Refresh" or reload page
• Lose typed text when refreshing
• Full page reload every time
• Slower conversation

With AJAX Commentary:

• Auto-refresh every X seconds
• Keep typed text during refresh
• Only commentary section updates
• Real-time chat feel

Strategy

Recommended Settings:

• Active Chat Sessions: 5-7 second refresh for fast conversation
• Casual Monitoring: 20-30 second refresh to stay informed without spam
• Low Bandwidth: 60 second refresh or disable entirely

When to Disable:

• On mobile data plan (saves bandwidth)
• Slow internet connection
• Prefer manual control over auto-refresh
• JavaScript disabled browser

Hooks Used

• viewcommentaryheader: Inject JavaScript libraries and init code
• viewcommentaryfooter: Start auto-refresh timer
• commentarytalkline: Attach AJAX form submission handler