Yamli API


Last updated: July 1, 2010

1. About the API

1.1 What is the Yamli API?

The Yamli API allows you to integrate our smart Arabic keyboard technology into your website. You can use the API to empower your users to type Arabic in any textbox on your website or blog, including email, forums, search boxes, etc…

Example of a "Yamlified" text box:

The API is designed to be very simple to use and to provide a seamless integration with your page. When you "yamlify" a textbox, the Yamli settings link appears next to, or inside, the textbox. You don't need to modify your page structure to use the Yamli API. Just use our setup tool to easily create the Yamli script to add at the bottom of your pages.

1.2 Who is it for?

The API is designed to be used by site owners with no coding experience all the way to advanced developers who need finer controls in order to unleash their creativity. Use it on your site or blog, or develop your own applications.

1.3 How does it benefit me?

Yamli's smart Arabic keyboard allows your users to write Arabic whether they have an Arabic keyboard or not. It removes the obstacles to interacting in Arabic with your site, and encourages new users to become more proactive. See how others are using it.

Yamli's smart keyboard is the most advanced Arabic typing solution on the web.

  • It is very easy to use and requires no learning

  • It is highly accurate and works with any dialect and/or spelling style

  • It is flexible and adapts to your users' typing patterns

1.4 Would users who type with an Arabic keyboard be affected?

No. If a user types directly in Arabic (using an Arabic keyboard), Yamli does not get activated and stays out of the way.

1.5 Are there any restrictions to using the API?

There are no limits on how many pages you use the API on, and how many users or page loads you have. So feel free to put it everywhere!

There are a few restrictions that are explained in our Terms of Service. Here are some of the more important ones:

  • You cannot use the Yamli API with a general purpose search engine (For example a Google search box). However, it's perfectly fine to use it for a limited search engine. For example, you could use Yamli on a search box restricted to finding content on your website.

  • You cannot use the Yamli API on websites engaging in or promoting illegal activities

1.6 Do I need a website to use the API?

Generally yes. You need to be able to edit the HTML content of your page in order to use the API. We are currently working on plugins for popular blog sites to allow people to integrate Yamli more easily, even when they don't have direct access to the website HTML source.

You can also create tools around the Yamli API. For example, you could develop a Firefox extension that would use the API. We don't restrict these uses, in fact we encourage them! Just keep in mind that you must only use documented features of the API (anything else can change without notice at any time).

1.7 What browsers does it support?

Yamli fully supports all the mainstream web browsers:

  • Internet Explorer 6, 7 and 8

  • Firefox 2 and 3 and above

  • Apple Safari 3.1 and above

  • Google Chrome 1.0 and above

  • Opera 9.5 and above

1.8 Can I use the Yamli API on my forum (using VBulletin for example)?

YES! To enable Yamli on your your forum, try using the Yamlify.yamlify('rte') described in section 2.2 of our API documentation.

1.9 Can I use the Yamli API with my webmail (Gmail, Hotmail, Yahoo Mail, etc...)?

Yes, using our Google Chrome plugin or our Firefox plugin.

2. Setting up the Yamli API

2.1 Do I need to sign up?

No signups or account numbers are required. However, we do recommend that you register to receive updates about the API, but it's completely optional. We will only send emails about new API features, or support issues we feel are important for our API community.

2.2 Do I need to understand HTML or Javascript?

No, you can use our easy setup tool to setup Yamli just right for your web site.

2.3 How do I setup the Yamli API for my website?

You can either use our easy setup tool, or read the API documentation if you need finer control over the API's functionality.

2.4 How do I find the textbox id? What if there isn't one?

To locate the textbox id, go to the your page's HTML source code and locate one of the following tags:

<input type="text" id="textbox_id_1" ... />
<textarea id="textbox_id_2" ... ></textarea>

In these examples, the id of the textboxes are "textbox_id_1" and "textbox_id_2" respectively.

In some cases, the textbox may NOT have an id. In this case, you can just add one. Keep in mind that id's should be unique in the page, so don't use an id that already exists.

Sometimes the textbox will have a name attribute. If so, you could use the same value for the id, which would look something like this:

<textarea name="textbox_name_1" id="textbox_name_1" ... ></textarea>

Again, make sure that the id you use is unique inside the page (sometime the same name is used several times in the same page).

2.5 Where should I put the Yamli script in my page's HTML?

Ideally, you should place the Yamli script at the bottom of your HTML page, just before the closing </body> tag. Yamli will work fine even if you don't do so, but following this rule makes your pages load faster.

2.6 Can I use the Yamli API in blog or forum plugins, or even in browser add-ons?

Yes! You can use the API to build new tools or to build plugins. For example, you could develop a Firefox extension that would use the API, or a WordPress plug in, etc... Please refer to the API documentation and sign up to the mailing list to stay updated about the latest API features. Feel free to contact us directly as well.

3. Customizing the Yamli API

3.1 What are the supported languages?

While the Yamli API is always used to type Arabic, its user interface is available in 3 languages:

  • English

  • Arabic

  • French

3.2 I "yamlified" my textbox, but the Yamli button is getting in the way. How can I move it?

Users control Yamli's functionality through a Yamli settings button that is placed either next to or inside the "yamlified" textbox. By default, this button is located on the bottom left of the textbox. This location may not be appropriate for your textbox. You can change this location using our easy setup tool, or by manually changing the "settingsPlacement" option, as documented here.

3.3 My visitors don't want to type Arabic all the time. Can I set up Yamli so that it is disabled by default?

Yes. By default, Yamli will convert latin characters to Arabic in a "yamlified" textbox. This may not be desirable, for example if you expect that most of your visitors would rather write in English than in Arabic.

If you wish to have Yamli disabled when the page loads, set the "Enable Yamli by default" option to "Off" in the easy setup tool. Alternatively, you can manually set the "startMode" option, as documented here. The user can always choose to turn Yamli on if they need to use the Yamli settings button next to or in the textbox.

3.4 Can I change the Yamli fonts and colors to match my website?

Yes. The default color of the Yamli settings button is blue. To change this, change the "settingsColor" and "settingsLinkColor" options as described in the documentation.

You can also change the Yamli settings font using the "uiFontFamily" option, also documented here.

Remember that you can set options for all the textboxes in your page (using global options), for a group of textboxes (using class options), or for an individual textbox (using id options).

4. Troubleshooting

I setup the API, but nothing is showing up. What could be wrong?

If you have correctly copied the Yamli API script generated by the easy setup tool, then you might have incorrectly typed the id of the textbox you wish to "yamlify". Double-check the HTML source of your page for the "id" attribute of the <textarea> or <input type="text"> textbox, and make sure the id specified in the Yamli.yamlify() function in the script matches exactly.

In addition, the Yamli API is not compatible with Rich Text Editors, which are frequently found in blog or forum software. See FAQ 1.8 for more details.

If you are sure that the script and the textbox id are correct, and you still cannot see the Yamli button and/or typed text isn't being converted to Arabic, send us a quick bug report. Make sure to include the url of your website.

4.2 The Yamli button is showing up on top of other content on my site. How can I prevent this?

Some websites use an HTML feature called the z-index to compose their web pages. The z-index controls how HTML elements are layered on top of each other when they overlap.

The Yamli API also uses the z-index to make sure the Yamli user interface elements (such as the settings button) properly appear next to or inside the textboxes. On some pages, the Yamli button can show up on top of a z-indexed HTML element that covers the original textbox.

The Yamli API uses z-index values from 1000 to 1004. You can either change the z-index of the element that should be on top of the textbox to a value above 1004, or change the z-index that Yamli uses. To do this, use the "zIndexBase" option, as described in the documentation.