Yandex.Widgets Quick start

Transcription

1

2 .. Version 2 Document build date: This volume is a part of Yandex technical documentation. Yandex helpdesk site: Yandex LLC. All rights reserved. Copyright Disclaimer Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support, and usage of the service. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws. You may use or its components only within credentials granted by the Terms of Use of or within an appropriate Agreement. Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws. Contact information Yandex LLC Phone: [email protected] Headquarters: 16 L'va Tolstogo St., Moscow, Russia

3 Contents About the Quick Start Guide... 4 Hello, world!... 4 Distance Units Converter... 7 Index... 17

4 4 About the Quick Start Guide The Quick Start guide includes several examples that can help you get started working with widgets. Document structure This document consists of the following sections: 1. "Hello, world!" widget: an example that guides you through widget basics, from creating a widget to adding it to the widget catalog. You will need to have some basic HTML knowledge to work with the example. Knowing CSS is a plus. 2. Distance Units Converter widget: an example that demonstrates how to create widgets that dynamically process information. This widget will convert distance or length between various units of measurement (millimeters, centimeters, meters, inches and feet). The example also describes how to store the widget body on a designated server. You will need to have some basic HTML, JavaScript and CSS knowledge to work with the example. How to create a widget using a constructor Hello, world! This example demonstrates how to create a widget that prints the "Hello, world!" string on the screen. It describes how to upload the widget and how to add it to the catalog. What is inside a widget? Let's consider the following code: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " xhtml1/dtd/xhtml1-strict.dtd"> <html xmlns=" xmlns:widget=" ns/" > <head>  <meta name="title" content="hello, World!" /> <meta name="description" content="displays Hello, world!"/> </head> <body style="margin:0">  <p>hello, world!</p> </body> </html> This is a ready-made widget. The XHTML file contains: Widget description The description contains widget properties including the name, a short description of the functionality, etc. A widget should contain at least the title property (its name) which is required to upload the widget to Yandex: <meta name="title" content="hello, World!" />

5 5 Note: Additionally, the description can contain settings, which are described in the Distance Units Converter example. Widget body The widget body consists of HTML code, scripts and the table of styles, which implement the widget functions. In our example, the body consists of a single line: <p>hello, world!</p> The lines at the top of the file contain metadata: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " xhtml1/dtd/xhtml1-strict.dtd"> <html xmlns=" xmlns:widget=" ns/" >... </html> Attention! You should specify UTF-8 encoding. Please do not change these lines unless you clearly understand what you are doing. Inside a widget Widget properties Widget preferences How to create your own "Hello, world!" widget Create an empty file with the *.html extension and copy the widget code provided above to this file. Save the file. Now you can display the file in your browser. Note: Your browser opens files with the *.html extension by default. To allow editing of the file content, right-click the file and choose the context menu option Open with -> Select program... Select your text editor from the list of available programs. Right now our widget looks pretty dull. Add the following attribute to the tag <body>: <body style="background-color:#ffcc00; color:blue; margin:0;"> Now the text "Hello, world!" is displayed in blue letters on a bright yellow background. Now let's play with the widget properties. For example, the default widget height is 300 pixels. This is obviously too much for displaying a single text line. To solve this problem you can use the widget property height. Add the following line to the widget properties: <meta name="height" content="60" /> After the widget is uploaded to Yandex it will be displayed with a height of 60 pixels. The file contents should look like this:

6 6 <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " xhtml1/dtd/xhtml1-strict.dtd"> <html xmlns=" xmlns:widget=" ns/" > <head> <meta name="title" content="hello, World!" /> <meta name="description" content="displays the string Hello, world!"/> <meta name="height" content="60" /> </head> <body style="background-color:#ffcc00; color:blue; margin:0;"> <p>hello, world!</p> </body> </html> At this point, your browser should be displaying a yellow page with the text in the upper left corner. Now the widget is ready; you just need to upload it to the Yandex server in order to display the page you have created in a special designated frame (<iframe>). Creating a widget from scratch Widget template How do I upload a widget to Yandex? 1. Log in to the Developer Dashboard located at You should provide your Yandex login and password in order to access the dashboard. 2. Click the Create widget link. 3. Accept the user agreement. 4. Upload the widget data: The XHTML file for the widget. An icon for the catalog. If the upload is successful, you will be redirected to the widget editing page, where you can: Get a direct link for adding the widget. Send a request to add the widget to the shared catalog. Get code to insert into your blog. How to create a widget using a constructor How to add your widget to the widget catalog How can users install my widget? If you already know who your users are, you can just share the link to your widget with them. Users can add your widget on their pages by clicking this link. If the widget has already been added to the widget catalog, any user can find it and install it on their page. Information about the widget catalog How to add your widget to the widget catalog How does it work? When a user installs a widget, the <iframe> element is added to the page and the widget body is loaded into the element. The widget created in this example will look like this:

7 7 Distance Units Converter Developer's guide Distance Units Converter This example demonstrates how to create a widget which dynamically processes information using JavaScript. We will consider two different approaches to storing the widget body. Preparing the widget body The Distance Units Converter should convert between the following units: millimeters centimeters meters inches feet Create an HTML file implementing the widget interface: <html> <head> <style type="text/css"> body { background-color:#ffcc00; text-align:center; #toval{ color:blue; </style> </head> <body style="margin:0"> <table> <input type="text" id="fromval" style="width:80px"/> <select id="fromsystem"> <option value="mm">millimeters</option> <option selected="selected" value="cm">centimeters</option> <option value="m">meters</option> <option value="foot">feet</option> <option value="inch">inches</option> </select> <td colspan="2" align="center">= <input type="text" disabled="true" id="toval" style="width:80px"/></

8 8 td> <select id ="tosystem"> <option value="mm">millimeters</option> <option value="cm">centimeters</option> <option value="m">meters</option> <option selected="selected" value="foot">feet</option> <option value="inch">inches</option> </select> </table> </body> </html> This code creates two drop-down lists containing distance units of measurement, a field for entering the value to be converted, and an area for displaying the result. Simple style sheets are also provided. To convert data from one measurement system to another, let's use the millimeter as a base unit for distance and express all other units in terms of millimeters. We get the following ratio: Unit of measurement millimeter 1 centimeter 10 meter 1000 inch 25,4 foot 304,8 Let's express these relationships using a JavaScript object: var metrics = { "mm" : 1, "cm" : 10, "m" : 1000, "inch" : 25.4, "foot" : ; Then we can add the following conversion function: function convert(){ var val = document.getelementbyid("fromval").value;  if(isnan(val)){ return;  document.getelementbyid("toval").value = val * metrics[document.getelementbyid("fromsystem").value] / metrics[document.getelementbyid("tosystem").value]; The corresponding value in millimeters Now we need to make the function run each time the user changes the input value or chooses a new measurement unit. To do this we need to add the following event handlers: <input type="text" id="fromval" onfocus="watchchanges()" onblur="watchchanges()" />... <select id="fromsystem" onchange="convert()" />... <select id="tosystem" onchange="convert()" /> The fromval input field now has the events onfocus and onblur which call the function watchchanges. This function starts a timer, which monitors changes to the input field. Thus we can handle any changes, including pasting a value from the context menu. Here is the function code:

9 9 var interval = null; function watchchanges(){ interval == null? setinterval("convert()", 500) : clearinterval(interval); Now the page capable of handling the required conversions is ready. Here is the complete code: <html> <head> <style type="text/css"> body { background-color:#ffcc00; text-align:center; #toval{ color:blue; </style> <script type="text/javascript">  </script> </head> <body style="margin:0"> <table> <input type="text" id="fromval" style="width:80px" onfocus="watchchanges()" onblur="watchchanges()"/> <select id="fromsystem" onchange="convert()"> <option value="mm">millimeters</option> <option selected="selected" value="cm">centimeters</option> <option value="m">meters</option> <option value="foot">feet</option> <option value="inch">inches</option> </select> <td colspan="2" align="center">= <input type="text" disabled="true" style="width:80px" id="toval"/></ td> <select id ="tosystem" onchange="convert()">

10 10 <option value="mm">millimeters</option> <option value="cm">centimeters</option> <option value="m">meters</option> <option selected="selected" value="foot">feet</option> <option value="inch">inches</option> </select> </table> </body> </html> Inside a widget Preparing the widget description The file containing the widget description must contain valid XHTML. For this reason, you should use the following format for the file where you create the widget description: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " <html xmlns=" xmlns:widget=" ns/">... </html> Attention! You should specify UTF-8 encoding. The more detailed the properties section is, the easier it will be to find the widget in the shared catalog. Add the following fragment to the <head> block of the document: <meta name="title" content="distance Units Converter" /> <meta name="description" content="the Distance Units Converter can convert between various units used for measuring distance."/> This is where you provide information about the name of the widget and a description of its functionality. Custom settings (called preferences) are like variables where you can store information and use it, for example, to customize the widget's appearance. For example, you can add a preference that restricts operations to only work with certain measurement units. Add the following fragment to the <head> block: <widget:preferences> <preference name="mm" type="boolean" defaultvalue="true" label="millimeters" / > <preference name="cm" type="boolean" defaultvalue="true" label="centimeters" / > <preference name="m" type="boolean" defaultvalue="true" label="meters" /> <preference name="foot" type="boolean" defaultvalue="true" label="feet" /> <preference name="inch" type="boolean" defaultvalue="true" label="inches" /> </widget:preferences>

11 11 Note: To use the preferences, you should declare the namespace xmlns:widget=" wdgt.yandex.ru/ns/". Each preference is defined in a separate <preference> tag; all preferences are wrapped into the <widget:preferences> container tag. Note: The total size of the preferences should not exceed 1 kb. This is because the preferences are sent via the browser's address line (using an HTTP GET request). The following preferences form can be generated based on the code provided above: To display this form, users can click on the gear icon in the upper right corner of the widget when viewing the Yandex home page in Settings mode. Add the logic for handling preferences to the widget body: <script type="text/javascript" src=" widget.onload = function(){ widget.adjustiframeheight(); var metricnames = ["m", "cm", "mm", "foot", "inch"]; var metrics = ""; for(var i = 0; i < metricnames.length; ++i){ if(widget.getvalue(metricnames[i]) == "true"){ metrics += ("," + metricnames[i] + ","); function delothervaluesfromlist(list, values){ for(var i = 0; i < list.options.length;){ values.indexof("," + list.options[i].value + ",") == -1? list.remove(i) : + +i;

12 12 Note: This example uses the widget JavaScript API. To use this example you will need to include the file WidgetApi.js. For more information on the API, see the JS API reference. The widget event onload, which fires when the widget loads, uses the JS API method getvalue to receive the preferences that were added to the <widget:preferences> tag earlier. Note: For more information, see the section User preferences in the Developer's Guide. Then we call the delothervaluesfromlist function for both drop-down lists to remove any values that the user has not selected in the preferences form. Adding commas before and after values assures that they will be unique when you call the indexof function (otherwise, the index for meters "m" in the preferences string containing millimeters "mm" would be positive). For onload we also call the JS API method adjustiframeheight which adjusts the height of the <iframe> element so that the whole widget content is displayed without a vertical scroll bar. Widget properties Widget preferences Where to store widgets Widgets can be autonomous or server-side. The body of an autonomous widget is stored in the same file as its description. The body of server-side widgets is stored on a separate server (defined by the widget author) and the description file contains an additional src property which specifies the location of the body. Distance Units Converter as an autonomous widget To create an autonomous Distance Units Converter widget, put the widget body into the description file: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " <html xmlns=" xmlns:widget=" ns/" > <head> <meta name="title" content="distance Units Converter" /> <meta name="description" content="the Distance Units Converter can convert between various units used for measuring distance."/> <widget:preferences> <preference name="mm" type="boolean" defaultvalue="true" label="millimeters" /> <preference name="cm" type="boolean" defaultvalue="true" label="centimeters," /> <preference name="m" type="boolean" defaultvalue="true" label="meters" /> <preference name="foot" type="boolean" defaultvalue="true" label="feet" /> <preference name="inch" type="boolean" defaultvalue="true" label="inches" / > </widget:preferences> <style type="text/css"> body { background-color:#ffcc00; text-align:center; #toval{

13 13 color:blue; </style> <script type="text/javascript" src=" WidgetApi.js"> </script> <script type="text/javascript">  </script> </head> <body style="margin:0"> <table> <input type="text" id="fromval" style="width:80px" onfocus="watchchanges()" onblur="watchchanges()"/> <select id="fromsystem" onchange="convert()"> <option value="mm">millimeters</option> <option selected="selected" value="cm">centimeters</option> <option value="m">meters</option> <option value="foot">feet</option> <option value="inch">inches</option> </select>

14 14 <td colspan="2" align="center">= <input type="text" style="width:80px" disabled="true" id="toval"/></ td> <select id ="tosystem" onchange="convert()"> <option value="mm">millimeters</option> <option value="cm">centimeters</option> <option value="m">meters</option> <option selected="selected" value="foot">feet</option> <option value="inch">inches</option> </select> </table> </body> </html> Distance Units Converter as a server-side widget The body of a server-side widget should be hosted somewhere as a normal Internet page (in this example, the widget body is stored at Add the src property to the widget description: <meta name="src" content=" /> So the widget file will look like this: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" " xhtml1/dtd/xhtml1-strict.dtd"> <html xmlns=" xmlns:widget=" ns/" > <head>  <meta name="title" content="distance Units Converter" /> <meta name="description" content="the Distance Units Converter can convert between various units used for measuring distance."/> <meta name="src" content=" />  <widget:preferences> <preference name="mm" type="boolean" defaultvalue="true" label="millimeters" /> <preference name="cm" type="boolean" defaultvalue="true" label="centimeters" /> <preference name="m" type="boolean" defaultvalue="true" label="meters" /> <preference name="foot" type="boolean" defaultvalue="true" label="feet" /> <preference name="inch" type="boolean" defaultvalue="true" label="inches" / > </widget:preferences> </head> <body style="margin:0"> </body> </html> The file will look like this:

15 15 <html> <head>  <style type="text/css"> body { background-color:#ffcc00; text-align:center; #toval{ color:blue; </style> <script type="text/javascript" src=" WidgetApi.js"> </script> <script type="text/javascript">  </script> </head> <body style="margin:0"> <table> <input type="text" id="fromval" style="width:80px" onfocus="watchchanges()" onblur="watchchanges()"/> <select id="fromsystem" onchange="convert()">

16 16 <option value="mm">millimeters</option> <option selected="selected" value="cm">centimeters</option> <option value="m">meters</option> <option value="foot">feet</option> <option value="inch">inches</option> </select> <td colspan="2" align="center">= <input type="text" style="width:80px" disabled="true" id="toval"/></ td> <select id ="tosystem" onchange="convert()"> <option value="mm">millimeters</option> <option value="cm">centimeters</option> <option value="m">meters</option> <option selected="selected" value="foot">feet</option> <option value="inch">inches</option> </select> </table> </body> </html> Autonomous and server-side widgets What is the result? The widget we have created looks like this: How to create a widget using a constructor How to add your widget to the widget catalog Developer's guide

17 Index example 7 Hello, World! 4 widget 4 example 4

18