Mote.io Chrome Extension

Thanks for your interest in building a remote for Mote.io!

Here's how you can get your remote into the production version of the Mote.io extesion:

• Fork this repository
• Create a remote
• Submit a pull request

I'll review your code, merge your remote in, and then deploy it to the world!

Development Cycle

Mote.io remotes work by clicking and inspecting objects in the DOM. When a button is pressed on the phone, it fires a function which should probably click something on the page.

It's annoying to define a remote, reload the extension, launch the app, sync, and press the button on the phone just to test if a function works.

Instead, this is how I develop remotes:

1. Test all of my button functions in the Chrome console before even begining to write the config file. This is identical to the environment the functions will be called in when triggered from the phone. If it works in console, it will work in mote.io.remote. These functions can be as simple as $('#playerPlay').click();
2. Create a really simple remote with just buttons and test it on the phone
3. Test functions to find now playing objects / states in the Chrome console (like #1). These may be like: $('#now-playing').text().trim();
4. I go back and add update(), notify(), and updateButton() methods and test it on the phone

You can also fire the button functions manually from the console once they have been added to mote.io.remote like so:

mote.io.remote.blocks[0].data[0].press();

Setting up the extension in developer mode

1. Fork this repository
2. Disable production extension
3. Load it as an unpacked extension in Chrome
4. Visit the start page to make sure the unpacked extension works

Adding your own remote

1. First, create a file in the /remotes directory with a descriptive name.
2. Then, add an entry to manifest.json for the site you want to support.

The entry should look something like this:

    {
      "matches": [
        "http://www.pandora.com/*"
      ],
      "js": [
        "moteio.js",
        "remotes/pandora.js"
      ],
      "run_at": "document_start"
    }

Reloading and refreshing extension code

Chrome extensions are a hassle to refresh. You need to visit chrome://extensions and refresh the page to update your extension. You can read more about refreshing extensions here.

You also may try this extension that adds a shortcut to reload extensions.

Tips and Tricks

Check out extra section at the bottom of this doc for some solutions to common questions.

Remote API

You can find many examplees of remotes in the /remotes directory. A remote file looks like so:

exec(function(){

  mote.io.remote = {
    api_version: '0.1',
    app_name: 'Vimeo',
    action: 'watching',
    twitter: 'vimeo',
    display_input: true,
    init: function() {...}
    update: function(force) {...},
    blocks: [...]
  };

});

Every remote file must be wrapped in the exec(function(){...}); call.

This function allows the javascript code to run at the document level. This means any variable you define within this function is going to be in the global scope!

Config Variables

Property	Type	Required	Notes
api_version	string	Yes	Should be '0.1'
app_name	string	Yes	Appears at the top of the app, as well as in status updates. Keep it short.
action	string	if notify.share is true	The verb that will appear in status updates. Example values are "watching" and "listening to".
twitter	string	if notify.share is true	The @handle mentioned in Twitter share status updates.
display_input	boolean		Default is false. Enabling this will show an icon overlay over the web page when a button is tapped.
init	function		A function called after a phone has connected.
update	function		A function called by the plugin javascript to update the remote.
blocks	array	Yes	An array of objects containing the remote layout .

Block Types

Notify

Notify is the area in which app notifications are shown.

Property	Type	Required	Notes
type	string	Yes	Must be 'notify'
share	boolean		Determines if Twitter and Facebook icons are shown. mote.io.remote.action and mote.io.remote.twitter must be defined if this is true.

blocks: [
    {
      type: 'notify'
      share: true
    },
    ...
]

Search

Search displays a text box with a search icon

Property	Type	Required	Notes
type	string	Yes	Must be 'search'
action	function	Yes	A function to be called when the user submits a search query. The query is sent as the first param of the function.

blocks: [
  {
    type: 'search',
    action: function(query) {
      alert(query);
    }
  }
  ...
]

Buttons

The buttons type represents a row of buttons.

Property	Type	Required	Notes
type	string	Yes	Must be 'buttons'
data	array	Yes	An array of button objects. Buttons are aligned from left to right but always centered on screen.

blocks: [
  {
    type: 'buttons',
    data: [
      {...},
      {...},
      {...}
    ]
  },
  ...
]

The yellow lines here represent individual blocks of buttons.

Buttons.data

Data is an array of button objects. Button objects have the following properties:

Property	Type	Required	Notes
press	function	Yes	A function to call when the button is pressed
icon	string	Yes	This is an icon from font-awesome. Do not provide the text "icon-" as it will be added automatically.
hash	hash		This is a button identifier used in button updates (read more below)

Here is the middle row of the image above represented in javascript:

blocks: [
  {
    type: 'buttons',
    data: [
      {
        press: function () {
          alert('left pressed');
        },
        icon: 'chevron-left'
        hash: 'up'
      },
      {
        press: function () {
          alert('middle pressed');
        },
        icon: 'circle-blank'
        hash: 'go'
      },
      {
        press: function () {
          alert('right pressed');
        },
        icon: 'chevron-right'
        hash: 'right'
      },
    ]
  },
  ...
]

Select

Select represents a select box in the app.

Property	Type	Required	Notes
type	string	Yes	Must be 'select'
data	array	Yes	An array of select option objects.

{
  type: 'select',
  data: [
    {...},
    {...}
  ]
}

Select.data

Select.data is an array of select option objects. Select option objects have the following properties:

Property	Type	Required	Notes
text	string	Yes	The option text
action	array	Yes	A function to fire when the select button is pressed
optgroup	string		Groups select option objects under a parent with this value

{
  type: 'select',
  data: [
    {
      optgroup: 'Latest',
      text: 'Latest',
      action: function() {
        window.location = "/latest";
      }
    },
    {
      optgroup: 'Latest',
      text: 'Freshest',
      action: function() {
        window.location = "/latest/fresh";
      }
    },
    ...
}

Methods

Notify

Notify sends information to the notify block about what to display.

Parameters	Type	Required	Notes
line1	string	Yes	The first line of text
line2	string		The second line of text
image	string	Yes	The url of an image to display next to text. Resized to 50px x 50px
url	string	Yes	A permalink to the current playing item. Not the current window.location, but a link to the single item that is playing right now.
force	boolean	Yes	Pass the value of force from mote.io.remote.update(force). Must be false if used outside of the update() context.

mote.io.remote =  {
  update: function(force) {
  
    var thisArtist = $($('#player-nowplaying a')[3]).text(),
      thisSong = $($('#player-nowplaying a')[4]).text(),
      thisImage = extractUrl($('.haarp-active.section-track').find('.readpost > span').css('background-image')),
      thisPerma = window.location.origin + $('.haarp-active.section-track').find('a.track').attr('href');
   
    mote.io.notify(thisArtist, thisSong, thisImage, thisPerma, force);
  
  }
}

Update Button

The update button method allows you to change the color and icon of a button on a remote.

Parameters	Type	Required	Notes
button_hash	string	Yes	The hash identifier of the button. Make sure you assign this variable in the button object.
icon	string	Yes	The new icon to display.
color	string	Yes	The button icon color. A 6 character hex code like #000000 or #ffffff
force	boolean	Yes	Pass the value of force from mote.io.remote.update(force). Must be false if used outside of the update() context.

mote.io.remote =  {
  update: function(force) {
	
	if($('#playerFav').hasClass('fav-on')) {
	mote.io.updateButton('heart', null, '#ff0000', force);
	} else {
	mote.io.updateButton('heart', null, '#434345', force);
	}

  }
}

Additional Notes and Workarounds

jQuery

The mote.io plugin provides you with jQuery for free by using the jQ variable. Not all of the examples may use jQ. They may access the standard $ which is actually provided by the website the code is injected onto, not the mote.io extension.

Deferred Loading

A remote is only sent to the client once, when it is found on the webpage. Something like the following will work just fine.

setTimeout(function(){
  mote.io.remote = {};
}, 5000);

Updating the remote on the phone

Once the remote is sent, you can only update the button colors, icons, and notification text.

However, sometimes you just need to send the whole remote over. This is usually because the website you're building a remote for is a single page app.

Use the following method to resend mote.io.remote to the phone. This function has no parameters, it simply looks for mote.io.remote and sends it over.

mote.io.receiver.sendRemote();