`class_="receiver"`

Using <widget class_="receiver"> updates dynamic variables when it receives JavaScript messages sent from external web applications.

Description

When a QuickApp is embedded within a web application via an <iframe>, the transmitter and receiver widgets facilitate communication between the application and the QuickApp.

The receiver widget receives messages from web applications external to 1010data and updates the dynamic variables specified in those messages with their corresponding values.

For a complete example of using the transmitter and receiver widgets to communicate with an external web application, see the Embedded QuickApps tutorial.

Syntax

<dynamic>
  <widget class_="receiver"/>
</dynamic>

Attributes

value_

When value_ is specified, the entire value of the JavaScript message is stored in the dynamic variable associated with this attribute.

The variable must be declared in the opening <dynamic> tag of the QuickApp (e.g., <dynamic var_name="">).

In the absence of a value_ attribute, the widget accepts a JavaScript postMessage of the form:

{set:{var1:value1, var2:value2,
                ...}, submit: [name1,name2, ...]}

Note: Either or both of set and submit sub-messages may be present, and any number of variable-value pairs and/or submit names may be specified.

enforce_origin_

Accepts a string that represents a URI (specifying protocol, hostname, and port, if non-standard) to prevent interpreting messages from hostile code.

Example for `class_="receiver"`

This example demonstrates how a QuickApp can receive a JavaScript message from the containing web application. Based on the contents of the message, the receiver widget will update either or both of the dynamic variables year or zipcode with the specified values.

<defblock name="sel_year">
  <table>2014;2015
  </table>
</defblock>
<defblock name="to_plot" zipcode="10017" year="">
  <sel value="year(date)={@year}"/>
  <sel value="zipcode={@zipcode}"/>
  <sel value="day(date)=15"/>
  <colord cols="zipcode,date,meantempi"/>
  <sort col="date" dir="up"/>
</defblock>
<dynamic year="2015" zipcode="10017">
  <widget class_="receiver"/>
  <widget class_="transmitter" message_="{@year},{@zipcode}" 
   onrender_="1"/>
  <layout>
    <widget class_="dropdown" label_="Select a year" 
     value_="@year" insert_="sel_year"/>
    <widget class_="graphics" width_="700" 
     base_="pub.demo.weather.wunderground.observed_daily">
      <insert block="to_plot" year="{@year}" 
       zipcode="{@zipcode}"/>
        <graphspec width="600" height="400">
          <chart type="line" samples="100000">
            <style seriescolors="#F26F21" linemarkershow="0"/>
            <data x="date" y="meantempi" yrot="65"/>
          </chart>
        </graphspec>
    </widget>
    <widget class_="grid" type_="scroll" 
     base_="pub.demo.weather.wunderground.observed_daily">
      <insert block="to_plot" year="{@year}" zipcode="{@zipcode}"/>
    </widget>
  </layout>
</dynamic>

The QuickApp is embedded in an external web application via an <iframe>. When the web application sends a message to the QuickApp via the postMessage method in JavaScript, it is received by the receiver widget.

An example of the JavaScript postMessage call is:

win.postMessage({set: {"zipcode": e.target.value}}, iframe.src);

where win is the window object associated with the <iframe>, and iframe.src is the QuickApp's DOM.

Note: When referring to the QuickApp's dynamic variables in JavaScript, no @ symbol is needed.

In this example, when the QuickApp receives the postMessage, the zipcode dynamic variable is updated with the value of e.target.value.

Additional information

The following information should be considered when using <widget class_="receiver">

The receiver widget can discern JavaScript types; floats, ints, and text can be received and mapped to their appropriate 1010data types. Additionally, JavaScript arrays can be received and are interpreted as lists in 1010data, and JavaScript objects can be received and are interpreted as packages in 1010data.
There can only exist one receiver and one transmitter widget per outermost DOM.

class_="receiver"