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 and 7 on Windows platforms
Firefox 2 and 3 on Windows and Mac OS X platforms
Apple Safari 3.1 and newer on Mac OS X platforms

The following platforms are unofficially supported:

Opera 9.5 on Windows platforms
Firefox 2 and 3 on Linux platforms
Apple Safari 3.1 and newer on Windows platforms

Yamli has been reported to work on these platforms, and we work to support them as resources permit.

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

We currently do not support Rich Text Editor (RTE) controls, because these are not standard HTML controls and many implementations exist. We are investigating how to support these controls in the future.

2. The Basics - How to Integrate Yamli in 5 Minutes

2.1 Registering for an Account

At the moment, registration for a Yamli API account is by invitation only. If you wish to participate, please drop us a note here.

Use of the Yamli API is free of charge. You must agree to the following Terms of Service in order to use the API.

After you register for a Yamli API account, you will receive a 6-digit account number. You will need to use this account number when invoking the Yamli API.

Your Yamli API account can only be used on domains that you specify. You will need to let us know which domains you wish to use with the API. This is usually "www.yourdomainname.com".

2.2 "Yamlify" Your Textboxes

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('000003'))
      {
        Yamli.yamlify('textbox_id');
      }
    </script>

  </body>
</html>

In this script, you should replace 000003 with your 6-digit Yamli API account number.

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, but it MUST come after the last non-script tag in the <BODY>.

You should also 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>

If you have more than one textbox to yamlify, you can add more Yamli.yamlify() statements.

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 both globally, for all the textboxes in the page, and locally, for a single textbox.

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('000003',
                                              { option1: value1,
                                                option2: value2,
                                                ... more options ...,
                                                optionN: valueN })
  {
    ...
  }
</script>

Local options are set in the Yamli.yamlify() function calls. This is how you use them:

<script type="text/javascript">
  if (typeof(Yamli) == 'object' && Yamli.init('000003'))
  {
    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 and 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.

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.

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 is 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.

Yamli API Documentation

Table of Contents

1. Introduction

1.1 About the Yamli API

1.2 Requirements

2. The Basics - How to Integrate Yamli in 5 Minutes

2.1 Registering for an Account

2.2 "Yamlify" Your Textboxes

3. Customize Yamli

3.1 Global and Local Options

3.2 User Interface Language

3.3 Yamli Settings Placement

3.4 Enable/Disable Yamli by Default

3.5 Hide Optional UI Components

3.6 Fonts and Colors

4. Troubleshooting Options

4.1 Z-Index and Overlapping

4.2 'Onchange' Event