$args `default` source, `allow_all` to offer
* the "every campaign" option.
*/
protected function register_product_controls( array $args = array() ): void {
$allow_all = ! empty( $args['allow_all'] );
$default = (string) ( $args['default'] ?? 'manual' );
$sources = array();
if ( $allow_all ) {
$sources['all'] = esc_html__( 'All campaigns', 'styleraise' );
}
$sources['manual'] = esc_html__( 'Pick a campaign', 'styleraise' );
$sources['current'] = esc_html__( 'Current post / loop item', 'styleraise' );
$sources['tag'] = esc_html__( 'Dynamic tag or custom value', 'styleraise' );
$sources['dynamic'] = esc_html__( 'Post meta field', 'styleraise' );
$this->add_control(
'product_source',
array(
'label' => esc_html__( 'Campaign Source', 'styleraise' ),
'type' => Controls_Manager::SELECT,
'default' => $default,
'options' => $sources,
)
);
$this->add_control(
'product_id_manual',
array(
'label' => esc_html__( 'Campaign', 'styleraise' ),
'type' => Controls_Manager::SELECT2,
'options' => Product_Resolver::get_options(),
'default' => '',
'label_block' => true,
'condition' => array( 'product_source' => 'manual' ),
'description' => esc_html__( 'Only products with donations enabled are listed.', 'styleraise' ),
)
);
$this->add_control(
'product_id_tag',
array(
'label' => esc_html__( 'Product ID', 'styleraise' ),
'type' => Controls_Manager::TEXT,
'default' => '',
'label_block' => true,
'dynamic' => array( 'active' => true ),
'condition' => array( 'product_source' => 'tag' ),
'description' => esc_html__( 'Accepts a literal ID or any dynamic tag that resolves to one — an ACF field, a JetEngine value, the WCDP Product ID tag.', 'styleraise' ),
)
);
$this->add_control(
'product_meta_key',
array(
'label' => esc_html__( 'Meta Key', 'styleraise' ),
'type' => Controls_Manager::TEXT,
'default' => '',
'label_block' => true,
'placeholder' => 'collection_select',
'condition' => array( 'product_source' => 'dynamic' ),
'description' => esc_html__( 'Custom field on the current post that stores the product ID.', 'styleraise' ),
)
);
if ( 'all' !== $default ) {
$this->add_control(
'product_source_notice',
array(
'type' => Controls_Manager::RAW_HTML,
'raw' => '
' . esc_html__( 'In an archive or Loop Grid template, choose "Current post / loop item" so every card shows its own campaign.', 'styleraise' ) . '
',
'condition' => array( 'product_source' => 'manual' ),
)
);
}
}
/**
* Register the controls that adjust the campaign totals.
*
* @param array $args Reserved for future use.
*/
protected function register_campaign_data_controls( array $args = array() ): void {
unset( $args );
$this->add_control(
'goal',
array(
'label' => esc_html__( 'Goal Override', 'styleraise' ),
'type' => Controls_Manager::NUMBER,
'default' => '',
'min' => 0,
'dynamic' => array( 'active' => true ),
'description' => esc_html__( 'Leave empty to use the goal set on the product.', 'styleraise' ),
)
);
$this->add_control(
'cheat',
array(
'label' => esc_html__( 'Amount Correction', 'styleraise' ),
'type' => Controls_Manager::NUMBER,
'default' => '',
'dynamic' => array( 'active' => true ),
'description' => esc_html__( 'Added to the raised total, for example to include offline donations. Can be negative.', 'styleraise' ),
)
);
$this->add_control(
'addids',
array(
'label' => esc_html__( 'Additional Product IDs', 'styleraise' ),
'type' => Controls_Manager::TEXT,
'default' => '',
'label_block' => true,
'dynamic' => array( 'active' => true ),
'description' => esc_html__( 'Comma-separated IDs whose donations are added to this campaign.', 'styleraise' ),
)
);
$this->add_control(
'combine_translations',
array(
'label' => esc_html__( 'Combine Translations', 'styleraise' ),
'type' => Controls_Manager::SWITCHER,
'return_value' => 'yes',
'default' => 'yes',
'description' => esc_html__( 'With Polylang or WPML active, add the donations of every translation of this product. Turn off if each language is a separate campaign.', 'styleraise' ),
)
);
}
/**
* Register the per-widget override for live figure refreshing.
*
* Site policy lives in the settings screen; this exists because one page
* rarely wants one answer. A hero progress bar under paid traffic should
* refresh, while a grid of fifty archive cards showing the same figures
* should not pay for it.
*/
protected function register_live_control(): void {
$this->add_control(
'live_updates',
array(
'label' => esc_html__( 'Live Updates', 'styleraise' ),
'type' => Controls_Manager::SELECT,
'default' => 'inherit',
'separator' => 'before',
'options' => array(
'inherit' => esc_html__( 'Follow site setting', 'styleraise' ),
'on' => esc_html__( 'Always refresh', 'styleraise' ),
'off' => esc_html__( 'Never refresh', 'styleraise' ),
),
'description' => esc_html__( 'Page caches serve the figures that were current when the page was cached. Refreshing fetches the real ones after load, so a cached page still shows the truth.', 'styleraise' ),
)
);
}
/* ─────────────────────────── Data helpers ─────────────────────────── */
/**
* Product ID this widget instance refers to.
*
* @return int
*/
protected function get_product_id(): int {
return Product_Resolver::resolve( $this->get_settings_for_display() );
}
/**
* Campaign snapshot for this widget instance.
*
* @return Campaign|null
*/
protected function get_campaign() {
$settings = $this->get_settings_for_display();
$product_id = Product_Resolver::resolve( $settings );
if ( ! $product_id ) {
return null;
}
return Campaign::get( $product_id, $this->build_campaign_args( $product_id, $settings ) );
}
/**
* Assemble the campaign arguments from widget settings.
*
* @param int $product_id Resolved product ID.
* @param array $settings Widget settings.
* @return array
*/
protected function build_campaign_args( int $product_id, array $settings ): array {
$addids = array();
if ( ! empty( $settings['addids'] ) ) {
$addids = array_map( 'absint', array_map( 'trim', explode( ',', (string) $settings['addids'] ) ) );
}
if ( 'yes' === ( $settings['combine_translations'] ?? 'yes' ) ) {
$addids = array_merge( $addids, Product_Resolver::get_translation_ids( $product_id ) );
}
return array(
'goal' => isset( $settings['goal'] ) && is_numeric( $settings['goal'] ) ? (float) $settings['goal'] : '',
'cheat' => isset( $settings['cheat'] ) && is_numeric( $settings['cheat'] ) ? (float) $settings['cheat'] : 0,
'addids' => array_values( array_filter( $addids ) ),
// Reaches the probe, so the chosen symbol position also applies to
// the amounts WCDP formats in "match the site" mode.
'currency_position' => (string) ( $settings['currency_position'] ?? '' ),
);
}
/* ─────────────────────────── Render helpers ─────────────────────────── */
/**
* Whether the current render happens inside the Elementor editor.
*
* @return bool
*/
protected function is_editor(): bool {
return Product_Resolver::is_elementor_render_context();
}
/**
* Print an editor-only placeholder explaining why nothing rendered.
*
* Stays silent on the frontend: a visitor should see an empty space, never
* a configuration hint.
*
* @param string $message Explanation shown to the editor.
*/
protected function render_placeholder( string $message ): void {
if ( ! $this->is_editor() ) {
return;
}
printf(
'%1$s%2$s
',
esc_html( $this->get_title() ),
esc_html( $message )
);
}
/**
* Placeholder text tailored to the configured campaign source.
*
* @return string
*/
protected function get_unresolved_message(): string {
$settings = $this->get_settings_for_display();
$source = (string) ( $settings['product_source'] ?? 'manual' );
switch ( $source ) {
case 'current':
return esc_html__( 'No donation product in the current context. Set a Preview Post in the Elementor settings, or place this widget in a product template or loop.', 'styleraise' );
case 'tag':
return esc_html__( 'The dynamic tag did not resolve to a product with donations enabled.', 'styleraise' );
case 'dynamic':
return empty( $settings['product_meta_key'] )
? esc_html__( 'Enter the meta key that stores the product ID.', 'styleraise' )
: esc_html__( 'The meta field is empty on this post, or it points to a product without donations enabled. A Preview Post may be required.', 'styleraise' );
case 'manual':
default:
return esc_html__( 'Pick a campaign, or switch the source to "Current post / loop item".', 'styleraise' );
}
}
/**
* Documentation link shown in the panel header.
*
* @return string
*/
public function get_custom_help_url(): string {
return 'https://www.wc-donation.com/documentation/';
}
}