What is LatteKit
It's a framework for building Android UI in Kotlin code by using the concept of virtual views and reactive data flow, the goal is to reduce boilerplate while retaining the same Android layout constructs.
Quick Example
package io.lattekit.helloworld import android.app.Activity import android.os.Bundle import android.view.View import android.widget.EditText import io.lattekit.annotation.Bind import io.lattekit.plugin.css.declaration.css import io.lattekit.render import io.lattekit.view.LatteView class MainActivity : Activity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
render("<io.lattekit.helloworld.MyApp />")
}
}
open class MyApp : LatteView() {
@Bind("@id/myText") var myText : EditText? = null;
init {
css("""
.question {
font-size: 20sp; font-weight: bold;
}
.input {
font-size: 14sp; margin-top:8dp; width: match_parent;
}
.answer {
font-size: 20sp; font-weight: bold; margin-top: 10dp; color: #00AADE;
}
""")
// or: css("com.my.package/file.css")
}
override fun layout() = xml("""
<LinearLayout padding="30dp" orientation="vertical">
<TextView text="What's your name?" class="question"/>
<EditText id="@+id/myText" hint="Type your name here"
onTextChanged=${
{
notifyStateChanged()
}
}
class="input"/>
<TextView text=${
"Hello ${
myText?.text
}
"
}
visibility=${
if (myText?.text?.toString() == "") View.GONE else View.VISIBLE
}
class="answer"/>
</LinearLayout>
""")
}
The above layout code is not "string", it's layout representation. The actual XML code will be parsed and compiled by the LatteKit gradle plugin. The use of string interpolation is to make it easier to reference scope variables in the layout. You can use any kotlin expression to set a property value, including lambdas.
Other Samples
For more samples, view the samples at lattekit-samples folder. But before viewing the sample, please read the core concept below to understand the sample better.
How It Works
1- Virtual Views (LatteViews)
The core concept of LatteKit is to define virtual views. A virtual view is subclass of LatteView that defines its own layout. The layout may contain native Android views and other virtual views. It can also receive properties passed to it from the rendering view. For example
open class MyApp : LatteView() {
var currentUser : User? = null;
override fun layout() = xml("""
<LinearLayout padding="30dp" orientation="vertical">
<views.UserDetailsView user=${
currentUser
}
/>
</LinearLayout>
""")
}
open class UserDetailsView : LatteView() {
@Prop var user : User? = null;
// Or @Prop("customPropertyName")
override fun layout() = xml("""
<LinearLayout orientation="horizontal" paddingTop="10dp" paddingBottom="10dp">
<ImageView src=${
user?.avatarUrl
}
layout_width="50dp" layout_height="50dp" />
<TextView text=${
user?.username
}
layout_gravity="center_vertical" layout_height="wrap_content"/>
</LinearLayout>
""")
}
Here, MyApp & UserDetailsView are virtual views. MyApp contains UserDetailsView which expects property user. When the native view tree is built, UserDetailsView will be replaced by the actual layout. Properties are automatically assigned to variables with @Prop annotation. In the above example, MyApp passed currentUser as user propertiy in UserDetailsView.
2- Data Binding & Maintaining View States
As demonstrated in the quick example, you can use any variable you want in your layout code. Just use string interpolation to pass any value to properties. You can use lambdas and reference other views in the layout code. Any variables used in the layout is considered state variable. If some variable's value changes, you will need to notify the view to update its layout by calling notifyStateChanged(). When notified, the virtual view will update its layout and all property changes will flow through the virtual layout tree. In the previous example, if MyApp changes currentUser for any reason (for example due to API call), all it needs to do is call notifyStateChanged() after the change. This will update user property in UserDetailsView which will then update its layout. Calling notifyStateChanged() will always ensure that the layout tree reflects the correct state of the notified view.
Binding Views
If you need to have reference to views from your layout code, you can use @Bind annotation. This is similar to what you do when you call findViewById. By default, the annotation will look for a view with the same id as the variable name. But you can specify the id in the annotation too:
@Bind var saveButton : Button? = null; // Or // @Bind("@id/saveButton") saveButton : Button? = null; override fun layout() = xml(""" <Button id="@+id/saveButton" /> """) You can also refernece those views inside your layout, as demonstrated in the first example.
ListView/RecyclerView/ViewPager
Those views have special treatment inside the layout definition. LatteKit will create an adapter for you, all you have to do is provide the views it should render. You can basically think of it as a for loop that iterates through data set (it's not for loop though, it just implements an Adapter behind the scene). For example:
open class MyListView : LatteView() {
var myData : List<Any> = listOf(...)
override fun layout() = xml("""
<ListView data=${
myData
}
layout_width="match_parent" layout_height="match_parent">
<views.AdItemView when=${
{
it : Any -> it is AdData
}
}
/>
<views.FoodItemView when=${
{
it : Any -> it is FoodData
}
}
defaultView="true" />
</ListView>
""")
}
open class FoodItemView : LatteView() {
@Prop("model") var foodDeatils: FoodData? = null;
override fun layout() = xml("""<TextView text=${
foodDeatils?.title
}
/>""")
}
open class AdItemView : LatteView() {
@Prop("model") var adDetails: AdData? = null;
override fun layout() = xml(""" .... """)
}
Here, the ListView will render myData dataset. The dataset contains two different kinds of objects: AdData and FoodData. Each needs to have different view (FoodItemView or AdItemView). The adapter will determine which template to use by calling the lambda specified via when property. If none of the templates matche, it will fallback to the first template that has defaultView=true. It will then render the template and pass the property model which will contain the corrospending item in the myData.
The template will use model property passed by the adapter.
Lifecycle
If you need to initialize your component, or need to initialize Android views outside the layout. You can override onViewCreated. Also, if you need to need to perform any action before the view is removed from the layout tree, you can override onViewWillDetach().
open class MyListView : LatteView() {
var myData : List<Any> = emptyList();
.. .. override fun onViewCreated() {
ApiManager.getFeed()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe {
response ->
myData = response
notifyStateChanged()
}
}
override fun onViewWillDetach() {
backgroundMusic?.stop();
}
override fun layout() = xml("""
<ListView data=${
myData
}
layout_width="match_parent" layout_height="match_parent" dividerHeight="0">
<views.AdItemView when=${
{
it is AdData
}
}
/>
<views.FoodItemView when=${
{
it is FoodData
}
}
defaultView="true" />
</ListView>
""")
}
CSS Styling
There are two ways to use CSS styling. 1) Local CSS, which are CSS delcarations that are defined inside LatteView. Those declarations don't cascade down to other virtual views. or 2) Global css, which are defined in a separate css file. The css file should be just inside any java package. Here how to use them:
open class MyView : LatteView() {
@Bind("@id/myText") var myText : EditText? = null;
init {
// Global CSS
css("com.my.package/myfile.css")
// Local CSS
css("""
.myclass {
padding: 20dp;
}
""")
}
override fun layout() = xml("""
<LinearLayout class="myclass">
</LinearLayout>
""")
}
CSS styling is not 100% complete, most used properties are already implemented. I'll keep adding more support in later releases. I'll expand this section later to explain what special cases of CSS properties. For the meaning time, you can view more css examples at lattekit-samples
Getting Started
1- Add the gradle plugin class path to buildscript
buildscript {
dependencies {
classpath 'io.lattekit.tools:gradle-plugin:0.9.3'
}
}
2- Apply the plugin
// The plugins must be in that order apply plugin: 'com.android.application' apply plugin: 'lattekit' apply plugin: 'kotlin-android' 3- Add runtime lib to dependency to build.gradle
compile 'io.lattekit:lattekit-core:0.9.3' 4- Define your virtual views as explained above
it's important that LatteView subclasses are declared open class. Gradle plugin will throw an error if it sees layout code inside non-open (final) class.
5- To render LatteView within activity:
import io.lattekit.render
class MyActivity : Activity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Note: props here are passed as map and not in xml
render("<com.package.MyView />",props=mutableMapOf("title" to "MyApp"))
}
}
6- If you just want the native View object, you can call buildView().
var virtualView = Latte.render("<com.package.MyView />",props=mutableMapOf("title" to "MyApp"));
var androidView = virtualView.buildView(myActivity,LayoutParams(..)) // You can later update props using: virtualView.props.put("prop",value);
virtualView.notifyStateChanged();
7- To show LatteView as an activity form another LatteView
Latte.showActivity(this,"<com.package.UserProfile />", mutableMapOf("user" to user))8- To show LatteView as a Dialog form another LatteView
Latte.showDialog(this,"<com.package.UserProfile />", mutableMapOf("user" to user))License
The MIT License (MIT) Copyright (c) 2016 Maan Najjar 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.