# Wallboard Quick Filters & Filtered Folders Complete Guide

## Quick Filters Overview

Quick Filters are reusable, complex query definitions that enable sophisticated content and device selection across multiple areas of the Wallboard system.

### Supported Entity Types
Quick Filters can be created for:
- **Devices**: Complex device selection based on multiple criteria
- **Content**: Advanced content filtering and selection
- **Media Files**: File-based filtering with various criteria
- **System Data Sources**: Integration with system-level data filtering

### Quick Filter Creation Process

#### Creation Methods
**Two approaches for creating Quick Filters:**

1. **Graphical Editor**: Visual interface for building filter criteria
2. **Query Language (WBQL)**: Direct Wallboard Query Language for advanced users

##### WBQL (Wallboard Query Language) Syntax

**Basic Structure:**
```
attribute operator value
```

**Key Operators:**

| Operator | Symbol | Description | Example |
|----------|--------|-------------|---------|
| Contains | `:` | Case-insensitive partial match | `name:john` |
| Equals | `=` | Exact match | `status=ACTIVE` |
| Starts With | `^` | String starts with value | `name^john` |
| Not Contains | `∉` | Does not contain | `name∉test` |
| Not Equals | `≠` | Not equal to | `status≠DELETED` |
| Greater Than | `>` | Numeric comparison | `size>1000` |
| Less Than | `<` | Numeric comparison | `price<100` |
| In Set | `∈` | Value in list | `status∈ACTIVE,PENDING` |
| Not In Set | `!∈` | Value not in list | `role!∈VIEWER,GUEST` |

**Logical Operators:**
- **AND**: `,` (comma) - `name:john,status=ACTIVE`
- **OR**: `|` (pipe) - `type=ADMIN|type=OWNER`
- **Grouping**: `()` - `(type=A|type=B),status=ACTIVE`

**Special Values:**
- **Null checks**: `manager=NULL` or `manager=!NULL`
- **Boolean values**: `active=true` or `deleted=false`
- **Tag matching**: `tags:important` (automatically quoted for exact match)

**WBQL Examples:**
```
Basic filtering:
name:test                           // Name contains "test"
status=ACTIVE,size>100             // Active AND size greater than 100
type=VIDEO|type=IMAGE              // Type is VIDEO OR IMAGE

Complex queries:
(tags:promotion|tags:sale),status=ACTIVE,created>2024-01-01
// (Contains promotion OR sale tags) AND active AND created after Jan 1, 2024

Device targeting:
platform=Android,status=ONLINE,(tags:store-a|tags:store-b)
// Android devices that are online in store-a OR store-b

Content selection:
type=CONTENT,tags:featured,size<10000000,published=true
// Featured content under 10MB that's published
```

**URL Encoding Note:**
When used in APIs, WBQL queries must be URL-encoded:
- Space: `%20`
- Colon: `%3A`
- Comma: `%2C`
- Pipe: `%7C`

**WBQL Filter Input:**
The screenshot shows the **Query Language** approach with:
- **Filter text area**: Direct WBQL input field for complex queries
- **Test button**: Validate WBQL syntax before saving
- **Example shown**: `name:test` - filters for items with names containing "test"

**When to use WBQL vs Graphical Editor:**
- **Graphical Editor**: User-friendly, visual filter building for basic to moderate complexity
- **WBQL**: Advanced users, complex nested logic, programmatic filter creation
- **Name**: Quick Filter identifier (required)
- **Listed**: Controls visibility in filter dropdowns across the interface
- **Teams**: Access control - which teams can use this Quick Filter
- **Filter by teams**: Data scope - which teams' data should be included in filter results
- **Starting folder**: Root directory for recursive search (applies to content and file filters)

**Advanced Configuration:**
- **Add filter**: Build complex filter criteria with multiple conditions
- **Logical operators**: Combine criteria with AND/OR logic
- **Entity-specific criteria**: Different options based on filter type (devices, content, files)

#### Entity-Specific Filter Criteria

**Device Quick Filters:**
Available filter criteria include:
- **Name**: Device name matching
- **Content**: Assigned content filtering
- **Tags**: Device tag-based selection
- **Online state**: Device connectivity status
- **Platform**: Operating system/platform type (Android, Windows, BrightSign, etc.)
- **Working hours**: Device schedule configuration
- **App version**: Wallboard application version
- **Emergency status**: Emergency mode state
- **OS version**: Device operating system version
- **License**: License type assignment (Lite, Professional, Premium, etc.)
- **License tier**: License category grouping
- **License status**: License validity and status
- **Content type**: Type of assigned content
- **Firmware version**: Device firmware version
- **Layout**: Screen layout configuration
- **Version state**: Application version status
- **Model**: Device hardware model

**Content Quick Filters:**
Available filter criteria include:
- **Name**: Content name matching
- **Type**: Content type (Content, Slide, Playlist)
- **Tags**: Content tag-based selection
- **Width**: Content width dimensions
- **Height**: Content height dimensions

**File Quick Filters:**
Available filter criteria include:
- **Name**: File name matching
- **Type**: File type/format
- **Size**: File size filtering
- **Tags**: File tag-based selection
- **Width**: Image/video width dimensions
- **Height**: Image/video height dimensions
- **Validity**: File integrity and validity checks
    - **Valid files only**: Include only valid/accessible files
    - **Are files valid by default**: Default validity assumption

#### Recursive Folder Search
**Universal Recursive Behavior:**
- All Quick Filters with folder selection automatically search recursively
- **Starting folder** serves as root directory for comprehensive search
- Searches through all nested subfolders automatically
- No option to disable recursive search - it's always enabled
- Applies to both Content and File Quick Filters

**Folder Selection Impact:**
- **Root folder (/)**: Searches entire system hierarchy
- **Specific folder**: Limits search scope to that folder and all subfolders
- **Performance consideration**: Narrower folder selection improves filter performance

### Quick Filter Reusability

#### Channel System Integration
**Dynamic Content Assignment:**
- Channels can use Quick Filters for automatic content selection
- Content automatically included/excluded based on filter criteria
- Real-time updates when content matches filter conditions

**Example Use Case:**
```
Quick Filter: "Store A Promotions"
Criteria: Tags contain "store-a" AND Tags contain "promotion"
Starting folder: /Marketing Materials/
Usage: Channel widget automatically includes matching promotional content
Result: New promotional content tagged correctly appears automatically in channel
```

#### Schedule System Integration
**Device Targeting:**
- Schedules can use Quick Filters for sophisticated device targeting
- Complex device selection without manual device list management
- Dynamic targeting based on device attributes

**Example Use Case:**
```
Quick Filter: "Retail Floor Displays"
Criteria: Tags contain "retail" AND NOT Tags contain "backoffice"
Usage: Schedule targets all retail floor devices automatically
Result: New retail devices automatically receive scheduled content
```

#### System Data Source Integration
**File System and Device Information Data Sources:**
- **File System data sources** can use Quick Filters to determine which files to include
- **Device Information data sources** can use Quick Filters to select which devices' data to aggregate
- Same filtering logic as Filtered Folders but exposed through data source interface
- Enables data-driven content with automatically filtered file/device information

## Filtered Folders vs File System Data Sources

### Concept and Relationship

**Filtered Folders** and **File System data sources with Quick Filters** provide essentially the same filtering functionality but serve different integration patterns within the Wallboard ecosystem.

**Core Similarity:**
- Both use identical Quick Filter logic to select files based on criteria
- Both provide automatic, real-time updates when files match/unmatch criteria
- Both support recursive folder searching and complex filtering rules

**Key Difference - Integration Interface:**

#### Filtered Folder Integration
**Folder Interface Pattern:**
- Appears and functions as a regular folder throughout the system
- **Playlist Integration**: Can be added to playlists like any folder
- **Gallery Widgets**: Works in gallery widgets for thumbnail displays
- **Collection Playback**: Supports all folder-based playback modes (one item, all items, specific count)
- **Media Selection**: Available in content editor wherever folder selection is needed

#### File System Data Source Integration
**Data Source Interface Pattern:**
- Exposes filtered file information as structured JSON data
- **Widget Data Binding**: Files available as data for template-driven widgets
- **Custom Content**: File metadata available for custom layouts and logic
- **Data-Driven Templates**: File lists, names, paths available as template variables
- **Dynamic Content**: File information can drive content logic and presentation

### When to Use Each Approach

#### Choose Filtered Folder When:
- **Direct file playback needed**: Playlists, media rotation, gallery displays
- **Standard folder behavior expected**: Existing folder-based workflows
- **Visual media presentation**: Thumbnail galleries, image carousels
- **Simple file inclusion**: Just want files to appear/play automatically

**Example Use Cases:**
```
Seasonal Gallery Widget → Filtered Folder: "Holiday Images"
Promotion Playlist → Filtered Folder: "Current Promotions" 
Store-Specific Media → Filtered Folder: "Store A Content"
```

#### Choose File System Data Source When:
- **File metadata needed**: Display file names, sizes, creation dates
- **Custom presentation logic**: Template-driven file displays
- **Complex file information**: Need structured data about files
- **Data-driven content**: File properties drive content behavior

**Example Use Cases:**
```
File Directory Widget → File System Data Source: List filenames in template
Asset Management Dashboard → File System Data Source: Show file metadata
Dynamic Content Selection → File System Data Source: File properties influence layout
Template-Based Galleries → File System Data Source: Custom file information display
```

### Creative Integration Patterns

#### Alternative Solutions for Same Goal
**Goal: Show current promotional images**

**Filtered Folder Approach:**
- Create Filtered Folder with criteria: tags contain "promotion" AND created within 30 days
- Add to gallery widget
- Images automatically appear/disappear

**File System Data Source Approach:**
- Create File System data source with same Quick Filter criteria
- Bind to custom widget template
- Template displays file information with custom formatting
- More control over presentation but requires template design

#### Hybrid Strategies
**Complex Content Management:**
- Use File System data source to get file metadata for decision logic
- Use Filtered Folders for actual media playback
- Combine both approaches for sophisticated content management workflows

### Key Characteristics

#### Dynamic Content Population
- **Automatic Updates**: Content appears/disappears based on filter criteria
- **Recursive Search**: Can search through nested folder structures
- **Real-time Evaluation**: Filter criteria applied continuously
- **No Manual Management**: Files automatically included/excluded

#### Integration Benefits
**Universal Folder Compatibility:**
- Any system expecting a folder can use a Filtered Folder
- **Playlist Integration**: Filtered Folders work in playlists like regular folders
- **Content Widget Integration**: Gallery widgets can use Filtered Folders
- **Collection Playback**: All folder-based playback modes supported
- **Media Selection**: Content editor can reference Filtered Folder contents

### Filtered Folder Configuration

#### Creation Process (from UI screenshots)
1. **Access**: Files → Add → Add filtered folder
2. **Name**: Specify filtered folder name (required)
3. **Target Folder**: Select root folder for recursive search (required)
4. **Teams**: Assign team permissions (optional)
5. **Quick Filter**: Select or create filter criteria (required)
6. **Add quick filter for files**: Define specific file filtering rules

#### Configuration Components

**Target Folder Selection:**
- Root directory for recursive file search
- Filter applies to all files within folder hierarchy
- Supports nested folder structures

**Team Assignment:**
- Controls access permissions for filtered folder
- Inherits team-based security model
- Can be assigned to multiple teams

**Quick Filter Integration:**
- Leverages existing Quick Filter system
- Can select pre-created Quick Filters
- Can create new filters specifically for files

**File-Specific Filter Criteria:**
- File type filtering (images, videos, documents)
- File name pattern matching
- File metadata filtering
- Date-based filtering (creation, modification dates)
- File size criteria
- Tag-based filtering for media files

### Business Use Cases

#### Content Organization
**Automatic Categorization:**
```
Filtered Folder: "Current Promotions"
Target: /Marketing Materials/
Criteria: Tags contain "promotion" AND Created date within last 30 days
Usage: Playlist automatically shows current promotional content
Benefit: Marketing team uploads files with tags, appears automatically
```

#### Geographic Content Distribution
```
Filtered Folder: "Store A Media"
Target: /Store Content/
Criteria: Tags contain "store-a" OR Filename contains "StoreA"
Usage: Store A displays automatically get relevant content
Benefit: Centralized content management with automatic distribution
```

#### Seasonal Content Management
```
Filtered Folder: "Holiday Content"
Target: /Seasonal/
Criteria: Tags contain current season AND File type = image/video
Usage: Gallery widgets automatically show seasonal content
Benefit: Content rotates seasonally without manual intervention
```

#### Asset Type Organization
```
Filtered Folder: "Video Assets"
Target: /All Media/
Criteria: File type = video AND NOT Tags contain "archive"
Usage: Video playlists automatically include active video content
Benefit: Automatic video collection without manual curation
```

### Technical Implementation

#### Performance Considerations
- **Recursive Evaluation**: Performance impact increases with folder depth
- **Filter Complexity**: Complex criteria may affect response times
- **Real-time Updates**: Changes propagate immediately to consuming widgets
- **Caching Strategy**: System caches filter results for performance

#### Limitation Awareness
- **Storage Dependencies**: Relies on proper file organization and tagging
- **Filter Accuracy**: Results only as good as filter criteria definition
- **Team Permissions**: Subject to team-based access control
- **Recursive Depth**: Deep folder structures may impact performance

### Advanced Integration Patterns

#### Multi-Level Filtering
**Nested Filtered Folders:**
- Filtered Folders can reference other Filtered Folders as target directories
- Complex hierarchical filtering strategies
- Layered content organization approaches

#### Dynamic Playlist Population
**Automatic Content Updates:**
- Playlists containing Filtered Folders update automatically
- New files matching criteria appear without playlist modification
- Content lifecycle management through filtering

#### Cross-Team Content Sharing
**Team-Based Content Distribution:**
- Filtered Folders can aggregate content across team boundaries
- Central content repository with automatic team-specific distribution
- Collaborative content management workflows

### Best Practices

#### Filter Design
- **Specific Criteria**: Use precise filter conditions to avoid unwanted content
- **Performance Optimization**: Balance filter complexity with performance requirements
- **Regular Review**: Periodically review filter effectiveness and accuracy

#### Content Management
- **Consistent Tagging**: Establish standardized tagging conventions for reliable filtering
- **Folder Structure**: Organize source folders logically for efficient filtering
- **Team Coordination**: Ensure teams understand filtering impact on content visibility

#### System Integration
- **Testing Phase**: Test filtered folders thoroughly before production deployment
- **Documentation**: Document filter logic for team understanding and maintenance
- **Monitoring**: Monitor filtered folder performance and content accuracy over time

## System-Wide Quick Filter Integration

### Universal Application
Quick Filters provide consistent selection logic across all Wallboard modules:

- **Content Management**: Dynamic content selection for channels and widgets
- **Device Management**: Complex device targeting for schedules and deployments
- **File Management**: Sophisticated file filtering for media organization
- **System Data Sources**: Advanced data selection and processing
- **Filtered Folders**: Automated content aggregation and distribution

### Operational Benefits
- **Consistency**: Same filter logic applicable across different contexts
- **Automation**: Reduces manual content and device management overhead
- **Scalability**: Supports large-scale deployments with complex targeting needs
- **Flexibility**: Adapts to changing organizational and content requirements