# Module System

Convert Plus ships with three conversion modules. Each module is a self-contained unit with its own class, views, themes, presets, and assets.

## Registered Modules

Modules are registered in `modules/config.php` and stored in the `convert_plug_modules` WordPress option.

| Module | Slug | Class | File |
|--------|------|-------|------|
| Modal Popup | `Modal_Popup` | `Smile_Modals` | `modules/modal/class-smile-modals.php` |
| Info Bar | `Info_Bar` | `Smile_Info_Bars` | `modules/info_bar/class-smile-info-bars.php` |
| Slide In Popup | `Slide_In_Popup` | `Smile_Slide_Ins` | `modules/slide_in/class-smile-slide-ins.php` |

## Module Registration

`modules/config.php` calls `convert_plug_add_module()` (defined in `modules/modules-functions.php`) with an array of module definitions:

```php
$modules = array(
    'Modal Popup' => array(
        'file' => 'modal/class-smile-modals.php',
        'img'  => CP_PLUGIN_URL . 'modules/modal/assets/img/modal.jpg',
        'desc' => '...',
    ),
    // ...
);
convert_plug_add_module( $modules );
```

On first activation, all three modules are enabled. Modules can be toggled from the admin **Modules** page (`Admin > Convert Plus > Modules`).

## Module Directory Structure

Each module follows the same directory layout:

```
modules/{module_name}/
├── class-smile-{module}.php     ← Main module class
├── Gruntfile.js                 ← Per-module Grunt tasks
├── package.json
├── assets/
│   ├── css/                     ← Compiled CSS
│   ├── js/                      ← Compiled JS
│   └── img/                     ← Module preview image
├── functions/
│   ├── functions.php            ← Module-specific PHP helpers
│   ├── functions.common.php     ← Shared rendering helpers
│   └── functions.options.php    ← Option definitions
├── views/
│   ├── main.php                 ← Campaign list view
│   ├── new-style.php            ← New style/campaign creation
│   ├── edit.php                 ← Style editor view
│   ├── analytics.php            ← Per-style analytics view
│   ├── variant.php              ← A/B variant management
│   └── variant/                 ← Variant sub-views
├── themes/                      ← Pre-built design templates
└── presets/                     ← Importable preset configurations
```

## Modal Popup

A lightbox-style overlay. Supports:
- Custom height via `cp_custom_height` / `cp_modal_height` settings
- Overlay animation and disable-animation-below-width (`hide_animation_width`)
- Affiliate link support
- All standard display triggers (see Display Triggers below)

Key function: `cp_generate_style_css( $a )` — emits inline `<style>` for per-modal overrides.

## Slide-In Popup

Slides in from a configurable corner of the screen. Contains a Social Media Bar component (`framework/functions/component-social-media.php`).

## Info Bar

A sticky bar anchored to the top or bottom of the viewport. Supports countdown timer component (`framework/functions/component-count-down.php`).

## Display Triggers

All three modules share the same trigger system (handled in `modules/modules-functions.php` and the module JS):

| Trigger | Description |
|---------|-------------|
| Time delay | Show after N seconds |
| Scroll depth | Show when user scrolls X% of page |
| Exit intent | Show when cursor moves toward browser chrome |
| After content | Show when user reaches end of post content |
| Click | Show on element click |
| Inactivity | Show after N seconds of no interaction |

## Targeting Options

Targeting is configured per-campaign and evaluated by `get_quick_behavior_settings()` in `admin/ajax-actions.php`:

- Page/post targeting (include/exclude by ID, category, tag, custom taxonomy)
- User role targeting
- Device targeting (desktop/mobile/tablet)
- Geolocation targeting (country, via MaxMind GeoLite2 — see [Geolocation Targeting](Geolocation-Targeting))
- Cookie-based suppression

## A/B Variant Testing

Each style (campaign) supports multiple variants. Variant settings are managed via:

- `update_variant_test_settings` AJAX action
- Views in `modules/{module}/views/variant/`

## Shared Functions (`modules/modules-functions.php`)

Key shared functions:

| Function | Description |
|----------|-------------|
| `cp_get_form_hidden_fields( $a )` | Generates hidden form fields for mailer/subscription |
| `convert_plug_add_module( $modules )` | Registers modules into `Smile_Framework::$modules` |

### Form Submission Flow

1. Visitor submits an opt-in form inside a campaign
2. Hidden fields (generated by `cp_get_form_hidden_fields`) carry: `mailer_id`, `list_id`, `style_id`, `nonce`
3. AJAX handler `cp_add_subscriber` validates the nonce and routes submission to the correct provider
4. If provider is `Convert Plug` (no external integration), subscriber is stored directly in `smile_lists[{list_id}]`

## Preview

Live preview is available in the style editor. Preview AJAX actions:

- `wp_ajax_cp_display_preview_modal`
- `wp_ajax_cp_display_preview_info_bar`
- `wp_ajax_cp_display_preview_slide_in`

## Export / Import

Each module supports export to `.zip` and import from `.zip`:

- Export actions: `cp_export_modal_action`, `cp_export_infobar_action`, `cp_export_slidein_action`
- Import: `cp_import_presets`, `cp_import_presets_step2`

## Related Pages

- [Smile Framework](Smile-Framework)
- [Campaigns and Contacts](Campaigns-and-Contacts)
- [AJAX Actions Reference](AJAX-Actions-Reference)
- [Geolocation Targeting](Geolocation-Targeting)