ProMotion 2.3 - Notable Changes

ProMotion 2.3 includes several useful new features and better compatibility with RedPotion. It should be fully backwards-compatible with older version of ProMotion, so file an issue if you run into anything.

Here are the notable changes in ProMotion 2.3:


Documentation has been moved from the Wiki to a ./docs folder within the repository itself. All pull requests should include relevant documentation updates, keeping our docs more in sync with the code base.

PM::Table::Searchable improvements

You can now specify a lambda with your search parameter for more fine-grained control.

class TableScreenStabbySearchable < TableScreenSearchable  
  searchable with: -> (cell, search_string) {
    return search_string.split(/\s+/).all? {|term|

  def build_cell(title)
      title: title,
      subtitle: @subtitle.to_s,
      action: :update_subtitle,
      properties: {
        searched_title: "#{title} - stabby"

Or if you want to reference a method instead:

class MyTableScreen < PM::TableScreen  
  searchable placeholder: "Search This Table", with: :custom_search_method

  def custom_search_method(cell, search_string)
    cell[:properties][:some_obscure_attribute].strip.downcase.include? search_string.strip.downcase

To initially hide the search bar behind the nav bar until the user scrolls it into view, use hide_initially: true.

class MyTableScreen < PM::TableScreen  
  searchable hide_initially: true

PM::Delegate on_tab_selected

ProMotion tab bar now triggers an on_tab_selected method call when a tab is selected.

class AppDelegate < ProMotion::Delegate  
  def on_load(app, options)
    open_tab_bar HomeScreen, AboutScreen, ContactScreen

  def on_tab_selected(screen)
    puts screen # instance of some screen

PM::TableScreen will_display_header

You can customize the section header views just before they are displayed on the table. Note this is different from the table header view.

def will_display_header(view)  
  view.tintColor = UIColor.redColor

You can give the table a custom header view (this is different from a section footer view) by defining:

def table_footer_view  
  # Return a UIView subclass here and it will be set at the bottom of the table.

This is useful for information that needs to be at the very bottom of a table.


New module (automatically included in PM::Delegate and PM::Screen variants) that includes the following methods:

  • app: shortcut for UIApplication.sharedApplication
  • app_delegate: shortcut for UIApplication.sharedApplication.delegate
  • app_window: shortcut for UIApplication.sharedApplication.delegate.window
  • try: lets you try methods that may not exist, similar to ActiveSupport's try method. Note that unlike ActiveSupport, we're not monkeypatching every object with this method.

It's sometimes useful to monkeypatch all objects with the methods in PM::Support. Just create a file in your app like this:

class NSObject  
  include ProMotion::Support

Now you can use try and app and whatnot in any object. Since PM::Support is so tiny, it shouldn't have any appreciable impact on performance.

PM::Screen set_nav_bar_buttons

Similar to set_nav_bar_button, this allows you to set more than one at a time by passing in an array.

set_nav_bar_buttons :right, [{  
  custom_view: my_custom_view_button
  title: "Tasks",
  image: UIImage.imageNamed("whatever"),
  action: nil

Other improvements

  • Refactored a bunch of tests to make the test suite run faster and have better coverage
  • Fixed some subtle bugs with searchable
  • Added in cell#on_load to make PM more compatible with RedPotion

Thanks to everyone who contributed to this latest release, which is our most stable and useful ProMotion yet!