Yamli API
Yamli

Yamli API Documentation

Last updated: July 1, 2010

Table of Contents

1. Introduction

1.1 About the Yamli API

Yamli’s technology allows users to type Arabic using Latin characters. By licensing Yamli, you can use Yamli to allow your users to easily type Arabic in all the HTML forms on your website, including email, forums, search boxes, comment forms, etc… Our technology can be integrated seamlessly without disrupting the existing layout and functionality, and with a minimum of effort.

When you integrate Yamli on a textbox, the Yamli settings link appears next to, or inside, the textbox.

Here is an example of a "Yamlified" text box:

In this example, clicking on the Yamli logo allows the user to access Yamli specific settings. This is just one way to place the Yamli settings link relative to the textbox. For more information on placing the Yamli settings link, see this section.

1.2 Requirements

Browser Support

Yamli fully supports the following web browsers:

  • Internet Explorer 6, 7 and 8

  • Firefox 2 and above

  • Apple Safari 3.1 and above

  • Google Chrome 1.0 and above

  • Opera 9.5 and above

HTML Elements

Yamli is compatible with the following HTML controls, for which adding Yamli functionality is very simple:

  • INPUT type TEXT - these are single line text boxes

  • TEXTAREA - these are multiline text boxes

  • Rich Text Editor (RTE)new! - these can be either IFRAME or contentEditable DIVs.
    You can now use Yamli with TinyMCE, CKEditor, YUI Editor, and many others!

2. Getting Started

2.1 How to Integrate Yamli in 5 Minutes

To enable Yamli on your website, you just need to include a little script at the end of the page. In this script, you will need to specify which textboxes will be "yamlified". To do all this, add the following code at the end of your HTML file.

    ... your HTML content goes here ...

    <script type="text/javascript" src="http://api.yamli.com/js/yamli_api.js"></script>
    <script type="text/javascript">
      if (typeof(Yamli) == 'object' && Yamli.init())
      {
        Yamli.yamlify('textbox_id');
      }
    </script>

  </body>
</html>

This script should be added right before the closing </BODY> tag. You may have other scripts at that location, such as Google Analytics for example. It doesn't matter if Yamli's script is before or after these. By placing the Yamli script at the bottom of your HTML code, Yamli can load in the background while the user starts interacting with your page.

You should replace textbox_id with the id of the <INPUT type="text"> or <TEXTAREA> elements you wish to yamlify. If your HTML textbox doesn't have an id already, you can easily add one like this:

<textarea id="textbox_id" ... other attributes ...></textarea>

2.2 Specifying which textboxes to "Yamlify"

The example above showed you how to use the Yamli API with a single textbox on a page. How do you "yamlify" more than one textbox on a page? You can use three approaches:

  • Specify each textbox with a Yamli.yamlify() statement

  • Yamlify all the textboxes that have a given class using a Yamli.yamlifyClass() statement

  • New!Yamlify all the textboxes in your page, or only those of a certain type using a Yamli.yamlifyType() statement

Note that if you "yamlify" a textbox multiple times. Additional calls affecting a given textbox are just ignored.

Function: Yamli.yamlify ( elementId, options )
This function adds Yamli's functionality to a given textbox. The textbox is specified using the "elementId" parameter.
Parameter name: elementId
Type: string
Required: yes
This parameter corresponds to the "id" attribute of the textbox. The textbox can either be a TEXTAREA, an INPUT (TYPE="TEXT") element, an Rich Text Editor IFRAME, or a CONTENTEDITABLE DIV.
Parameter name: options
Type: object
Required: no
This parameter lets you specify the options specific to the textbox. It is a Javascript object of key/value pairs, as described in section 3.1. Note that Yamli.yamlify() makes an internal copy of the options parameter. This means you can re-use the same options object in consecutive calls.
Function: Yamli.yamlifyClass ( clsName, options )
This function adds Yamli's functionality to all the textboxes with the supplied class. The class is specified using the "clsName" parameter. This is useful if you have groups of textboxes that use common options (see section 3.1).
Parameter name: clsName
Type: string
Required: yes
If a textbox uses a class that matches "clsName", it will be yamlified. The textbox can either be a TEXTAREA or an INPUT (TYPE="TEXT") element. Note that textboxes can specify multiple classes. For example, if a textbox class is "comment yamliTextbox", it would be yamlified if Yamli.yamlifyClass('yamliTextbox') were called.
Parameter name: options
Type: object
Required: no
This parameter lets you specify the options specific to the textboxes using a class matching clsName. It is a Javascript object of key/value pairs, as described in section 3.1. Note that Yamli.yamlifyClass() makes an internal copy of the options parameter. This means you can re-use the same options object in consecutive calls.
Function: Yamli.yamlifyType ( typeName, options )
This function adds Yamli's functionality to all the textboxes matching the supplied type (for example you can yamlify all TEXTAREAs). The type is specified using the "typeName" parameter. This is useful if you yamlify all the textboxes in a page. It is sometimes the easiest way to target Rich Text Editors (RTEs) for which an element id or class may not be obvious.
Parameter name: typeName
Type: string
Required: yes
Values:
  • 'textbox': Yamlify all INPUT (TYPE="TEXT") elements in the page.

  • 'textarea': Yamlify all TEXTAREA elements in the page.

  • 'rte': Yamlify all RTE elements in the page. This function affects both IFRAME and CONTENTEDITABLE rich text editors.

  • 'any': Yamlify all elements in the page.

Parameter name: options
Type: object
Required: no
This parameter lets you specify the options specific to the textboxes matching the type typeName. It is a Javascript object of key/value pairs, as described in section 3.1. Note that Yamli.yamlifyType() makes an internal copy of the options parameter. This means you can re-use the same options object in consecutive calls.

3. Customize Yamli

While it's easy to get Yamli running on your website, it's important for you to be able to customize it so that it fits in.

3.1 Global and Local Options

Because you may have more than one textbox in a given webpage, the Yamli API lets you set options at two levels:

  • Globally, for all the "yamlified" textboxes in the page

  • Locally level, for a single textbox, or for all the textboxes of a given class

The options consist of a Javascript object of key/value pairs. The values can be booleans, numbers or strings, depending on the option.

Important: Option key names are case-sensitive.

Global options are set in the Yamli.init() function call. This is how you use them:

<script type="text/javascript">
  if (typeof(Yamli) == 'object' && Yamli.init( { option1: value1,
                                                 option2: value2,
                                                 ... more options ...,
                                                 optionN: valueN })
  {
    ...
  }
</script>

Local options are set in the Yamli.yamlify() or Yamli.yamlifyClass() function calls. For example:

<script type="text/javascript">
  if (typeof(Yamli) == 'object' && Yamli.init())
  {
    Yamli.yamlifyClass('class_name',
                       { option1: value1,
                         option2: value2,
                         ... more options ...,
                         optionN: valueN });
                         
    Yamli.yamlify('textbox_id',
                  { option1: value1,
                    option2: value2,
                    ... more options ...,
                    optionN: valueN });
  }
</script>

Many of the Yamli API options can be used both at the global or local level. If the same option is set both globally and locally, the local option takes precedence.

3.2 User Interface Language

One of the most important options is the language of the Yamli user interface. It is defined in the following option:

Option Name: uiLanguage
Type: string
Scope: global, local
Values:
  • 'en' (default): English

  • 'ar': Arabic

  • 'fr': French

Here are examples of the user interface languages:

uiLanguage: 'en'
uiLanguage: 'ar'
uiLanguage: 'fr'

We may support more languages in the future. Let us know if you have particular needs.

3.3 Yamli Settings Placement

The Yamli settings link allows user to change the various Yamli options. Choosing the placement of the settings link is done using this option:

Option Name: settingsPlacement
Type: string
Scope: global, local
Values:
  • 'bottomRight' (default): Underneath the textbox, aligned with the right edge.

  • 'bottomLeft': Underneath the textbox, aligned with the left edge.

  • 'topRight': Above the textbox, aligned with the right edge.

  • 'topLeft': Above the textbox, aligned with the left edge.

  • 'rightTop': To the right of the textbox, aligned with the top edge.

  • 'leftTop': To the left of the textbox, aligned with the top edge.

  • 'rightBottom': To the right of the textbox, aligned with the bottom edge.

  • 'leftBottom': To the left of the textbox, aligned with the bottom edge.

  • 'rightCenter': To the right of the textbox, vertically centered (not available in TEXTAREA).

  • 'leftCenter': To the left of the textbox, vertically centered (not available in TEXTAREA).

  • 'inside': Inside the textbox, button only.

  • 'hide': No button. Only use this option if you plan on giving the user alternative controls. You can find more details in section 3.7

INPUT TEXT Examples

settingsPlacement: 'bottomRight'
settingsPlacement: 'topLeft'
settingsPlacement: 'rightCenter'
settingsPlacement: 'inside'
settingsPlacement: 'inside' (TEXTAREA)

You can fine tune the placement of the Yamli settings link using the following options:

Option Name: settingsXOffset, settingsYOffset
Type: number
Scope: global, local
Use a positive or negative number to specify the horizontal and vertical offsets in pixels. For vertical offsets, a negative value move the settings link up in the page.

Here is an example of the use of this option:

settingsPlacement: 'rightTop'
settingsXOffset: 20
settingsYOffset: -10

3.4 Enable/Disable Yamli by Default

Deciding whether Yamli is enabled or disabled by default is an important decision.

Important: Yamli will not interfere with the user is typing directly in Arabic (for example with an Arabic keyboard).

The following option determines Yamli's start mode:

Option Name: startMode
Type: string
Scope: global, local
Values:
  • 'onOrUserDefault' (default):
    Use the user's last on/off choice. If the user has never turned Yamli on or off, defaults to on.
    Recommended if you expect mostly Arabic input, but want to disable Yamli if the user has chosen not to use it in the past.

  • 'offOrUserDefault':
    Use the user's last on/off choice. If the user has never turned Yamli on or off, defaults to off.
    Recommended if you expect mostly English input, but want to enable Yamli if the user has chosen to use it in the past.

  • 'on':
    Always on when the page is loaded.
    Recommended if you expect mostly Arabic input.

  • 'off':
    Always off when the page is loaded.
    Recommended if you expect mostly English input.

Here are some examples of the startMode option. To see how Yamli remembers your last choice with "onOrUserDefault" and "offOrUserDefault", switch Yamli on or off, then refresh this page.

startMode: 'onOrUserDefault'
startMode: 'offOrUserDefault'
startMode: 'on'
startMode: 'off'

3.5 Hide Optional UI Components

You can choose to hide certain parts of the Yamli UI. The following options let you customize the complexity of Yamli for your website's users.

Option Name: showTutorialLink
Type: boolean
Scope: global, local
Values:
  • true (default): Show the Yamli tutorial link in the settings menu.

  • false: Hide the Yamli tutorial link in the settings menu.

Option Name: showDirectionLink
Type: boolean
Scope: global, local
Values:
  • true (default): Show the text direction toggle in the settings menu.

  • false: Hide the text direction toggle in the settings menu.

Here is an example of these options:

showTutorialLink: false
showDirectionLink: false

3.6 Fonts and Colors

You can change the default colors and font preferences used in part of the Yamli user interface. These options will help you integrate Yamli more seamlessly in your web page.

User Interface Font

Text appears in many areas of the Yamli user interface. The user interface for a single textbox uses a single font family, which you can set using the following option:

Option Name: uiFontFamily
Type: string
Scope: global, local
Values: Any valid css "font-family" property string
This option lets you customize the font used throughout the Yamli user interface.

In this example, we try a few different font families:

uiFontFamily: 'times'
uiFontFamily: 'monospace'

Settings Text Color

Because Yamli settings button and link appear over your existing web page content, you need to be able to control the color of the text to ensure that it is readable over your background. Use the following options to do this:

Option Name: settingsColor, settingsLinkColor
Type: string
Scope: global, local
Values: Any valid css "color" property string
This option lets you customize the color of the Yamli settings text and links.

In this example, we change the colors of the settings text:

settingsColor: 'red'
settingsLinkColor: '#00bb00'

Note: At this moment, you cannot change the color of the text or the background in the Yamli popups that appear when you type Arabic or access the settings.

3.7 Enable/Disable Yamli Dynamically (Advanced)

Although the Yamli API provides your users with an easy to use interface to control the function of the API, you may want finer control over this experience. To achieve this, you may first choose to hide the standard Yamli button from your textboxes. To do this, set the "settingsPlacement" option to "hide" (see section 3.3).

The next step is to control:

  • Whether the Yamli API is enabled or disabled on the textbox(es)

  • Global and local options

To enable Yamli dynamically, use the Yamli.yamlify, Yamli.yamlifyClass or Yamli.yamlifyType functions described in section 2.2

To disable Yamli dynamically, use the corresponding functions listed below:

Function: Yamli.deyamlify ( elementId )
This function removes Yamli's functionality from a given textbox. The textbox is specified using the "elementId" parameter.
Parameter name: elementId
Type: string
Required: yes
This parameter corresponds to the "id" attribute of the textbox. The textbox is expected to have been previously "yamlified" using Yamli.yamlify(). Calling Yamli.deyamlify() on a regular textbox has no effect.
Function: Yamli.deyamlifyClass ( clsName )
This function removes Yamli's functionality from all the textboxes with a class matching the parameter "clsName".
Parameter name: clsName
Type: string
Required: yes
This parameter corresponds to the "class" attribute of textboxes. The textboxes are expected to have been previously "yamlified" using Yamli.yamlifyClass().
Function: Yamli.deyamlifyType ( typeName )
This function removes Yamli's functionality from all the textboxes with a type matching the parameter "typeName".
Parameter name: typeName
Type: string
Required: yes
Values:
  • 'textbox': Yamlify all INPUT (TYPE="TEXT") elements in the page.

  • 'textarea': Yamlify all TEXTAREA elements in the page.

  • 'rte': Yamlify all RTE elements in the page. This function affects both IFRAME and CONTENTEDITABLE rich text editors.

  • 'any': Yamlify all elements in the page.

The textboxes are expected to have been previously "yamlified" using Yamli.yamlifyType().

In this example, use the buttons to "yamlify" and "deyamlify" the textbox:

3.8 Change Options Dynamically (Advanced)

Use the following functions to change global, class and individual textbox options dynamically.

Function: Yamli.setGlobalOptions ( options )
Use this function to modify the global Yamli options that were initially set with Yamli.init().
Parameter name: options
Type: object
Required: yes
The options parameter should be an object with key/value corresponding to the desired global options (See section 3.1 for more details).
Function: Yamli.setClassOptions ( clsName , options )
Use this function to modify the options specific to a class that were initially set with Yamli.yamlifyClass().
Parameter name: clsName
Type: string
Required: yes
This parameter corresponds to the class of the textboxes. The textbox is expected to have been previously "yamlified" using Yamli.yamlifyClass().
Parameter name: options
Type: object
Required: yes
The options parameter should be an object with key/value corresponding to the desired local options (See section 3.1 for more details).
Function: Yamli.setIdOptions ( elementId , options )
Use this function to modify the options specific to a textbox that were initially set with Yamli.yamlify().
Parameter name: elementId
Type: string
Required: yes
This parameter corresponds to the "id" attribute of the textbox. The textbox is expected to have been previously "yamlified" using Yamli.yamlify().
Parameter name: options
Type: object
Required: yes
The options parameter should be an object with key/value corresponding to the desired local options (See section 3.1 for more details).

In this example, we change the color of the text in the Yamli button text:


3.9 Transliteration Popup Direction

Sometimes you need to use the Yamli API on a textbox that is pinned near the bottom of the browser window (for example think of the Facebook chat window). In situations like this, the Yamli transliteration menu would normally popup underneath the text being typed, and as a result might not be completely accessible to the user. Use the popupDirection option to make the transliteration menu pop up above the text being typed.

Option Name: popupDirection
Type: string
Scope: global, local
Values:
  • 'down' (default): The transliteration menu shows up below the text being typed.

  • 'up': The transliteration menu shows up above the text being typed.

INPUT TEXT Examples

popupDirection: 'up'

4. Troubleshooting Options

Depending on how your website is designed, you may need to tweak Yamli's functionality to get it to fit in right. This section presents several options that may help you troubleshoot and solve some of these issues.

In general, you will only need to read this section if you experience problems with the API. Understanding this section requires a more advanced level of understanding of web programming.

4.1 Z-Index and Overlapping

The Yamli API user interface is displayed on top of your existing web page. This can be a problem if your website uses absolute positioning and the z-index property. The Yamli UI may show above or below your content, depending on the z-index of the HTML elements on your page. Note that it is generally not a common issue, but might happen if, for example, you use a Javascript popup library.

Option Name: zIndexBase
Type: number
Scope: global
The default value is 1000. The Yamli user interface uses elements at various z-index values, ranging from zIndexBase to zIndexBase + 4.

4.2 'Onchange' Event

Your webpage may rely on the 'onchange' event to detect changes to the text in a textbox. This is not uncommon, and usually happens if your page performs a validation operation on the content of the textbox, for example to check that it is formatted as an email address.

When you Yamlify a textbox in your webpage, the Yamli API will dynamically change text from latin characters to Arabic characters. These changes happen asynchronously, which means that, depending on the connection speed, Yamli may perform the conversion to Arabic while the user has moved onto another textbox. Your validation logic may not take into account this change.

By default, when Yamli changes the text in a textbox, an 'onchange' will NOT be generated. If you wish to have Yamli generate 'onchange' events, use the following option:

Option Name: generateOnChangeEvent
Type: boolean
Scope: global, local
Values:
  • false (default): Do NOT generate 'onchange' events when Yamli converts text to Arabic.

  • true: Generate 'onchange' events when Yamli converts text to Arabic.