AndroidBase

The AndroidBase project provides an Android app project template that setups for Gradle Kotlin DSL, it also provides some base classes or extensions to accerate your android development.

You can use this template or download the base module.

There also provides two helper branches:

If you'd like to see how the simple Gradle Kotlin DSL project works (i.e. a new android app project just created by Android Studio and use Gradle Kotlin DSL), you can checkout to the branch gradle-kotlin-dsl to take a look.
If you'd like to see how the base module works or contribute to this project, you can checkout to the branch library.

Setup for Template Project

Just click on button to create a new repo starting from this template. Or you can clone this project by git clone git@github.com:enginebai/AndroidBase.git .
Change your project name in settings.gradle.kts.
Set your application ID in Versions.kt
Set the package name in AndroidManifest.xml file of :app module .
Select com.enginebai.project directory in "Project" tool window and rename package for your app.
Specify your retrofit base URL in NetworkModule.kt file.
Start to design your main layout xml file fragment_main.xml and fragment class.
Specify your MainFragment.kt name in navigation graph xml file.
That's all. Start your app development journey now 🎉.

Get Started with Template Project

You can start your development as usual in app module.
This projects encourges you to use single activity architecture with naivgation component, you will create new fragment that extends the BaseFragment for your all UI pages.
This project uses koin as our dependency injection framework, you will define the modules in di package and add those modules in AppContext.defineDependencies()
You will handle errors with ExceptionHandler, we register a function that will handle errors that are passed to Subscriber.onError(Throwable) for RxJava; for non-RxJava exception, you will inject ExceptionHandler and pass exception to accept(Throwable) function. More detail usage you can check ExceptionHandler, there are some instructions that guide you how to write your custom exception handling logic.

Good Practices of Gradle Kotlin DSL

Add all dependencies versions in Versions.kt

object Versions {
    const val kotlin = "1.3.50"
    const val awesomeLibrary = "x.y.z"
    // TODO: add the library version
    ...
}

Define all 3rd-party dependencies in Dependencies.kt, and use all versions definition in Versions.kt.

object Dependencies {
    const val rxJava = "io.reactivex.rxjava2:rxjava:${Versions.rxJava}"
    // TODO: add standalone dependency here!
    ...

    object Kotlin {
        const val gradlePlugin = "org.jetbrains.kotlin:kotlin-gradle-plugin:${Versions.kotlin}"
        const val stdLib = "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${Versions.kotlin}"
    }

    // TODO: add inner object for sub-modules of library
    object AndroidX {
        ...
    }
    ...
}

Always import dependency from Dependencies.kt in build.gradle.kts file.

dependencies {
	implementation(Dependencies.Glide.core)
	"kapt"(Dependencies.Glide.compiler)
    implementation(project(":base"))
    // TODO: add by using dependency imported from `Dependencies.kt` file
    ...
}

Configure android build script in Config.kt.

fun Project.configAndroid() = this.extensions.getByType<BaseExtension>().run {
    compileSdkVersion(Versions.Android.sdk)
    defaultConfig {
        minSdkVersion(Versions.Android.minSdk)
        targetSdkVersion(Versions.Android.sdk)
        versionCode = Versions.App.versionCode
        versionName = Versions.App.versionName
        // TODO: add your configurations
        ...
    }
    ...
}

It's equivalent to the old way android { ... } block in build.gradle file

android {
    compileSdkVersion 21
    buildToolsVersion "21.1.2"
    defaultConfig {
        applicationId "com.enginebai.moviehunt"
        // TODO: add your configurations
        ...
    }
    ...
}

Add all configuration variables inside Config object in Config.kt, and add buildConfigField(...) to include.

object Config {
    const val API_ROOT = "\"https://api.themoviedb.org/3/\""
    const val IMAGE_API_ROOT = "\"https://image.tmdb.org/t/p/\""
    // TODO: add your constants here, make sure to add extra double quotes for string value.
}

fun Project.configAndroid() = this.extensions.getByType<BaseExtension>().run {
    compileSdkVersion(Versions.Android.sdk)
    defaultConfig {
        ...

        buildConfigField("String", "API_ROOT", Config.API_ROOT)
        buildConfigField("String", "IMAGE_API_KEY", Config.IMAGE_API_ROOT)
        // TODO: add your varialbes here imported from `Config` object
        ... 
    }
    ...
}

Add the common dependencies that share between modules to Dependencies.kt

fun Project.importCommonDependencies() {
    dependencies {
        ...
        implementation(Dependencies.material)
        // TODO: add your common dependencies
        .. 
    }
}

Note: Remember to perform Gradle Sync to apply your changes when updating any files in buildSrc.

Modules Structure

:app module: That's your app module, just like a normal Android app project. Or you can create a new modules (ex: :common) for that if you use multi-modules project or libraries. There is the sample build.gradle.kts for library module:

plugins {
    id("com.android.library")
    commonPlugins.forEach { id(it) }
}

configAndroid()
importCommonDependencies()

dependencies {
    implementation(Dependencies.whatever)
    ...
}

/buildSrc: It enables you to write the build script (*.gradle.kts files) in kotlin to manage dependencies and gets better IDE completion support. It gives you a way to develop build code more like regular code. More information please check official document.

Download for Base Module

Step 1. Add it to your root build.gradle.kts:

allprojects {
    repositories {
        ...
        maven("https://jitpack.io")
    }
}

Step 2. Add the dependency:

Versions.kt:

const val androidBase = "1.0.0"

Dependencies.kt:

const val androidBase = "com.github.enginebai:AndroidBase:${Versions.androidBase}"

App module build.gradle.kts:

dependencies {
    ...
    implementation(Dependencies.androidBase)
}

Included Libraries

There are some default 3rd-party libraries imported in this project, and provide some popular dependencies (following listed) in buildSrc/Dependencies.kt file that you can choose to use. Feel free to add/remove those dependencies.

Android Architecture Components, part of Android Jetpack for give to project a robust design, testable and maintainable.
Retrofit / OkHttp, Square open-source RESTful API and http client.
RxJava / RxAndroid, reactive programming for JVM.
Koin, kotlin light-weight dependency injection.
Timber, for logging.
Epoxy, for RecyclerView complex view layout.
Paging, for pagination loading of RecyclerView.
Navigation, for single activity and fragment routing.
Room, for local persistence database.

Useful Extensions

See Extension Functions.

LICENSE

Copyright (c) 2020 Engine Bai

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

enginebai / AndroidBase