In April this year we released version 1.0.0 of Cockpit—an open-source Android tool for developers—but also designers and even customers—to tweak the debug build of the application at runtime. At the beginning it was a very simple tool, providing the user with just the basic functionality and supporting only primitive types of parameters. Now, with version 2.2.0, we’ve come up with a lot of great features, making developing and testing your native Android app more effective than ever.

Read more on the first version of Cockpit in our previous blog post.

What is Cockpit?

Cockpit is an open-source library providing a way to easily tweak your app using a compact debug panel. It’s very simple to use: you only need to define the params in yml file and the library does the rest for you! It generates the Cockpit.java file, providing you with all the methods to work with the params you defined. It also generates an easy to use UI, so you don’t have to worry about details. No more debug panels written from scratch!

We know every app is different, so we didn’t want to impose any particular way of showing Cockpit. You decide it yourself—whether you want to show it on button click, on shake, on multi-touch—it’s up to you! In our sample app, however, we used Seismic library by Square to display Cockpit panel on shake, as we find this solution very simple yet useful and intuitive.

Since Cockpit is a debug panel, it’s obvious that it can be used by Android developers. At Polidea we’ve used it to change animation length, displayed text, timeouts, endpoints, etc. Testers will find it pretty handy as well. But Cockpit is much more than that. You can pass the app integrated with Cockpit to the designers and they’ll be able to test it with different params without needing the developer to rebuild the project for them. You can also pass a debug build to the client to help them decide on some features in your project.

What’s new in 2.2.0?

Versions 1.0.x provided only handling of limited types of params—boolean, integer, double and string and supported only flat structure of params with name and default value. We knew that it’s not enough for advanced applications’ needs and decided to extend the functionality of the library.

Flavor support

The new release brings support for flavors. Params defined in cockpit.yml file are applied to all the flavors. To modify their values or add new ones depending on the flavor, you need to add cockpit<flavorName> file accordingly, for example:

cockpitDebug.yml
cockpitStaging.yml
cockpitStagingDebug.yml
cockpitStagingRelease.yml

Support for both flat and complex param structure

Until now, only flat structure of yaml file was supported. We’ve decided this wasn’t enough. That’s why we introduced more complex param structure to suit more demanding user needs. With complex structure, you can define not only param’s name and default value, but also a description, which, if provided, will be used for display in Cockpit panel instead of param’s name, making the panel’s content more readable to people.

message:
  description: "Message text"
  value: "Test"

Of course if you’re fine with using param names for display, you can still use the flat structure:

message: "Test"

New param types

Version 2.2.0 adds handling of the list, color, slider, step, read-only and action types. Additionally, the params can be put into named groups. Let’s take a look at how to use those features.

LIST

To define a list, you have to add one simple line in your cockpit.yml file:

listSimpleTypeName: [ "staging", "testing", "prod" ]

Based on this line, our library will generate a spinner with three options to choose from. However, if you feel it’s not enough for you, you can specify display name and index of the item selected by default. To be able to do it, you have to use more complex structure to define your list, for example:

listComplexTypeName:
  type: list
  values: [ "staging", "testing", "prod" ]
  selectedItemIndex: 1

selectedItemIndex field is optional. If not provided, 0 is assumed. You can access the selected value from your code using getParamNameSelectedValue(), where paramName is your param’s name.

ACTION

Another useful feature is an ability to define a custom action and invoke it on a button click. To define an action, add the following to your cockpit.yml file:

actionTypeName:
  type: action
  description: "Action description"
  buttonText: "Perform"

buttonText field is optional. If not provided, “Perform” will be used. description is also optional and will be used instead of a param name if provided.

COLOR

Another new param type is color. When you define a parameter as color type, Cockpit will display its preview next to the value. Supported color formats are #RRGGBB and #AARRGGBB. You can define color param with a following piece of yaml:

footerFontColor:
  type: color
  description: "Font color"
  value: "#FFFFFF"

description is optional; will be used instead of a param name if provided.

RANGE SLIDER

Slider can be useful to pick a value from within a predefined range for example age, font size, etc. You can define one for Cockpit as follows:

fontSize:
  type: range
  description: "Font size"
  min: 6
  max: 48
  step: 1
  value: 36

description, as in all other params, is optional. step is optional as well. If not provided, 1 is assumed. At last, value is optional—if not provided, min value is used.

STEP

Another useful feature in Cockpit 2.2.0 is a step param. It can be used with numeric values and provides + and - buttons, so you can change the value step by step in either way. You can define a step param with the following piece of code:

fontSize:
  type: step
  value: 36
  step: 2
  min: 20
  max: 60
  description: "Total price font size"

min, max and description are optional.

READ-ONLY PARAM

A read-only param can be useful when you just want to display some information in the Cockpit panel. A build version is a good example. To define a read-only param, use:

appVersion:
  type: read_only
  description: "Version"

description, as usual, is optional.

GROUP

When your set of params gets more and more complex, it’s only natural you’d want to group them into some meaningful sections. That’s why we’ve introduced groups. Using this feature is really simple—you just need to add group field to the complex param definition. If you don’t provide a group for a param, it will be assigned to Default one.

Listening for changes

To make the most of the debug panel, it’s nice to have a way to observe changes of the params. That’s why Cockpit generates appropriate methods for you: for value changes, you can use addOnParamNameChangeListener() and removeOnParamNameChangeListener(), for list selection changes, you can use addParamNameSelectionChangeListener and removeParamNameSelectionChangeListener, for actions, which don’t change by design, but only get invoked, you can use addParamNameActionRequestCallback() and removeParamNameActionRequestCallback().

Restoring default values

After integrating Cockpit into one of our projects, we found out that it would be handy to be able to restore default values of the parameters after some changes. Because of that we’ve added both a feature of restoring default values globally and per each param. To restore the default value, you just need to press curved arrow icon and the change will get applied immediately.

UI features and design

After adding some new features we came to the conclusion that we really need some neat UI design. One of our designers did a great job and provided us with a very nice one you can see in the current version.

On top of that, we decided it would be nice to be able to actually see your application under the debug panel. To achieve that, we’ve introduced a bottom sheet fragment you can pull down to fit half of the screen’s height. That way you can update your params and observe the screen underneath.

What’s next?

We still have some ideas to develop in our library. At the moment we’re very proud of how Cockpit evolved and grew from version 1.0.0. We’re happy we were able to learn a lot and have fun during its development. We’d like to see the developers use Cockpit in their projects and are super curious about the feedback. Take a look at our repository and stay tuned for more!