top

Adding a Visual Custom Component to SDK

Published 2014-10-28 | (Compatible with SDK 3.5 and 2012 models)

This tutorial demonstrates how to add a visual custom component to an application with the Samsung WYSIWYG Editor. The Samsung WYSIWYG Editor is part of the Samsung Smart TV SDK.

Prerequisites

To create applications that run on a TV screen, you need:

  • Samsung TV connected to the Internet
  • SDK or a text editor for creating HTML, JavaScript and CSS files (using Samsung Smart TV SDK is recommended)

You can find general instructions for creating applications in Implementing Your Application Code.

Development Environment

Use Samsung Smart TV SDK to create the application. You can also use the emulator provided with the SDK to debug and test the application before uploading it in your TV. Later, you can run the application on a TV; see Testing Your Application on a TV. Note that applications may perform better on the TV than on the emulator.

Visual Custom Component

Adding a New Component to the Samsung WYSIWYG Editor

To add a new component to the Samsung WYSIWYG Editor,

  1. In the <Samsung WYSIWYG Editor installation directory>\bin\Tool folder, create a new folder for the visual component. The default installation directory is C:\Program Files\Samsung\Samsung TV SDK(X.X.X). In this example, the component folder is samsung_logo (see the figure below).

    Figure. Folder created for the new component

  2. Inside the newly created folder (samsung_logo), add a new folder called thumb and a new file called cInfo.xml (see the figure below).

    Figure. thumb folder and cInfo.xml file

    • In the thumb folder, add two files (see the figure below):

    • 16x16 .png file (samsung_logo16.png) for the icon

    • 48x48 .png file (samsung_logo_48.png) file for the thumbnail

    • Figure. Image files to be added in the thumb folder

      The icon and thumbnail are created for the component inside the Samsung WYSIWYG Editor (see the figure below).

      Note

      The resolution of the icon file is 16x16, and the resolution of the thumbnail file is 48x48. The component must be in the specified sizes to be properly displayed on the Component panel.

      Figure. Editor showing thumbnail, icon, and bgimage

    • Add a .png image file in the C:\Program Files\Samsung\Samsung TV SDK(x.x.x)\Bin\images\samsung_logo folder (see the figure below). The component appears in the editing window as shown in the figure above. This serves as a background image for the component.

      Figure. Location for the .png file for the component

    • In the cInfo.xml file, add the following code so that the information is parsed and the component appears on the Samsung WYSIWYG Editor. Note that in the code below, the use of each tag has been commented. For details on the xml tags, see the table below.

      <?xml  version="1.0" encoding="utf-8"?>
      <objectdef>
          <object type="samsung_logo">                                <!-- Specifies the type of object that must be added -->
              <title>samsung_logo</title>                             <!-- Title that appears along with the component -->
                                                                      <!-- in the  component list panel -->
              <thumbnail>tool\samsung_logo\thumb\samsung_logo48.png</thumbnail> <!-- The location of the thumbnail -->
              <icon>tool\samsung_logo\thumb\samsung_logo16.png</icon>
              <text readonly="true"></text>
              <defname>samsungLogo</defname>
              <width>200</width>
              <height>100</height>
              <resizeoption>both</resizeoption>                       <!-- both, width, height, none -->
              <bgimage readonly="true">images\samsung_logo\samsung_logo.png</bgimage>
              <function>samsung_logo</function>
              <parameters>
              </parameters>
              <cssattributes>
                  <attr name="left" type="number"/>
                  <attr name="top" type="number"/>
                  <attr name="width" type="number"/>
                  <attr name="height" type="number"/>
              </cssattributes>
              <userlibjs>samsung_logo/samsung_logo.js</userlibjs>     <!-- Copies the js file for the component -->
                                                                      <!-- from commonlib\user_common\ folder -->
                                                                      <!-- to MyApps\samsung_logo folder -->
              <userlibimgdir>user_comp/images</userlibimgdir>         <!-- Copies the image file for the component -->
                                                                      <!-- from  commonlib\user_common\ folder -->
                                                                      <!-- to MyApps\samsung_logo \images folder -->
              <userlibcss>samsung_logo/samsung_logo.css</userlibcss>  <!-- Copies the css file for the component -->
                                                                      <!-- from  commonlib\user_common folder -->
                                                                      <!-- to MyApps\samsung_logo folder -->
              <usercode_includejs><![CDATA[]]></usercode_includejs>
              <usercode_init><![CDATA[]]></usercode_init>
              <usercode_destroy><![CDATA[]]></usercode_destroy>
              <comment>
              </comment>
          </object>
      </objectdef>
      
Tag Description
<object> Used to specify the type of the object to be added: in this case, an image component.
<title> Specifies the title of the component. This appears on the component list panel.
<thumbnail> Specifies the location of the thumbnail.
<icon> Specifies the location for icon.
<defname> Specifies the name that appears on the Component ID.
<bgimage> Specifies the background image for the component. This appears on the Samsung WYSIWYG Editor editing Screen.
<userlibjs>

Specifies the JavaScript file from which the user-defined code for the component is copied and placed into the MyApps directory.

Note

If you have multiple JavaScript files, add this tag to every JavaScript file.

<userlibimgdir> Specifies the location from which the image that will appear on the screen/emulator is copied.
<userlibcss>

Specifies the location from which the css file that will appear on the screen/emulator is copied.

Note

If you have multiple css files, add this tag to every css file.

<usercode_includejs> Specifies the JavaScript code to be included for the component.

Using the Newly Added Component

This section describes the functionality of the newly added component by giving an example of how, after the component is added and exported, it is displayed on the emulator screen.

Once the component has been added and exported from the WYSIWYG Editor, it is displayed on the emulator. Two buttons are included: one that shows and one that hides the component. This tutorial task includes the source code for displaying the component on the emulator. Several other functionalities, such as focus and blur, can also be added to improve the functionality of the component.

  • The CommonLibuser_common folder is the default folder for the user-defined JavaScript file and image file to be used by the component. The user_common folder is created automatically. Inside this folder, create the following folders (see the figure below)
  • A user component folder (in this example, the user component folder is called samsung_logo). Place the JavaScript files and CSS files that you want to add in this folder.
  • An images folder inside the samsung_logo folder. Place the image file for the component in this images folder.

Figure. Location of the files to be added

  • Place a .png file in the images folder. This is the file that is displayed on the screen/emulator when the application is run.

    Note

    Even though the files are created in the user_common folder, they are copied to the Application root folder (<installation directory>\Apps\MyApps\samsung_logo) when the application is run. It is important that these files are present in the application root folder for getting the output on the emulator screen. The copying is done by the <userlibjs> and <userlibimgdir> XML tags that are present in the cInfo.xml file.

  • Define the functionality of the component by adding the code given below to the samsung_logo.js file. In this case, the functionality of the component is to be displayed on the emulator screen.

    (function ($) {
        $.fn.samsung_logo = function () {
    
            var contents = [
                '<div  id="samsung_logo">',
                '</div>'
            ].join('');
    
            $(this).html(contents);
    
            return this;
        };
    })(jQuery);
    

The emulator output is shown below.

Figure. Emulator displaying the user component

Once the above steps have been implemented, the component can be inserted in the WYSIWYG Editor, and when it is exported to the Samsung Smart TV SDK, the component is displayed on the Emulator when the application is run.