Shortcode [elc_pfl_transcript]

1.0 Overview #

This specification defines the functional requirements, behavior, and technical parameters for the [elc_pfl_transcript] shortcode. It serves as the definitive source of truth for engineering and quality assurance teams, ensuring a consistent and accurate implementation of the feature.

The primary function of this shortcode is to provide students with a user-initiated mechanism to generate and download a ZIP archive of their course transcript. To ensure correct functionality, the shortcode is subject to a strict placement constraint: it will only render its UI elements and become operational when placed within a course page. The following section details the user interaction sequence from initiation to download.

2.0 Core Functionality and User Flow #

This section details the complete, step-by-step user interaction sequence with the [elc_pfl_transcript] shortcode. It outlines the state changes of the shortcode’s UI from the initial prompt to the final download, providing a clear map of the intended user experience.

1. Step 1: Initiation The user is presented with the initial shortcode UI, which prompts them to generate the transcript.
2. Step 2: Generation Trigger The user selects the ‘Generate transcript’ button. This action triggers the plugin to begin generating the course transcript as a ZIP archive.
3. Step 3: UI State Change Upon successful generation of the archive, the shortcode’s UI automatically updates. The ‘Generate transcript’ button is replaced by a ‘Download transcript’ link.
4. Step 4: Download The user selects the ‘Download transcript’ link. This action saves the generated ZIP archive directly to the user’s local ‘downloads’ folder.

While this flow describes the direct user interaction, the initial visibility of the feature is governed by a specific set of rules, which are analyzed in the next section.

3.0 Conditional Rendering Logic #

This section analyzes the conditional rules that govern the initial rendering of the ‘Generate transcript’ button. This logic is a critical piece of the feature’s design, intended to manage user expectations and prevent attempts to generate transcripts from incomplete course data. This behavior is controlled by the allow_partial attribute and is based on the student’s progress state within the course.

Condition	Button Rendering Behavior
allow_partial attribute is “0” or omitted (default behavior).	The ‘Generate transcript’ button is rendered only if the student’s course progress state is ‘completed’.
allow_partial attribute is explicitly set to “1”.	The ‘Generate transcript’ button is rendered if the student’s course progress state is ‘in_progress’ OR ‘completed’.

By default, the logic enforces a strict completion-gate, guaranteeing that official transcripts represent a finished course. The allow_partial="1" setting provides flexibility for scenarios where in-progress snapshots are valuable, such as for administrative review or student self-assessment. The allow_partial attribute is one of two key parameters that control the shortcode’s behavior, which are detailed next.

4.0 Shortcode Attributes #

This section serves as a technical reference, providing detailed specifications for each attribute available for the [elc_pfl_transcript] shortcode. These attributes allow for the configuration of the shortcode’s appearance and rendering logic.

display_as #

• Purpose: Controls the visual appearance of the shortcode’s UI element.
• Accepted Values:
  • banner (Default): Renders the button within a stylized banner that includes informational text.
  • button: Renders the element as a standalone button without the surrounding banner text.
• Example Usage:

allow_partial #

• Purpose: Controls the conditional logic for rendering the button based on the student’s course progress.
• Accepted Values:
  • 0 (Default): Renders the button only when the course state is ‘completed’.
  • 1: Renders the button when the course state is either ‘in_progress’ or ‘completed’.
• Example Usage:

In addition to these configuration attributes, the shortcode provides an action hook for programmatic extension, detailed below.

5.0 Developer Integration: Action Hook #

This section documents the public-facing action hook provided by the [elc_pfl_transcript] shortcode. This hook allows developers to inject custom logic at a key point in the transcript generation process, enabling custom logging, notifications, or integration with external systems.

• Hook Name: elc_pfl_after_transcript_generated
• Trigger: Executed immediately after the transcript ZIP archive has been successfully generated and is available for download.
• Purpose: Allows developers to execute custom logic, such as logging transcript generation events, sending notifications, or integrating with other systems.

Parameter	Type	Description
$user_id	int	The ID of the user for whom the transcript was generated.
$course_id	int	The ID of the course for which the transcript was generated.
$zip_path	string	The absolute file path to the generated ZIP archive.
$atts	array	An associative array of the shortcode attributes used in the request (e.g., display_as, allow_partial).

To complement this technical data, the final section describes the specific visual states of the default user interface.

6.0 Appendix: Visual States of the display_as="banner" Style #

This appendix provides a textual description of the two primary visual states of the default “banner” display style. This information is essential for UI/UX validation, front-end development, and quality assurance testing.

State	Description of UI Elements
Initial State (Pre-generation)	The banner displays the text “Generate your transcript ZIP.” alongside a button labeled “Generate transcript”.
Ready State (Post-generation)	The banner automatically updates to display the text “Transcript ready.” alongside a link labeled “Download transcript”.