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.

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

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.

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

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:

Here is an example of the use of this option:

settingsPlacement: 'rightTop'

settingsXOffset: 20

settingsYOffset: -10

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:

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'

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.

Here is an example of these options:

showTutorialLink: false

showDirectionLink: false

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:

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:

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.

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:

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

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

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

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.

INPUT TEXT Examples

popupDirection: 'up'