# Developer Guide

This guide is for developers who want to customize or extend BuddyPress Check-ins. Here you'll find information about hooks, filters, template overrides, and code examples.

---

## Overview

BuddyPress Check-ins stores location data as BuddyPress activity meta. When a user posts an activity with a check-in, the location information is saved alongside the activity.

### Plugin Structure

```
bp-check-in/
├── admin/                  # Admin-related files
│   ├── class-bp-checkins-admin.php
│   ├── css/               # Admin stylesheets
│   ├── js/                # Admin JavaScript
│   └── includes/          # Admin settings templates
├── includes/              # Core plugin files
│   ├── class-bp-checkins.php           # Main plugin class
│   ├── class-bp-checkins-loader.php    # Action/filter loader
│   ├── class-bp-checkins-globals.php   # Global settings
│   └── bp-checkins-functions.php       # Helper functions
├── public/                # Frontend files
│   ├── class-bp-checkins-public.php    # Public-facing functionality
│   ├── css/               # Public stylesheets
│   ├── js/                # Public JavaScript
│   └── templates/         # Template files
└── languages/             # Translation files
```

---

## Hooks and Filters

### Filters

#### `bpchk_activity_listing_per_page_user_profile`

Controls how many check-ins are displayed per page on the user profile Check-ins tab.

**Default:** 10

**Example:**
```php
add_filter( 'bpchk_activity_listing_per_page_user_profile', function( $per_page ) {
    return 20; // Show 20 check-ins per page
} );
```

---

#### `bpchk_member_profile_checkin_tab_slug`

Filters the URL slug for the Check-ins tab on member profiles.

**Example:**
```php
add_filter( 'bpchk_member_profile_checkin_tab_slug', function( $slug ) {
    return 'my-locations'; // Changes URL to /members/username/my-locations/
} );
```

---

#### `bpchk_member_profile_checkin_tab_name`

Filters the display name of the Check-ins tab.

**Example:**
```php
add_filter( 'bpchk_member_profile_checkin_tab_name', function( $name ) {
    return __( 'Travel Log', 'your-theme' );
} );
```

---

#### `bpchk_core_template_plugin`

Filters which template file is loaded for the Check-ins profile tab.

**Default:** `members/single/plugins`

**Example:**
```php
add_filter( 'bpchk_core_template_plugin', function( $template ) {
    return 'members/single/custom-checkins';
} );
```

---

#### `bpchk_activity_new_checkin_action`

Filters the activity action text when a user posts a check-in.

**Parameters:**
- `$action` (string) - The activity action text
- `$activity` (object) - The BuddyPress activity object

**Example:**
```php
add_filter( 'bpchk_activity_new_checkin_action', function( $action, $activity ) {
    // Customize the check-in action text
    return sprintf(
        '%s shared their location',
        bp_core_get_userlink( $activity->user_id )
    );
}, 10, 2 );
```

---

#### `bpchk_enqueue_checkins_assets`

Controls whether check-in assets (CSS/JS) should be loaded on the current page.

**Parameters:**
- `$should_enqueue` (bool) - Whether to enqueue assets
- `$post` (object) - Current post object
- `$checkin_tab_slug` (string) - The check-ins tab slug
- `$current_component` (string) - Current BuddyPress component

**Example:**
```php
add_filter( 'bpchk_enqueue_checkins_assets', function( $should_enqueue, $post, $tab_slug, $component ) {
    // Also load on a custom page
    if ( is_page( 'my-custom-page' ) ) {
        return true;
    }
    return $should_enqueue;
}, 10, 4 );
```

---

## Activity Meta

Check-in data is stored in BuddyPress activity meta. Here's how to access it:

### Get Check-in Location

```php
// Get location name for an activity
$location = bp_activity_get_meta( $activity_id, 'bpchk_place_name', true );

// Get full address
$address = bp_activity_get_meta( $activity_id, 'bpchk_place_address', true );

// Get coordinates
$latitude = bp_activity_get_meta( $activity_id, 'bpchk_lat', true );
$longitude = bp_activity_get_meta( $activity_id, 'bpchk_lng', true );
```

### Meta Keys Reference

| Meta Key | Description | Example Value |
|----------|-------------|---------------|
| `bpchk_place_name` | Place/business name | "Central Park" |
| `bpchk_place_address` | Full address | "New York, NY 10024, USA" |
| `bpchk_lat` | Latitude | "40.7812199" |
| `bpchk_lng` | Longitude | "-73.9665138" |
| `bpchk_place_id` | Google Place ID | "ChIJ4zGFAZpYwokRGUGph3Mf37k" |

---

## Template Overrides

You can override the plugin's templates in your theme.

### Template Location

To override a template, copy it from:
```
wp-content/plugins/bp-check-in/public/templates/
```

To your theme:
```
wp-content/themes/your-theme/bp-check-in/
```

### Available Templates

| Template | Purpose |
|----------|---------|
| `checkin/bp-checkins-activity.php` | Check-ins listing on profile |

### Example: Custom Check-ins Template

1. Create folder: `your-theme/bp-check-in/checkin/`
2. Copy `bp-checkins-activity.php` to this folder
3. Modify as needed

---

## JavaScript Events

The plugin triggers JavaScript events you can hook into:

### Location Selected Event

```javascript
// Listen for when a location is selected
document.addEventListener( 'bpchk_location_selected', function( event ) {
    console.log( 'Location selected:', event.detail );
    // event.detail contains: place_name, address, lat, lng, place_id
} );
```

### Check-in Form Events

```javascript
// Before check-in is added
jQuery( document ).on( 'bpchk_before_checkin', function( e, data ) {
    console.log( 'About to add check-in:', data );
} );

// After check-in is added
jQuery( document ).on( 'bpchk_after_checkin', function( e, data ) {
    console.log( 'Check-in added:', data );
} );
```

---

## Database Structure

Check-in data is stored in the BuddyPress activity meta table.

### Table: `wp_bp_activity_meta`

| Column | Description |
|--------|-------------|
| `id` | Meta ID |
| `activity_id` | Related activity ID |
| `meta_key` | Meta key (bpchk_*) |
| `meta_value` | Meta value |

### Query Check-ins Directly

```php
global $wpdb;
$bp = buddypress();

// Get all activities with check-ins
$activities_with_checkins = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT DISTINCT a.id, a.content, am.meta_value as location
         FROM {$bp->activity->table_name} a
         INNER JOIN {$bp->activity->table_name_meta} am
         ON a.id = am.activity_id
         WHERE am.meta_key = %s",
        'bpchk_place_name'
    )
);
```

---

## Adding Custom Fields to Check-ins

### Step 1: Add Field to Form

```php
add_action( 'bpchk_after_location_field', function() {
    ?>
    <div class="bpchk-custom-field">
        <label for="bpchk-custom-note">
            <?php esc_html_e( 'Notes', 'your-theme' ); ?>
        </label>
        <input type="text" name="bpchk_custom_note" id="bpchk-custom-note" />
    </div>
    <?php
} );
```

### Step 2: Save Custom Field

```php
add_action( 'bp_activity_posted_update', function( $content, $user_id, $activity_id ) {
    if ( isset( $_POST['bpchk_custom_note'] ) ) {
        bp_activity_update_meta(
            $activity_id,
            'bpchk_custom_note',
            sanitize_text_field( wp_unslash( $_POST['bpchk_custom_note'] ) )
        );
    }
}, 10, 3 );
```

---

## CSS Customization

### Available CSS Classes

| Class | Element |
|-------|---------|
| `.bpchk-activity-checkin` | Check-in container in activity |
| `.bpchk-place-name` | Location name |
| `.bpchk-place-address` | Location address |
| `.bpchk-map-preview` | Map preview container |
| `.bpchk-location-icon` | Location icon in post form |
| `.bpchk-checkin-panel` | Location search panel |

### Example: Custom Styling

```css
/* Style the check-in location */
.bpchk-activity-checkin {
    background: #f5f5f5;
    padding: 10px;
    border-radius: 4px;
    margin-top: 10px;
}

/* Style the location name */
.bpchk-place-name {
    font-weight: bold;
    color: #333;
}

/* Hide map preview */
.bpchk-map-preview {
    display: none;
}
```

---

## Best Practices

### Performance

1. **Cache location data** when displaying multiple check-ins
2. **Use transients** for frequently accessed location queries
3. **Lazy load maps** when possible

### Security

1. **Always sanitize** location data before saving
2. **Escape output** when displaying location data
3. **Validate Google Place IDs** before use

### Compatibility

1. **Check for BuddyPress** before using BP functions
2. **Use plugin version checks** for deprecated features
3. **Test with BuddyBoss Platform** if supporting both

---

## Example: Display Recent Check-ins Widget

```php
function bpchk_recent_checkins_widget() {
    global $wpdb;
    $bp = buddypress();

    // Get recent check-ins
    $checkins = $wpdb->get_results(
        $wpdb->prepare(
            "SELECT a.id, a.user_id, am.meta_value as place_name, a.date_recorded
             FROM {$bp->activity->table_name} a
             INNER JOIN {$bp->activity->table_name_meta} am
             ON a.id = am.activity_id
             WHERE am.meta_key = %s
             ORDER BY a.date_recorded DESC
             LIMIT %d",
            'bpchk_place_name',
            10
        )
    );

    if ( empty( $checkins ) ) {
        echo '<p>' . esc_html__( 'No recent check-ins.', 'your-theme' ) . '</p>';
        return;
    }

    echo '<ul class="recent-checkins">';
    foreach ( $checkins as $checkin ) {
        printf(
            '<li>%s checked in at %s</li>',
            bp_core_get_userlink( $checkin->user_id ),
            esc_html( $checkin->place_name )
        );
    }
    echo '</ul>';
}
```

---

## Support

For developer support:
- [Plugin Documentation](./getting-started.md)
- [GitHub Repository](https://github.com/wbcomdesigns/buddypress-check-in)
- [Support Contact](https://wbcomdesigns.com/contact)