nged when $form is not a WP_Post instance
* or when $column_name does not match an analytics column.
*
* Hooks: wpforms_overview_table_column_value (filter).
* Matches the signature used by Forms\Locator::column_value — no strict type
* hints on filter callback params.
*
* @since 2.0.0
*
* @param mixed $value Current cell value (pass-through for unknown columns).
* @param mixed $form Form post object; must be WP_Post to render.
* @param string $column_name Column identifier.
*
* @return mixed
*/
public function render_column( $value, $form, string $column_name ) {
if ( ! $form instanceof WP_Post ) {
return $value;
}
$form_id = (int) $form->ID;
switch ( $column_name ) {
case 'analytics_views':
$value = $this->render_views( $form_id );
break;
case 'analytics_interactions':
$value = $this->render_interactions( $form_id );
break;
case 'analytics_conversion':
$value = $this->render_conversion( $form_id );
break;
}
return $value;
}
/**
* Bulk-fetch stats for all forms on the current overview page.
*
* Retrieves views and submissions for every form in a single DB call and
* stores the result in $stats keyed by form ID. No-ops when $form_ids is
* empty or non-array, or when the analytics DB object is unavailable.
*
* Hooks: wpforms_admin_forms_list_table_prepare_items_after (action). The
* parameter is untyped because the action's payload depends on the dispatcher
* (`ListTable::prepare_items()`), which may pass a non-array if the items
* lookup degraded - keeping this method tolerant prevents a fatal in that path.
*
* @since 2.0.0
*
* @param mixed $form_ids Form IDs (expected: int[]).
*/
public function prefetch_stats( $form_ids ): void {
if ( ! is_array( $form_ids ) || empty( $form_ids ) ) {
$this->stats = [];
return;
}
$db = wpforms()->obj( 'analytics_db' );
if ( ! $db ) {
$this->stats = [];
return;
}
$this->stats = $db->get_overview_stats( $form_ids );
}
/**
* Hide the Shortcode column by default on the Forms Overview screen.
*
* Hooks: default_hidden_columns (filter, priority 11). Runs after
* ListTable::default_hidden_columns() (priority 10), receives its output,
* gates on the same screen ID + Columns::has_selected_columns() conditions,
* and appends 'shortcode' to keep the analytics columns visually grouped
* after Entries on first visit.
*
* @since 2.0.0
*
* @param mixed $hidden Hidden columns array (filter input may be non-array).
* @param mixed $screen WP_Screen-like object for the current admin screen.
*
* @return array
*/
public function set_column_defaults( $hidden, $screen ): array {
$hidden = (array) $hidden;
if ( ! is_object( $screen ) || ! isset( $screen->id ) || $screen->id !== 'toplevel_page_wpforms-overview' ) {
return $hidden;
}
if ( Columns::has_selected_columns() ) {
return $hidden;
}
$hidden[] = 'shortcode';
return $hidden;
}
/**
* Render the Views column cell.
*
* @since 2.0.0
*
* @param int $form_id Form ID.
*
* @return string
*/
private function render_views( int $form_id ): string {
$views = $this->stats[ $form_id ]['views'] ?? null;
if ( $views === null ) {
return '—';
}
$value = number_format_i18n( (int) $views );
if ( ! wpforms()->is_pro() ) {
return $value;
}
if ( ! ProAnalytics::is_allowed() ) {
return $value;
}
return $this->build_analytics_link( $form_id, 'views', $value );
}
/**
* Render the Interactions column cell.
*
* On Lite, returns the Pro upgrade badge. On Pro with stats present,
* returns a link to the Analytics page for the given form.
* Returns a dash on Pro when the form has no stats.
*
* @since 2.0.0
*
* @param int $form_id Form ID.
*
* @return string
*/
private function render_interactions( int $form_id ): string {
if ( ! wpforms()->is_pro() || ! ProAnalytics::is_allowed() ) {
return $this->render_pro_badge( __( 'Upgrade to Pro to unlock Interactions', 'wpforms-lite' ) );
}
$interactions = $this->stats[ $form_id ]['interactions'] ?? null;
if ( $interactions === null ) {
return '—';
}
return $this->build_analytics_link( $form_id, 'interactions', number_format_i18n( (int) $interactions ) );
}
/**
* Render the Pro upgrade teaser for locked columns (Lite only).
*
* Outputs a blurred-value image wrapped in the education-modal link, so the
* locked metric reads as "there is data here, upgrade to see it". Both gated
* columns (Interactions, Conversion) share a single `analytics-upgrade`
* utm_content value. The `data-utm-medium` attribute is read by the Lite
* education modal JS to override the upgrade URL's utm_medium with
* `forms-overview`.
*
* @since 2.0.0
*
* @param string $tooltip Hover title naming the locked metric (e.g. "Upgrade to Pro to unlock Interactions").
*
* @return string
*/
private function render_pro_badge( string $tooltip ): string {
return sprintf(
'',
esc_attr__( 'Form Analytics', 'wpforms-lite' ),
esc_url( WPFORMS_PLUGIN_URL . 'assets/images/education/analytics-preview.png' ),
esc_url( WPFORMS_PLUGIN_URL . 'assets/images/education/blurred-value.svg' ),
esc_attr__( 'Upgrade to Pro', 'wpforms-lite' ),
esc_attr( $tooltip )
);
}
/**
* Render the Conversion column cell.
*
* @since 2.0.0
*
* @param int $form_id Form ID.
*
* @return string
*/
private function render_conversion( int $form_id ): string {
if ( ! wpforms()->is_pro() || ! ProAnalytics::is_allowed() ) {
return $this->render_pro_badge( __( 'Upgrade to Pro to unlock Conversion Rate', 'wpforms-lite' ) );
}
$value = $this->calculate_conversion_value( $this->stats[ $form_id ] ?? null );
if ( $value === null ) {
return '—';
}
return $this->build_analytics_link( $form_id, 'conversion', $value );
}
/**
* Compute the formatted conversion-rate string for a form's stats.
*
* @since 2.0.0
*
* @param array|null $stats Pre-fetched stats for the form, or null when absent.
*
* @return string|null Formatted "NN.N%" value, or null when stats are missing or views are zero.
*/
private function calculate_conversion_value( ?array $stats ): ?string {
if ( ! $stats ) {
return null;
}
$views = (int) ( $stats['views'] ?? 0 );
$submissions = (int) ( $stats['submissions'] ?? 0 );
if ( $views <= 0 ) {
return null;
}
$rate = round( ( $submissions / $views ) * 100, 1 );
return number_format_i18n( $rate, 1 ) . '%';
}
/**
* Build the Analytics-page link markup for a populated column cell (Pro).
*
* @since 2.0.0
*
* @param int $form_id Form ID the link targets.
* @param string $css_modifier Column suffix for the link CSS class.
* @param string $value Display value (escaped on output).
*
* @return string Anchor markup pointing at the form's Analytics page.
*/
private function build_analytics_link( int $form_id, string $css_modifier, string $value ): string {
return sprintf(
'%3$s',
esc_url( admin_url( 'admin.php?page=wpforms-analytics&form_id=' . $form_id ) ),
esc_attr( $css_modifier ),
esc_html( $value )
);
}
/**
* Render the Form Analytics feature-discovery tooltip on Forms Overview.
*
* @since 2.0.0
*/
public function render_feature_tooltip(): void {
if ( ! $this->should_render_feature_tooltip() ) {
return;
}
$tooltip = wpforms()->obj( 'education_feature_tooltip' );
if ( ! $tooltip ) {
return;
}
/**
* Filter the Learn More URL for the Form Analytics feature-discovery tooltip.
*
* @since 2.0.0
*
* @param string $url Default UTM-wrapped wpforms.com URL.
*/
$learn_more_url = apply_filters(
'wpforms_admin_forms_analytics_render_feature_tooltip_learn_more_url',
wpforms_utm_link(
AnalyticsFeature::DOC_URL,
'forms-overview',
'Analytics Feature Tooltip'
)
);
$button = wpforms()->is_pro() && ProAnalytics::is_allowed()
? [
'text' => esc_html__( 'View Analytics', 'wpforms-lite' ),
'url' => add_query_arg( 'page', 'wpforms-analytics', admin_url( 'admin.php' ) ),
'classes' => 'wpforms-btn wpforms-btn-sm wpforms-btn-orange wpforms-education-feature-tooltip-view',
]
: [
'text' => esc_html__( 'Upgrade to Pro', 'wpforms-lite' ),
'url' => '#',
'classes' => 'wpforms-btn wpforms-btn-sm wpforms-btn-orange education-modal',
'data' => [
'name' => esc_attr__( 'Form Analytics', 'wpforms-lite' ),
'license' => 'pro',
'action' => 'upgrade',
'banner-src' => WPFORMS_PLUGIN_URL . 'assets/images/education/analytics-preview.png',
'utm-medium' => 'forms-overview',
'utm-content' => 'analytics-feature-tooltip',
],
];
$tooltip->render(
[
'title' => esc_html__( 'Form Analytics', 'wpforms-lite' ),
'badge' => esc_html__( 'NEW', 'wpforms-lite' ),
'text' => esc_html__( 'Monitor views, conversions, and field-level activity to optimize performance.', 'wpforms-lite' ),
'section' => 'analytics-feature-discovery',
'learn_more_url' => $learn_more_url,
'button' => $button,
]
);
}
/**
* Whether the Form Analytics feature-discovery tooltip should render.
*
* Gates on the current admin screen and the per-user dismissal flag stored
* in the `wpforms_dismissed` user meta map.
*
* @since 2.0.0
*
* @return bool True when the tooltip should render on this request.
*/
private function should_render_feature_tooltip(): bool {
$screen = get_current_screen();
$screen_id = $screen->id ?? '';
if ( ! $screen || $screen_id !== 'toplevel_page_wpforms-overview' ) {
return false;
}
$dismissed = (array) get_user_meta( get_current_user_id(), 'wpforms_dismissed', true );
return empty( $dismissed['edu-analytics-feature-discovery'] );
}
}