[Libreoffice-commits] online.git: Branch 'distro/collabora/collabora-online-2-1' - loleaflet/reference.html

[Pranav Kant]

 loleaflet/reference.html |   83 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 72 insertions(+), 11 deletions(-)

New commits:
commit c8160260c0f22e9baddd2c38b93f3ebb20480eeb
Author: Pranav Kant <pranavk at collabora.co.uk>
Date:   Tue Jun 20 18:51:05 2017 +0530

    Document custom button API
    
    Change-Id: I67b29052ed9f140d82b8f93289fc9704892517c5
    (cherry picked from commit b36e79f173e128a985270aa58ad25533208f2fc5)
    Reviewed-on: https://gerrit.libreoffice.org/43088
    Reviewed-by: Jan Holesovsky <kendy at collabora.com>
    Tested-by: Jan Holesovsky <kendy at collabora.com>

diff --git a/loleaflet/reference.html b/loleaflet/reference.html
index fa08a3d6..ddb9a47a 100644
--- a/loleaflet/reference.html
+++ b/loleaflet/reference.html
@@ -73,6 +73,7 @@
 			<li><a href="#loleaflet-postmessage-query">Query API</a></li>
 			<li><a href="#loleaflet-postmessage-sessions">Session Management</a></li>
 			<li><a href="#loleaflet-postmessage-actions">Actions</a></li>
+			<li><a href="#loleaflet-postmessage-misc">Miscellaneous</a></li>
 		</ul>
 		<h4>UI Layers</h4>
 		<ul>
@@ -2721,13 +2722,7 @@ The <code>id</code> property of ErrorEvent can have the following values:
 <p>This API is mostly based
   on <a href="https://wopi.readthedocs.io/en/latest/scenarios/postmessage.html">WOPI
     specification</a> with few extensions/modifications. All messages sent are
-  in this form</p>
-
-<p>It is to be noted that as mentioned in WOPI specs, loleaflet frame will
-  ignore all post messages coming from the host frame
-  if <code>Host_PostMessageReady</code> has not been received. Further, no post
-  messages will be emitted if 'PostMessageOrigin' property is missing from
-  server response.</p>
+  in this form :
 
 <pre><code class="javascript">
 {
@@ -2738,11 +2733,18 @@ The <code>id</code> property of ErrorEvent can have the following values:
     }
 }
 </code></pre>
+SendTime is the timestamp returned by browsers' Date.now(). The post messages
+sent from the WOPI host should also be in same form.
+</p>
 
-SendTime is the timestamp returned by browsers' Date.now()
-
-<br/><br/>
-Similarly, message received should be in same form.
+<p>It is to be noted that as mentioned in WOPI specs, loleaflet frame will
+  ignore all post messages coming from the host frame
+  if <code>Host_PostmessageReady</code> has not been received. Further, since
+  for embedding LibreOffice Online as an iframe WOPI implementation is a must,
+  it is required that 'PostMessageOrigin' property is present in
+  WOPI host's CheckFileInfo response. Otherwise, no post messages will be
+  emitted.
+<br/>
 
 <h3 id="loleaflet-postmessage-initialization">Initialization</h3>
 Editor to WOPI host
@@ -2976,6 +2978,65 @@ Actions response
 	</tr>
 </table>
 
+<h3 id='loleaflet-postmessage-misc'>Miscellaneous</h3>
+WOPI host to editor
+<table data-id='postmessage-misc-to-editor'>
+	<tr>
+		<th>MessageId</th>
+		<th>Values</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td><code><b>Insert_Button</b></code></td>
+		<td><code>
+		    <nobr>id: <string></nobr><br/>
+		    <nobr>imgurl: <string></nobr>
+		    <nobr>hint: <string></nobr>
+		    <nobr>mobile: <boolean></nobr>
+		    <nobr>label: <string></nobr>
+		</code></td>
+		<td>
+		  Inserts the button to the left of the top toolbar. Only thing
+		  that it does is response to click events based on which hosts
+		  can act accordingly. It responds
+		  with <code>Clicked_Button</code> post message event.<br/>
+		  <code>id</code> parameter is a unique id of the toolbar
+		  button. It is recommended to prefix such ids given here with
+		  some host namespace so that it doesn't conflict with existing
+		  toolbar IDs. In case of conflict, button is not added.<br/>
+		  <code>imgurl</code> parameter is the link to the image that
+		  will be set as button image in the toolbar. The ideal size of
+		  the image is 24x24px. The image must be hosted on the host URL
+		  to not violate Content-Security-Policy.<br/>
+		  <code>hint</code> This is used as a tooltip of the
+		  button.<br/>
+		  <code>mobile</code> Whether the button should be shown when
+		  the interface switches to mobile mode.<br/>
+		  <code>label</code> When a readonly document is opened, we
+		  don't have the toolbar at all. In this case, this newly added
+		  button is present in file menubar. The text against this label
+		  is used as text of the menubar item.
+		</td>
+	</tr>
+</table>
+Editor to WOPI host
+<table data-id='postmessage-misc-to-host'>
+	<tr>
+		<th>MessageId</th>
+		<th>Values</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td><code><b>Clicked_Button</b></code></td>
+		<td><code>
+		    <nobr>id: <string></nobr>
+		</code></td>
+		<td>
+		  This event is emitted when the custom button added
+		  via <code>Insert_Button</code> API above is clicked.
+		</td>
+	</tr>
+</table>
 
 <h2 id="marker">Marker</h2>