TA Editorial Assessments

A lightweight, secure, and developer-friendly WordPress plugin designed to manage, display, and import assessment briefs. Built using standard WordPress object-oriented architecture and security best practices.

🌐 Live Demos & Working Examples

• Front-End Render Page: daniyal-hassan.com/techabout — Live page rendering assessment briefs via the [ta_assessment_briefs] shortcode.
• REST API Endpoint: daniyal-hassan.com/wp-json/ta/v1/briefs — Live custom JSON endpoint returning structured assessment brief data.

💡 Plugin Features & Architectural Scope

• Custom Content Type: Registers assessment_brief CPT with assessment_role custom taxonomy.
• Custom Meta Fields: Secure meta management for time duration (_ta_duration), reviewer notes (_ta_reviewer_notes), and rubric specifications (_ta_rubric).
• Custom REST API Endpoint: Provides /wp-json/ta/v1/briefs for decoupled or headless integrations.
• WP-CLI Import Integration: Command-line tool (wp ta-assessments import) supporting bulk CSV processing with --dry-run testing.
• Targeted Admin UX: Lightweight Vanilla JS character counter on the reviewer notes metabox, loaded strictly on assessment_brief edit screens.
• Front-End Shortcode: Standard [ta_assessment_briefs] shortcode equipped with developer-facing filters for custom queries and markup overrides.

🚀 Installation & Setup

Standard Installation

1. Upload or copy the ta-editorial-assessments folder into your WordPress site's /wp-content/plugins/ directory.
2. Log into WP-Admin, navigate to Plugins -> Installed Plugins, and click Activate.
3. Access the new Assessment Briefs menu item in your admin sidebar.

Running the WP-CLI Import

Connect to your server terminal via SSH and execute the CLI importer using the bundled sample CSV:

# Dry run (simulates the import without altering the database)
wp ta-assessments import wp-content/plugins/ta-editorial-assessments/briefs-import-sample.csv --dry-run

# Execute full import
wp ta-assessments import wp-content/plugins/ta-editorial-assessments/briefs-import-sample.csv

🛠️ Architectural Decisions & Tradeoffs

1. Vanilla JavaScript vs. React / Gutenberg Build

• Decision: Used clean Vanilla JavaScript for the admin character counter script.
• Tradeoff: Avoided heavy Node build pipelines (@wordpress/scripts, Webpack, Babel) and npm dependencies for a simple UI helper. This keeps the plugin bundle size lightweight (~few KB) and instantly maintainable.

2. Custom REST Endpoint vs. Core CPT REST Exposure

• Decision: Registered a dedicated custom REST route (/wp-json/ta/v1/briefs) rather than relying solely on show_in_rest => true.
• Tradeoff: Allows exact response shaping and data normalization (combining taxonomy terms and sanitized meta directly into the primary JSON payload) without exposing unneeded internal post object fields.

💻 Developer Customization & Exposed Filters

The plugin exposes custom filters so developers can alter queries and HTML output from a child theme’s functions.php file without editing plugin core files.

Filter 1: Customizing Query Arguments (ta_briefs_query_args)

Modify the WP_Query arguments used by the front-end shortcode:

add_filter( 'ta_briefs_query_args', function( $query_args ) {
    $query_args['posts_per_page'] = 5;
    $query_args['orderby']        = 'title';
    $query_args['order']          = 'ASC';
    return $query_args;
} );

Filter 2: Customizing Front-End Item HTML (ta_brief_item_html)

Override or wrap the generated markup for individual brief cards:

add_filter( 'ta_brief_item_html', function( $html, $post_id ) {
    $duration = get_post_meta( $post_id, '_ta_duration', true );
    $badge    = $duration ? '<span class="brief-duration-badge">' . esc_html( $duration ) . ' mins</span>' : '';

    return '<div class="custom-brief-card">' . $badge . $html . '</div>';
}, 10, 2 );

JS REST API Consumption Example

Fetch briefs programmatically on the client side:

async function fetchBriefs() {
    try {
        const response = await fetch('[https://daniyal-hassan.com/wp-json/ta/v1/briefs](https://daniyal-hassan.com/wp-json/ta/v1/briefs)');
        const briefs = await response.json();
        console.log('Fetched Assessment Briefs:', briefs);
    } catch (error) {
        console.error('Error fetching briefs:', error);
    }
}
fetchBriefs();

🛡️ Security Implementation & Data Integrity

• Input Sanitization: All incoming user data from metaboxes and CSV imports are sanitized (sanitize_text_field, absint, wp_kses_post) before database insertion.
• Contextual Output Escaping: Front-end and admin UI strings are escaped at the point of output using esc_html(), esc_attr(), and wp_kses_post().
• Authorization & CSRF Protection: Admin save handlers verify current_user_can('edit_posts') and validate cryptographic nonces (wp_verify_nonce).
• Prepared Database Operations: All metadata and post updates utilize official WordPress core wrapper APIs (update_post_meta, wp_insert_post) to eliminate raw SQL injection vectors.
• Secret Hygiene: No API keys, passwords, or personal credentials exist within this code package or repository.

🧪 Testing & Verification Steps

1. Shortcode Output: Add [ta_assessment_briefs] to any WordPress page and verify output layout.
2. REST API Response: Visit /wp-json/ta/v1/briefs in your browser or Postman and confirm valid JSON output containing post titles and meta attributes.
3. Admin Character Counter: Edit or create an Assessment Brief in WP-Admin and observe real-time character counting under the Reviewer Notes textarea.
4. CLI Dry Run: Execute wp ta-assessments import <path-to-csv> --dry-run to confirm CSV parsing accuracy without committing database writes.

🔮 What I Would Improve (Future Enhancements)

Given additional project scope and development time, the following enhancements would be prioritized:

1. Native Gutenberg Block: Rebuild the front-end shortcode display into a modern, interactive Gutenberg block built with React (@wordpress/block-editor).
2. Object Caching (Transients): Implement transient caching (set_transient) for the REST API response and shortcode queries to optimize performance for high-traffic environments.
3. Automated Unit & Integration Testing: Introduce PHPUnit test cases for CPT registration, meta sanitization, and REST route assertion, paired with Cypress for admin UX testing.

🔄 Rollback & Cleanup Strategy

• Deactivation: Safely flushes rewrite rules (flush_rewrite_rules) upon plugin deactivation to ensure site permalinks remain stable.
• Data Persistence: Custom post types and metadata are preserved in the database during plugin updates and deactivation to safeguard content integrity.