Docs

xPlay Theme
Version 1.0.6 — WordPress Theme Documentation
Developer Reference & Feature Guide

  1. Overview
    xPlay is a dark-themed WordPress theme purpose-built for video publishing websites. It provides a full suite of features including a custom video player, user authentication, profile pages, video uploads, monetization, favorites, comments, and an extensive ad zone system — all configurable through a custom Theme Options panel.

Theme Name
xPlay Theme

Version
1.0.6

Requires WordPress
5.8+

PHP Version
7.4+

License
Proprietary

Text Domain
xplay-theme

  1. Theme Setup
    2.1 Automatic Page Creation
    On theme activation, the following pages are automatically created with their assigned templates:
  • Categories → page-categories.php
  • Image Gallery → page-image-gallery.php
  • Pornstars → page-pornstars.php
  • Tags → page-tags.php
  • Featured Videos → page-featured.php
  • Profile → page-profile.php
  • Favorites → page-favorites.php
  • My Videos → page-my-videos.php
  • Reset Password → page-reset-password.php
  • Forgot Password → page-forgot-password.php
  • Edit Video → edit-video.php
  • Subscribe → template-subscribe.php
    These pages are only created if they do not already exist (checked by slug).
    2.2 Theme Supports
    The theme registers the following WordPress feature supports:
  • automatic-feed-links
  • title-tag
  • post-thumbnails
  • html5 (search-form, comment-form, comment-list, gallery, caption, style, script)
  • customize-selective-refresh-widgets
  • custom-logo (flex width/height, 250×250)
    2.3 Navigation Menus
  • Primary Menu (menu-1)
  • Footer Menu (footer-menu)
  1. Widget Areas (Sidebars)
    The following widget areas are registered and available in Appearance > Widgets:
  • Home Top Ad (home_top_ad) — Top of homepage, 728×90
  • Home Bottom Ad (home_bottom_ad) — Bottom of homepage, 728×90
  • Video Post Sidebar (main_sidebar) — Sidebar on single video posts
  • Ad Above Video (ad_above_video) — Above the video player, 728×90
  • Ad Below Video (ad_below_video) — Below the video player, 728×90
  • Video Ad Zone On Player (video_ad_zone) — Overlay on video player, 300×250
  • Page Top Ad (page_top_ad) — Top of all pages
  • Page Bottom Ad (page_bottom_ad) — Bottom of all pages
  • Related Videos Top (related_top_widget) — Above related videos section
  • Related Videos Bottom (related_bottom_widget) — Below related videos section
  • Footer Ad 1–4 (footer-ads-1 through footer-ads-4) — Footer ad spaces, 300×250
  1. Scripts & Styles
    4.1 Global Assets
  • style.css — Main theme stylesheet
  • Font Awesome 4.7.0 — Icon library (CDN)
  • navigation.js — Mobile nav toggle
  • header.js — Header interactions
  • trailer-hover.js — Video card trailer preview on hover
    4.2 Single Post Assets
    Loaded only on single post pages (is_single()):
  • single-post.css — Single video post layout and component styles
  • like-dislike.js — AJAX like/dislike with nonce (xplay_like_nonce)
  • comments-toggle.js — Slide-out comments panel toggle
  • video-ad.js — Video overlay ad display and close logic
    4.3 Dashboard Assets
  • dashboard-pages.css — Styles for profile, upload, favorites, my-videos pages
  • profile-cropper.js — Avatar image cropper (CropperJS 1.5.13)
  • footer-links.js — Admin footer links manager (admin only)
  1. User System
    5.1 Virtual Pages & URL Rewriting
    The theme creates virtual pages via rewrite rules (no physical WordPress pages needed):
  • /login/ → page-login.php
  • /register/ → page-register.php
  • /my-account/ → page-my-account.php
  • /upload-video/ → page-upload-video.php
  • /my-videos/ → page-my-videos.php
  • /favorites/ → page-favorites.php
  • /forgot-password/ → page-forgot-password.php
  • /reset-password/ → page-reset-password.php
  • /profile/{username}/ → page-profile.php
  • /profile/{username}/page/{n}/ → page-profile.php (paginated)
    5.2 Access Control
  • Logged-in users visiting /login/ or /register/ are redirected to /my-account/
  • Guests visiting /my-account/, /upload-video/, /my-videos/, /favorites/ are redirected to /login/
  • Admin bar is hidden for non-administrator users
  • Non-administrators accessing wp-admin are redirected to /my-account/
    5.3 Registration (AJAX)
    Action: xplay_register_user (nopriv) | Nonce: xplay_register_nonce
  • Username: letters, numbers, underscores, hyphens only. No spaces. 3–60 characters.
  • Email: must be valid and not already registered
  • Password: minimum 6 characters
  • On success: user is auto-logged-in and redirected (supports redirect_to parameter)
  • Role assigned: subscriber
    5.4 Login (AJAX)
    Action: xplay_login_user (nopriv) | Nonce: xplay_login_nonce
  • Accepts username/password with optional remember-me
  • Supports redirect_to parameter for post-login destination
    5.5 Password Reset Flow
    Forgot Password — Action: xplay_forgot_password
  • Accepts email address, generates a WordPress reset key
  • Sends a branded reset email with a 24-hour expiry link to /reset-password/
  • Does not reveal whether the email is registered (security)
    Reset Password — Action: xplay_reset_password
  • Validates reset key and user login pair via check_password_reset_key()
  • Minimum password length: 8 characters
  • Sends a confirmation email on success
  1. Video System
    6.1 Video Meta Keys
    Meta keys are configurable via Theme Options (with defaults):
  • embed — Video embed code or MP4 URL
  • main_thumbnail — Poster/thumbnail image URL
  • trailer_url — Trailer video URL for hover preview
  • models — Model/performer names
  • duration — Video duration (MM:SS or HH:MM:SS)
  • post_views_count — View counter
  • likes / dislikes — User vote counts
  • affiliate_text / affiliate_url — Per-video affiliate button
  • _is_premium — Premium-only flag
  • _is_featured — Featured video flag
    6.2 Duration Normalization
    On save_post, durations are automatically normalized:
  • Plain seconds (e.g. 3661) → HH:MM:SS (01:01:01)
  • Already formatted strings are passed through
  • Final value is validated against the pattern: ([0-9]{1,2}:)?[0-5][0-9]:[0-5][0-9]
    6.3 Auto Featured Image Sideloading
    When a post is saved without a featured image, the theme will attempt to download the URL stored in the main_thumbnail meta field and sideload it into the Media Library as the featured image. This runs once per post (tracked via _xplay_thumb_sideloaded meta).
    Allowed file types: JPEG, PNG, GIF, WebP
    6.4 Video Upload (AJAX)
    Action: xplay_upload_video | Nonce: xplay_upload_nonce | Requires login
  • Accepts: title, description, embed_code, duration, thumbnail_url, trailer_url, models, categories, tags, affiliate_text, affiliate_url, is_featured
  • Embed validation: only iframe or direct .mp4 URL accepted
  • Iframe sanitization: uses wp_kses() with a safe iframe attribute allowlist
  • Posts are created with post_status = pending (requires admin review)
  • Supports monetization: free, pay_per_view (with minimum price), premium_only
    6.5 View Counter
    Function: xplay_set_post_views($post_id)
  • Called on every single post view
  • Stores count in post meta key: post_views_count
  • Does not increment in wp-admin
    6.6 Like / Dislike (AJAX)
  • Action handle_like — increments likes meta, available to all users
  • Action handle_dislike — increments dislikes meta, available to all users
  • Both use nonce: xplay_like_nonce
    6.7 Video Deletion (AJAX)
    Action: xplay_delete_video | Nonce: xplay_delete_video | Requires login
  • Verifies post ownership (post_author must match current user)
  • Deletes featured image attachment
  • Deletes all child attachments
  • Permanently deletes the post
    6.8 Video Ordering
    On the homepage, ordering is controlled via the ?order= query parameter:
  • recent → order by date DESC
  • most-viewed → order by post_views_count meta DESC
  • top-rated → order by likes meta DESC
  • (default / no parameter) → random order
    Category and tag archive pages always display in random order.
  1. Favorites System
    Action: xplay_toggle_favorite | Nonce: xplay_favorites_nonce | Requires login
    Favorites are stored in user meta under the key xplay_favorites as a serialized array of post IDs.
  • Toggle adds or removes the post ID from the array
  • Response includes: action (added/removed), is_favorited (bool), count (int)
    Helper function: xplay_is_favorited($post_id, $user_id = null)
  • Returns true/false
  • Defaults to current logged-in user if no $user_id provided
  1. Comments System
    8.1 Custom Comment Callback
    Function: xplay_custom_comment($comment, $args, $depth)
    Registered via wp_list_comments() callback parameter in comments.php. Renders each comment with:
  • Custom avatar (see section 8.2)
  • Author name linking to /profile/{username}/ for registered users
  • Guest authors link to their provided URL (with rel=nofollow), or plain text if none
  • Comment date/time
  • Moderation pending notice for unapproved comments
  • Reply and Edit action links
    8.2 Avatar Helper
    Function: xplay_get_user_avatar($user_id, $size = 48, $fallback = ”)
  • Checks custom_avatar user meta (attachment ID) first
  • Falls back to WordPress get_avatar() / Gravatar if no custom avatar is set
  • Used in both single.php (author block) and the comment callback
  • Returns HTML img tag with class user-avatar
  1. Profile & URL System
    9.1 URL Structure
  • /profile/{username}/ — User profile page
  • /profile/{username}/page/{n}/ — Paginated profile videos
  • /my-videos/page/{n}/ — Paginated my videos
    9.2 Legacy URL Redirect
    Old ?user={ID} profile URLs are automatically 301-redirected to the clean /profile/{username}/ format.
    9.3 Helper Function
    get_user_profile_url($user_id_or_login)
  • Accepts numeric user ID or username string
  • Returns clean profile URL
  1. Pagination & Posts Per Page
    Function: xplay_modify_posts_per_page($query)
  • Applies to: homepage (is_home), archives (is_archive), search (is_search)
  • Value is pulled from Theme Options: videos_per_page (default: 24)
  • Only modifies the main query on the front end
  1. Theme Options
    Stored in WordPress options table under the key xplay_theme_options (array). Accessible via get_option(‘xplay_theme_options’, []).
    Configurable settings include:
  • video_embed_meta_key — Custom field key for embed code (default: embed)
  • video_poster_meta_key — Custom field key for poster image (default: main_thumbnail)
  • video_trailer_meta_key — Custom field key for trailer URL (default: trailer_url)
  • video_models_meta_key — Custom field key for models (default: models)
  • video_sandbox_enabled — Add sandbox attribute to iframes (bool)
  • global_affiliate_url — Sitewide affiliate button URL
  • global_affiliate_link_text — Sitewide affiliate button label (default: Watch Full Video)
  • videos_per_page — Number of videos per page (default: 24)
  • enable_login_register — Show login/register features (default: 1)
  • enable_profiles — Show profile/author features (default: 1)
  1. Key File Structure
  • functions.php — Core theme functions (this document)
  • single.php — Single video post template
  • comments.php — Comment list and form template
  • css/single-post.css — Single post & comments styles
  • css/dashboard-pages.css — User dashboard page styles
  • js/like-dislike.js — Like/dislike AJAX handler
  • js/comments-toggle.js — Comments panel slide toggle
  • js/video-ad.js — Video overlay ad logic
  • js/profile-cropper.js — Avatar crop & upload
  • js/trailer-hover.js — Trailer preview on hover
  • js/header.js — Header scroll/behavior
  • js/footer-links.js — Admin footer links
  • options/admin-page.php — Theme options admin page
  • options/settings.php — Theme options field definitions
  • options/enqueue.php — Options page asset enqueuing
  • inc/metabox-video.php — Video meta box for post editor
  • inc/subscription/loader.php — Subscription/monetization module
  • template-parts/related-videos.php — Related videos section
  1. Changelog
    v1.0.4 (Current)
  • Added xplay_get_user_avatar() helper for consistent avatar rendering
  • Custom comment callback (xplay_custom_comment) with avatar, profile links, and dark theme styling
  • Comment author names link to /profile/{username}/ for registered users
  • Refactored single.php author block to use xplay_get_user_avatar()
  • Added comment panel CSS to single-post.css
    v1.0.3
  • Added sandbox option for iframe embeds
  • Improved video upload validation (iframe and .mp4 only)
  • Added global affiliate button fallback from Theme Options
    v1.0.2
  • Added pay-per-view and premium-only monetization
  • Added video deletion with attachment cleanup
  • Added password reset flow (forgot/reset pages)
    v1.0.1
  • Added favorites system with AJAX toggle
  • Added profile URL rewriting and pagination
  • Added view counter and like/dislike AJAX handlers
    v1.0.0
  • Initial release
  • Theme setup, widget areas, video meta system
  • User registration, login, and virtual page routing

xPlay Theme v1.0.4 — End of Documentation
xPlay Theme v1.0.4 — Documentation | Page