983002 - [Stingray][Gaia] IAC protocol for widget

Status: RESOLVED INVALID

(Firefox OS Graveyard :: Gaia, defect)

Description

[John Hu [:johnhu][:johu][:醬糊小弟]]

To have widget working, we need to design the IAC protocol for the communication between system app and homescreen app.

Comment 1

[John Hu [:johnhu][:johu][:醬糊小弟]]

For IAC protocol, I propose to use array of action object. An action object is a widget operation action from homescreen app to system app. The minimum set of actions contains: add, remove, and update. Each of them with different arguments. Example may be found here:

homescreen to system (request message)
[{
  request-id: ‘request-id1’,  // the request id which is generated by homescreen app
  action: ‘add’,
  args: {
    x: 10,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget.gaiamobile.org/'
  }
}, {
  request-id: ‘request-id2’,
  action: ‘add’,
  args: {
    x: 220,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget.gaiamobile.org/'    // the second instance of the same widget.
  }
}, {
  request-id: ‘request-id3’,
  action: ‘add’,
  args: {
    x: 430,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget2.gaiamobile.org/'
  }
}, {
  request-id: ‘request-id4’,
  action: ‘update’,
  args: {
    x: 430,
    y: 400,
    w: 200,
    h: 150,
    widgetId: ‘widget-id3'
  }
}]

The sequence of request message is meaningful. System app should process them one by one sequentially. The followings are definitions of action object:

Action and arguments:
1. add: to create a widget
    args: x, y, width, height, widgetOrigin
2. remove: to remove a widget
    args: widgetId
3. update: to update the position/size of a widget
    args: widgetId, x, y, width, height, visible

For action "add", system app should reply the creation result to homescreen app with widgetId:
system to homescreen (reply message)
[{
  request-id: ‘request-id1’,
  action: ‘add’,
  widgetId: ‘widget-id1’
}, {
  request-id: ‘request-id2’,
  action: ‘add’,
  widgetId: ‘widget-id2’
}, {
  request-id: ‘request-id3’,
  action: ‘add’,
  widgetId: ‘widget-id3’
}]

Homescreen app should use the widgetId replied by system app to do further operations, like update or remove.

The sequence of reply message may NOT be the same as the sequence of request message because of async execution. We need to use request-id to get the mapping between request and reply messages.

Comment 2

[Tzu-Lin Huang [:dwi2][:tzhuang]]

I agree with the design. However, since the sequence of request message is meaningful, do we need to make request-id to be sequential too in order to reflect the fact?

Comment 3

[John Hu [:johnhu][:johu][:醬糊小弟]]

I don't think we need to make the request-id be sequential. Because it is an ID for mapping and I don't think we need to restrict the format of this ID.

BTW, system app can reply the two messages for one request message, like:

reply message 1:
[{
  request-id: ‘request-id1’,
  action: ‘add’,
  widgetId: ‘widget-id1’
}, {
  request-id: ‘request-id3’,
  action: ‘add’,
  widgetId: ‘widget-id3’
}]

reply message 2:
[{
  request-id: ‘request-id2’,
  action: ‘add’,
  widgetId: ‘widget-id2’
}]

Comment 4

[Tzu-Lin Huang [:dwi2][:tzhuang]]

Also, I think system app should reply all action, including 'remove' and 'update'. Homescreen app will definitely need to know all status of widgets.

Comment 5

[John Hu [:johnhu][:johu][:醬糊小弟]]

Sure. I agree with that. And I forgot to add the result property to reply message, the following is an example:

For add action:
[{
  request-id: ‘request-id2’,
  action: ‘add’,
  args: {
    x: 220,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget.gaiamobile.org/'    // the second instance of the same widget.
  }
}]
replies ======>
[{
  request-id: ‘request-id2’,
  action: ‘add’,
  result: true,
  widgetId: ‘widget-id2’
}]
----------------------------------------
For remove action: 
[{
  request-id: ‘request-id’,
  action: ‘remove’,
  args: {
    widgetId: ‘widget-idX'
  }
}]
replies ======>
[{
  request-id: ‘request-id’,
  action: ‘remove’,
  result: true,
  widgetId: ‘widget-idX’
}]
----------------------------------------
For update action: 
[{
  request-id: ‘request-id’,
  action: ‘update’,
  args: {
    visible: true,
    widgetId: ‘widget-idY'
  }
}]
replies ======>
[{
  request-id: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]

Comment 6

[John Hu [:johnhu][:johu][:醬糊小弟]]

More about arguments of each action
1. add's args:
    x (required): the left position, in pixel, at the coordination system of homescreen app,
    y (required): the top position, in pixel, at the coordination system of homescreen app,
    width (required): the width of widget, in pixel,
    height (required): the height of widget in pixel,
    visible (optional): the widget's visibility. Default is true.
    widgetOrigin (required): the origin url of widget app.
2. remove's args:
    widgetId (required): the widget id.
3. update's args:
    widgetId (required): the widget id.
    x (optional): the left position, in pixel, at the coordination system of homescreen app. Default is its original value,
    y (optional): the top position, in pixel, at the coordination system of homescreen app. Default is its original value,
    width (optional): the width of widget, in pixel. Default is its original value,
    height (optional): the height of widget in pixel. Default is its original value,
    visible (optional): the widget's visibility. Default is its original value,

Comment 7

[John Hu [:johnhu][:johu][:醬糊小弟]]

We should not mix two types of variable naming conventions. I suggest we use camel only. So, the replying message from system should be:
[{
  requestId: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]

Comment 8

[Luke Chang [:lchang] (inactive)]

This proposal looks great!

Currently I have only one suggestion: The system app needs the "entry_point" to identify some apps (e.g. dialer or contacts) so I think the protocol in add action should be:

[{
  request-id: ‘request-id2’,
  action: ‘add’,
  args: {
    x: 220,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: 'app://widget.gaiamobile.org/',
    widgetEntryPoint: 'entry'
  }
}]

Comment 9

[KM Lee [:rexboy] (inactivate after Sep. 22)]

We may need 'show' and 'hide' action for switching between applist and widget list. Suggesting the following format for now:

Hide
==
Request:
[{
  request-id: 'id001',
  action: 'hide'
  args: {
    widgetId: ‘widget-idX'
  }
}]

Response:
[{
  request-id: 'id001',
  action: 'hide',
  result: true,
  widgetId: ‘widget-idX'
}]


Show
==
Request:
[{
  request-id: 'id002',
  action: 'show'
  args: {
    widgetId: ‘widget-idY'
  }
}]

Response:
[{
  request-id: 'id002',
  action: 'show',
  result: true,
  widgetId: ‘widget-idY'
}]

Comment 10

[KM Lee [:rexboy] (inactivate after Sep. 22)]

Sorry, forget comment 9 :/ although it could be useful but what we need for now would be 'showall' and 'hideall'.

But this is a little bit contradict with current IAC library for they don't need widget id. Let me write down the detail:


Hideall
==
Request:
[{
  request-id: 'id001',
  action: 'hideall'
}]

Response:
[{
  request-id: 'id001',
  action: 'hideall',
  result: true
}]


Showall
==
Request:
[{
  request-id: 'id002',
  action: 'showall'
}]

Response:
[{
  request-id: 'id002',
  action: 'showall',
  result: true,
}]

Comment 11

[Tzu-Lin Huang [:dwi2][:tzhuang]]

Since 'showall' and 'hideall' are sending from homescreen to system, I think it won't be contradict with current IAC library.

Comment 12

[John Hu [:johnhu][:johu][:醬糊小弟]]

Show/hide actions can be replaced by update action. And we already have the same mechanism at comment 6.

Comment 13

[Tzu-Lin Huang [:dwi2][:tzhuang]]

for show/hide, I think the following could cover the cases
[{
  requestId: ‘request-id’,
  action: ‘update’,
  args: {
    visible: true,
    widgetId: ‘widget-idY'
  }
}]
replies ======>
[{
  requestId: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]

[{
  requestId: ‘request-id’,
  action: ‘update’,
  args: {
    visible: false,
    widgetId: ‘widget-idY'
  }
}]
replies ======>
[{
  requestId: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]

But I think showall and hideall must be different message

Comment 14

[(no longer active)]

I've provided all of the requested information in an email thread with Gene, Evelyn, Gary, Marco et al.  Please let me know if I can help further.

Comment 15

[John Hu [:johnhu][:johu][:醬糊小弟]]

Since the prototype of 2-layered doesn't land to master, we need invalid this bug.

The prototype of 2-layered can be found at: https://github.com/luke-chang/gaia/tree/TV_arch1

We will build a hybrid model which won't use IAC anymore.