Skip to content

Functionality

Jump to bottom
Terrence Murray edited this page Apr 5, 2026 · 3 revisions

Functionality

Custom Queries

The site implements three custom WP_Query instances, each owned by a different team member.

Query 1 - Trending by View Count (Jeremiah)

Purpose: Display posts ordered by popularity based on view count.

Property Detail
Location page-trending.php
Meta Key _post_views_count
Order Descending (most viewed first)
Page Trending in Tech

This query uses meta_key ordering to surface the most-read content, providing readers with a curated view of popular articles.

Query 2 - Category + Date Range Filter (Terrence)

Purpose: Allow users to filter articles by category and/or date range with paginated results.

Property Detail
Location inc/shortcode-category-filter.php
Shortcode [tdf_category_filter per_page="6"]
Used On Article archive (archive-article.php), Home page

How it works:

  1. Category Filtering - Uses tax_query to filter by category taxonomy slug, passed via ?article_cat=slug URL parameter
  2. Date Range Filtering - Uses date_query with after and before parameters from ?from=YYYY-MM-DD&to=YYYY-MM-DD URL parameters
  3. Pagination - Reads the paged query variable and passes it to WP_Query
  4. Combined Filtering - Category and date filters can be used simultaneously; state is preserved across pagination

Input Sanitization:

  • Category slugs sanitized with sanitize_key()
  • Date values sanitized with sanitize_text_field() and validated through strtotime()

UI Components:

  • Category pill tabs displaying all categories (excluding "Uncategorized")
  • Date range form with From/To date inputs
  • 3-column responsive grid of article cards
  • WP-PageNavi pagination with fallback to paginate_links()
  • Empty state message when no results match

Query 3 - Related Content Linking (Robyn)

Purpose: Connect opinions to their related articles and vice versa using ACF relationship fields.

Property Detail
Location single.php
Field related_article (ACF Relationship)

On an Article page: Runs a meta_query searching for Opinion posts whose related_article field contains the current article's ID (using LIKE comparison). Displays linked opinions with their pull quotes, authors, and dates.

On an Opinion page: Retrieves the related Article post from the ACF relationship field and displays it as a card with thumbnail, title, excerpt, and date.

User Roles and Permissions

User management is configured automatically during theme setup and enhanced with the Members plugin.

Registration

  • Front-end user registration is enabled (users_can_register = 1)
  • New users are assigned the Contributor role by default
  • Registration allows new writers to submit content for editorial review

Role Hierarchy

Role Content Capabilities Admin Capabilities
Administrator Create, edit, publish, and delete all content (articles, opinions, reviews, posts) Full site management — plugins, themes, settings, user management
Editor Create, edit, publish, and delete all content including other authors' posts Moderate comments, manage categories and tags
Contributor Create and edit own posts (articles, opinions, reviews) — cannot publish (must submit for review) No admin access beyond own draft management
Subscriber Read published content and post comments No content creation or admin access

Key distinction: Because all three CPTs (Article, Opinion, Review) use capability_type => 'post', WordPress post capabilities apply uniformly. Contributors can draft content for any CPT but an Editor or Administrator must publish it. ACF fields (including star ratings on Reviews) are visible to any role that can edit the post.

The Members plugin provides a UI for fine-grained capability management, allowing the team to customize what each role can do beyond WordPress defaults.

Comments

  • Comments are enabled on all post types (Article, Opinion, Review, and standard Posts) via 'comments' in each CPT's supports array
  • Comments are rendered on single post views via comments_template() with threaded reply support
  • Default comment status is open site-wide (default_comment_status = open)
  • First-time commenters require moderation (comment_moderation = 1)
  • Commenters must provide name and email (require_name_email = 1)
  • Subscribers and logged-in users can post comments; anonymous visitors must provide name and email

Search

WordPress core search is available site-wide. The Article and Opinion CPTs are registered with 'publicly_queryable' => true, making their content discoverable through the default WordPress search functionality.

The category filter shortcode provides an additional discovery mechanism specific to articles, complementing the global search with structured browsing by topic and date.

Custom Plugins

Three custom plugins were developed for the project, one by each team member.

1. TDF Breaking News Banner (Terrence)

Location: wp-content/plugins/tdf-breaking-news/

A scrolling headline ticker displayed in the site header.

Features:

  • Queries the most recent posts across all public custom post types
  • Horizontally scrolling slides with automatic progression
  • Manual navigation via previous/next arrow buttons
  • Slide counter display (e.g., "01/05")
  • Progress bar indicator
  • "Trending" label with CSS pulse animation

Admin Settings (Settings > Breaking News):

  • Enable/disable toggle
  • Scroll speed: 500ms to 10,000ms (default: 3,000ms)
  • Maximum headlines: 1 to 20 (default: 5)

Shortcode: [tdf_breaking_news] (placed in header.php)

Files:

  • tdf-breaking-news.php - Plugin registration, settings page, shortcode handler
  • css/banner.css - Banner styling and animations
  • js/banner.js - Slide transitions and navigation logic

2. TDF AJAX Category Filter (Jeremiah)

A dynamic post filtering system that updates content without full page reloads, providing a smoother browsing experience.

3. TDF Reading Progress Bar (Robyn)

A scroll-based progress indicator displayed on single post views, showing readers how far they have progressed through an article.

Shortcodes

Shortcode Parameters Output
[tdf_breaking_news] None Scrolling headline ticker with navigation
[tdf_category_filter] per_page (default: 6) Filterable article grid with category tabs, date range, and pagination

Automated Setup System

The theme includes a one-time setup routine (inc/setup.php) gated by a version constant (TDF_SETUP_VERSION). On first admin visit after theme activation, it automatically:

  1. Activates 9 required plugins
  2. Creates pages: Home, About Us, Team (child), Mission (child)
  3. Sets Home as the static front page
  4. Seeds categories: Mobile Devices, Apple, Google, Samsung
  5. Builds the primary navigation menu with correct parent-child hierarchy
  6. Enables Yoast SEO breadcrumbs
  7. Enables front-end user registration with Contributor as default role
  8. Enables comments site-wide with first-comment moderation
  9. Flushes rewrite rules for custom post type permalinks

Bumping TDF_SETUP_VERSION triggers the setup to re-run, allowing team members to propagate environment changes by pulling new code.

Clone this wiki locally