kimeeo/proteus

Proteus : A JSON based LayoutInflater for Android

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.kimeeo:proteus:5.0.0-rc11'
	}
	dependencies {
		implementation("com.github.kimeeo:proteus:5.0.0-rc11")
	}
	<dependency>
	    <groupId>com.github.kimeeo</groupId>
	    <artifactId>proteus</artifactId>
	    <version>5.0.0-rc11</version>
	</dependency>

                            
    libraryDependencies += "com.github.kimeeo" % "proteus" % "5.0.0-rc11"
        
        

                            
    :dependencies [[com.github.kimeeo/proteus "5.0.0-rc11"]]

Readme

<h1> <img src="/assets/proteus-logo.png" width="150px"/> : Android Layout Engine </h1> <a target="_blank" href="https://travis-ci.org/flipkart-incubator/proteus"> <img src="https://travis-ci.org/flipkart-incubator/proteus.svg?branch=master" alt="Build Status"> </a> <a target="_blank" href="https://jitpack.io/#flipkart-incubator/proteus"> <img src="https://jitpack.io/v/flipkart-incubator/proteus.svg" alt="Build Status"> </a> <a href="https://android-arsenal.com/details/1/5105"> <img src="https://img.shields.io/badge/Android%20Arsenal-Proteus-brightgreen.svg?style=flat" border="0" alt="Android Arsenal"> </a>

Proteus is meant to be a drop-in replacement for Android’s LayoutInflater; but unlike the compiled XML layouts bundled in the APK, Proteus inflates layouts at runtime. With Proteus, you can control your Apps layout from the backend (no WebViews). Forget the boilerplate code to findViewById, cast it to a TextView, and then setText(). Proteus has runtime data bindings and formatters. Plugin in your own custom views and attributes and functions.

Getting Started

gradle

// Add it in your root build.gradle at the end of repositories:
allprojects {
	repositories {
		...
		maven { url "https://jitpack.io" }
	}
}

// Add the dependency
dependencies {
        compile 'com.github.flipkart-incubator:proteus-core:5.0.0-rc8@aar'
        compile 'com.github.flipkart-incubator:gson-adapter:5.0.0-rc8@aar'
}

include as a module

  • Clone the proteus in the project folder
git clone https://github.com/flipkart-incubator/proteus.git
  • Include the a project in you apps build.gradle file
dependencies {
  compile project('proteus:proteus-core')
  compile project('proteus:gson-adapter')
}

How it works

Instead of writing layouts in XML, in proteus layouts are described in JSON, which can be used to inflate native Android UI at runtime. The JSON layouts can be hosted anywhere (on the device, on servers, etc.).

The Layout defines the the view heirarchy, just like XML.

The Data (optional) defines data bindings. These data bindings are similar to Android's Data Binding library.

Give the layout and data to ProteusLayoutInflater and get back a native view hierarchy.

Watch this video to see it in action.

Sample layout

{
  "type": "LinearLayout",
  "orientation": "vertical",
  "padding": "16dp",
  "children": [{
    "layout_width": "200dp",
    "gravity": "center",
    "type": "TextView",
    "text": "@{user.profile.name}"
  }, {
    "type": "HorizontalProgressBar",
    "layout_width": "200dp",
    "layout_marginTop": "8dp",
    "max": 6000,
    "progress": "@{user.profile.experience}"
  }]
}

Sample data

{
  "user": {
    "profile": {
      "name": "John Doe",
      "experience": 4192
    }
  }
}

Sample Java code

ProteusView view = proteusLayoutInflater.inflate(<layout>, <data>);
container.addView(view.getAsView());

Output

<img src="/assets/example-small.png" width="360px"/>

Setting up the Demo App

The demo app will let you play around with proteus as well as help you understand the internals better.

  • Install NodeJS here
  • open a terminal
  • cd into the project directory
  • run npm start
  • Start an AVD emulator
  • Install the Demo App

Ready to tinker

  • Tinker around with the layout and data
  • Hit the FAB to refresh the app.

Resources

Contributing

How?

The easiest way to contribute is by forking the repo, making your changes and creating a pull request.

What?

  • Adding new Views and Attribute Proccessors.
  • Adding new Functions.
  • Adding JavaDoc and Wiki.
  • Completing TODOs
  • Writing unit tests.
  • Finding bugs and issues. (submit here)
  • Fixing bugs and issues.
  • Implement performance/benchmarking tools.

License

Apache v2.0

If you are using proteus check out the can, cannot and must

Contributors

You can check out the contributors here, but if you wish to contact us; just drop in a mail.

Plugins

One click XML to JSON conversion plugin

Download this plugin (in beta) for Android Studio. Once enabled, you can select any android XML resource file and go to Tools > Proteus > Convert XML to JSON