search-guides

Quick Reference Guides

Adding a New Provider

Step 1: Create Provider Class

app/src/main/java/com/mrndstvndv/search/provider/{type}/{Name}Provider.kt

Step 2: Implement Provider Interface

class NewProvider(
    private val context: Context,
    private val settingsRepository: ProviderSettingsRepository
) : Provider {
    
    override val id = "new-provider"
    override val displayName = "New Provider"
    override val refreshSignal = MutableSharedFlow<Unit>()
    
    override fun initialize() { /* Heavy setup */ }
    
    override fun canHandle(query: Query): Boolean {
        return query.text.isNotBlank()
    }
    
    override suspend fun query(query: Query): List<ProviderResult> {
        // Return search results
    }
    
    override fun dispose() { /* Cleanup */ }
}

Step 3: Register in MainActivity (~line 150)

val providers = remember {
    listOf(
        // ... existing providers
        NewProvider(context, settingsRepository)
    )
}

Step 4: Add Toggle in ProvidersSettingsScreen

SettingsSwitch(
    title = "New Provider",
    checked = isEnabled,
    onCheckedChange = { /* save state */ }
)

Step 5: Add to DEFAULT_PROVIDER_ORDER

In ProviderRankingRepository:

private val DEFAULT_PROVIDER_ORDER = listOf(
    // ... existing IDs
    "new-provider"
)

Adding a New Setting

Step 1: Add Key Constant

In ProviderSettingsRepository:

private const val KEY_NEW_SETTING = "new_setting"

Step 2: Add StateFlow

private val _newSetting = MutableStateFlow(loadNewSetting())
val newSetting: StateFlow<Boolean> = _newSetting.asStateFlow()

Step 3: Add Load/Save Methods

private fun loadNewSetting(): Boolean {
    return prefs.getBoolean(KEY_NEW_SETTING, true)
}

fun setNewSetting(value: Boolean) {
    prefs.edit().putBoolean(KEY_NEW_SETTING, value).apply()
    _newSetting.value = value
}

Step 4: Add UI

In the appropriate settings screen:

val newSetting by settingsRepository.newSetting.collectAsState()

SettingsSwitch(
    title = "New Setting",
    description = "Description of what this does",
    checked = newSetting,
    onCheckedChange = { settingsRepository.setNewSetting(it) }
)

Adding a New Settings Screen

Step 1: Create Screen File

app/src/main/java/com/mrndstvndv/search/ui/settings/NewSettingsScreen.kt

Step 2: Implement Composable

@Composable
fun NewSettingsScreen(
    settingsRepository: ProviderSettingsRepository,
    onNavigateBack: () -> Unit
) {
    Column {
        // Back button header
        TopAppBar(
            title = { Text("New Settings") },
            navigationIcon = {
                IconButton(onClick = onNavigateBack) {
                    Icon(Icons.AutoMirrored.Filled.ArrowBack, "Back")
                }
            }
        )
        
        // Settings content
        SettingsGroup(title = "Section") {
            // Settings components...
        }
    }
}

Step 3: Add to Screen Enum

In SettingsActivity.kt:

private enum class Screen {
    // ... existing screens
    NewScreen
}

Step 4: Add Navigation Case

Screen.NewScreen -> NewSettingsScreen(
    settingsRepository = settingsRepository,
    onNavigateBack = { currentScreen = Screen.Home }
)

Step 5: Add Navigation Row

In parent screen:

SettingsNavigationRow(
    title = "New Settings",
    onClick = { onNavigate(Screen.NewScreen) }
)

Database Migrations (Room)

Step 1: Update Entity

In provider/files/index/:

@Entity(tableName = "files")
data class FileEntity(
    @PrimaryKey val path: String,
    val name: String,
    val newColumn: String = ""  // Add new field
)

Step 2: Add Migration

In FileSearchDatabase:

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "ALTER TABLE files ADD COLUMN newColumn TEXT NOT NULL DEFAULT ''"
        )
    }
}

Step 3: Increment Version and Add Migration

@Database(entities = [FileEntity::class], version = 2)
abstract class FileSearchDatabase : RoomDatabase() {
    companion object {
        fun getInstance(context: Context) = Room.databaseBuilder(...)
            .addMigrations(MIGRATION_1_2)
            .build()
    }
}

Common File Locations

Naming Conventions

Package Organization

provider/
├── Provider.kt           # Base interface
├── ProviderResult.kt     # Result model
├── model/                # Shared models (Query, etc.)
├── {type}/               # Provider implementation
│   ├── {Type}Provider.kt
│   └── {Type}Repository.kt (if needed)

ui/
├── theme/                # Design system
├── components/           # Reusable components
│   └── settings/         # Settings-specific components
└── settings/             # Settings screens

settings/                 # Non-UI settings utilities
├── ProviderSettingsRepository.kt
└── ProviderRankingRepository.kt

Design Patterns Used

Related Skills

• search-overview - Project structure and architecture
• search-provider - Provider interface details
• search-repository - Repository patterns
• search-ui - UI components and navigation
• search-build - Build configuration