# Featured Items

This feature adds a first-class `is_featured` flag to `collection_data` so the API can save and filter featured records without storing that state inside the JSON `data` field.

---

## What Changed

- `collection_data` now has a top-level `is_featured` column.
- `POST /api/collection-data/save.php` accepts `is_featured` when creating or updating a record.
- `GET /api/collection-data/list.php` accepts `is_featured=1` or `is_featured=0`.
- `GET /api/collection-data/paged-list.php` accepts `is_featured=1` or `is_featured=0`.
- `POST /api/collection-data/find.php` accepts `is_featured: true` or `false` in the request body.

---

## Database

Run [../sql/add_is_featured_to_collection_data.sql](../sql/add_is_featured_to_collection_data.sql) against an existing database.

The column is defined as:

```sql
is_featured TINYINT(1) NOT NULL DEFAULT 0
```

This keeps non-featured rows at `0` by default and makes featured filtering indexable.

---

## Save Examples

Create a featured record:

```json
{
  "id": 0,
  "collection_id": "customers",
  "parent_id": 0,
  "website_id": "fieldforge",
  "is_featured": true,
  "data": {
    "name": "Acme Corp",
    "email": "info@acme.com"
  }
}
```

Update an existing record to featured:

```json
{
  "id": 43,
  "collection_id": "customers",
  "parent_id": 0,
  "website_id": "fieldforge",
  "is_featured": true,
  "data": {
    "name": "Acme Corp",
    "email": "info@acme.com"
  }
}
```

Unset featured:

```json
{
  "id": 43,
  "collection_id": "customers",
  "parent_id": 0,
  "website_id": "fieldforge",
  "is_featured": false,
  "data": {
    "name": "Acme Corp",
    "email": "info@acme.com"
  }
}
```

---

## Read Examples

List featured records for a collection and website:

```http
GET /api/collection-data/list.php?collectionId=customers&websiteId=fieldforge&is_featured=1
```

List non-featured records:

```http
GET /api/collection-data/list.php?collectionId=customers&websiteId=fieldforge&is_featured=0
```

Find featured records with POST:

```json
{
  "collection_id": "customers",
  "website_id": "fieldforge",
  "is_featured": true,
  "limit": 1,
  "sortBy": "updated_at",
  "sortOrder": "DESC"
}
```

---

## Angular Notes

The Angular service is assumed to already exist. Add `is_featured?: boolean` to the request/record interfaces and send it as a top-level field, not inside `data`.

Suggested `list` usage:

```ts
this.collectionDataService.list(CollectionNames.Customers, {
  isFeatured: true,
}).subscribe(items => {
  this.featuredCustomer = items[0] ?? null;
});
```

Suggested `find` usage:

```ts
this.collectionDataService.find({
  collection_id: CollectionNames.Customers,
  website_id: CollectionNames.WebsiteId,
  is_featured: true,
  limit: 1,
}).subscribe(items => {
  this.featuredCustomer = items[0] ?? null;
});
```

---

## Rule

Do not store `is_featured` inside `data`. Keep it as a top-level column so the backend can query it efficiently by `collection_id` and `website_id`.