bryce/jquery.uls
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Do not group search results by region

Browse Source 
* Documentation updates
* Do not group search results by region
* Disable grouping by script when region grouping is disabled
* Add docs, clarify names per code review
* Fix bool -> boolean for consistency
This commit is contained in:
Niklas Laxström
2018-01-16 13:34:29 +02:00
committed by Santhosh Thottingal
parent fd41bbe5e1
commit d349937772
5 changed files with 157 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
README.md
View File

@@ -1,10 +1,8 @@
jQuery Universal Language Selector
Universal Language Selector jQuery library
==================================
Universal Language Selector
[![Build Status](https://secure.travis-ci.org/wikimedia/jquery.uls.png)](http://travis-ci.org/wikimedia/jquery.uls)
This is a [Wikimedia Foundation Language Engineering team project](https://www.mediawiki.org/wiki/Project_Milkshake).
This is a [Wikimedia Foundation project](https://www.mediawiki.org/wiki/Project_Milkshake).
![Universal Language Selector](https://upload.wikimedia.org/wikipedia/commons/a/a1/UniversalLanguageSelector-Compact.png "Universal Language Selector")
@@ -19,86 +17,69 @@ git clone https://github.com/wikimedia/jquery.uls.git
Documentation
-------------
The quick and easy way to learn usage of jquery.uls is trying out the examples/index.html in some webserver. Try it from here: http://thottingal.in/projects/js/jquery.uls/examples/
The quick and easy way to learn usage of jquery.uls is trying out the examples/index.html in webserver. Try it online at http://thottingal.in/projects/js/jquery.uls/examples/
The jQuery.uls provides a jQuery extension ```$.fn.uls``` that can be attached to a trigger element. The expected behavior is, when you click on the trigger, the language selector opens up.
The jquery.uls provides a jQuery extension ```$.fn.uls``` that can be attached to a trigger element. When you click on the trigger element, the language selector is shown.
The trigger can be a link, button or any valid jQuery element.
Example:
```javascript
$( '.uls-trigger' ).uls( );
$( '.uls-trigger' ).uls();
```
To use the selected language, you need define a selection Handler as shown below
To use the selected language, you need define a selection handler:
```javascript
$( '.uls-trigger' ).uls( {
onSelect : function( language ) {
// language is a ISO 639 language code. eg: en, hi, fi, he etc
onSelect: function( language ) {
// language is a IETF language tag in lowercase, for example: en, fi, ku-latn
// Your selection handler code goes here.
}
} );
```
In some usecases, you may need to provide a quick list of languages to select before going through all languages. For eg, it can a list of recently selected languages, language suggestions based on Geo IP.
That can be done as follows
You can provide a quick list of likely useful languages, for example based on Geo IP or recently selected languages:
```javascript
$( '.uls-trigger' ).uls( {
onSelect : function( language ) {
// language is a ISO 639 language code. eg: en, hi, fi, he etc
// Your selection handler code goes here.
},
quickList: [ 'en', 'ml', 'hi' ] // An array of language codes. Can be a function that returns this array too.
onSelect: function( language ) { ... },
quickList: [ 'en', 'ml', 'hi' ] // Can be a function returning an array too.
} );
```
If the search needs to be more complex(such as cross language search, spelling error tolerating etc), a search API option can be provided.
jquery.uls knows about 500 languages. You can specify a subset of those languages:
```javascript
$( '.uls-trigger' ).uls( {
onSelect : function( language ) {
// language is a ISO 639 language code. eg: en, hi, fi, he etc
// Your selection handler code goes here.
},
searchAPI: apiURL,
quickList: [ 'en', 'ml', 'hi' ] // An array of language codes. Can be a function that returns this array too.
onSelect: function( language ) { ... },
languages: { languageCode1: languageName, languageCode2: languageName2, .... },
} );
```
Example for such an api is used in Wikipedia: http://en.wikipedia.org/w/api.php?action=languagesearch&search=Te
ULS knows about 500 languages. If you dont want to use that many languages for your usecase, use languages option.
```javascript
$( '.uls-trigger' ).uls( {
onSelect : function( language ) {
// language is a ISO 639 language code. eg: en, hi, fi, he etc
// Your selection handler code goes here.
},
languages: { languageCode1: languageName, languageCode2: languageName2 , .... },
searchAPI: apiURL,
quickList: [ 'en', 'ml', 'hi' ] // An array of language codes. Can be a function that returns this array too.
} );
```
*Other Options*
*All options*
| Option | Description |
|-------------|---------------------|
| left | left position of ULS. eg: 100px, 20%|
| top | top position of ULS. eg: 100px, 20%|
| onCancel | function to be handled when language selection is not done. ie. language selector is closed without selecting any |
| showRegions | Regions to be shown in the language selector. Default: ['WW', 'AM', 'EU', 'ME', 'AF', 'AS', 'PA'] |
| left | Left position of ULS dialog. E.g: 100px or 20% |
| top | Top position of ULS dialog. E.g: 100px or 20% |
| onCancel | Callback function when the dialog is closed without selecting a language. |
| onReady | Callback function when ULS has initialized. |
| onVisible | Callback function when ULS dialog is shown. |
| onSelect | Callback function when user selects a language. |
| languages | List of selectable languages. Defaults to all known languages. |
| quicklist | List of suggested languages. Defaults to empty list. |
| searchAPI | API URL. Parameter query with the user query is appened to it. |
| menuWidth | Override the automatic choice of menu width. One of narrow, medium, wide (1, 2, 4 columns respectively). |
| showRegions | Regions to be shown in the language selector. Defaults to [ WW, AM, EU, ME, AF, AS, PA ] |
| groupByRegion | Whether to group languages by the regions: true of false. Default value depends on the menu width. |
| itemsPerColumn | Number of languages per column. Default is 8 |
| languageDecorator | Callback function to be called when a language link is prepared - for custom decoration. Arguments: (a) the $language - the language link jQuery object (b) languageCode. The function can do any styling, changing properties etc on the passed link. See examples/decorator.html for example usage.|
Features
--------
jQuery.uls has an elaborative language information collection and it is based on https://github.com/wikimedia/language-data.git. It knows about
jquery.uls has an elaborative language information collection and it is based on https://github.com/wikimedia/language-data.git. It knows about
1. The script in which a language is written.
2. The script code
@@ -107,14 +88,7 @@ jQuery.uls has an elaborative language information collection and it is based on
5. The autonym - language name written in its own script
6. The directionality of the text
With all these information the search becomes very effective. Based on the spoken regions, the UI organize the languages. In side regions
the language is again organized based on scripts.
A user can search for a language based on script name.
ULS can autocomplete a language name search.
An advanced usage of jQuery.uls can be tried out from wikimedia sites. For eg, see the language icon at the top of http://mediawiki.org or the cog icon near to the languages list in wikipedia in any language
With all these information the search becomes very effective. An advanced usage of jquery.uls can be tried out from Wikimedia sites. For example, see the language icon at the top of https://mediawiki.org or the cog icon near to the languages list in Wikipedia in any language.
More details
------------
@@ -122,7 +96,7 @@ More details
* UX Design https://www.mediawiki.org/wiki/Universal_Language_Selector/Design
How to build and test jQuery ULS
How to build and test jquery.uls
----------------------------------
First, get a copy of the git repo by running:
@@ -150,4 +124,4 @@ You can also run the tests in a browser by navigating to the `test/` directory,
Coding style
-------------
Please follow [jQuery coding guidelines](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
Please follow [MediaWiki coding conventions](https://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript)