SG

Поисковые подсказоньки

Сборка

Для сборки используется grunt v0.4.

git clone https://github.com/DriverX/SG.git
cd SG
npm install grunt
npm install grunt-contrib-concat
npm install grunt-text-replace
npm install grunt-closure-tools
grunt
ls -l sg*

Простой пример

<!doctype html>
<html>
<head>
 <meta charset="utf-8">
 
 <!-- load SG library -->
 <script src="sg.js"></script>
</head>
<body>
 <!-- search form with suggests -->
 <form action="http://go.mail.ru/search">
  <input id="query-input" name="q">
  <input type="submit" value="Search">
 </form>
 
 <!-- main suggests container -->
 <ul id="sg-items" style="display: none;"></ul>
 
 <script>
  var suggests = SG({
   // field, which will be inserted ыгппуыешщт
   field: "#query-input",
   // container for suggests
   cont: "#sg-items",
   // template per suggestion
   item: "<li><%= itemData.textMarked %></li>"
  });
 </script>
</body>
</html>

All done!

Static properties

Event - класс событий
evt - содержит в себе все идентификаторы событий, на которые можно подписаться
utils - полезные утилиты
opts - глобальные настройки саджестов

SG.Event

SG.Event предоставляет простой интерфейс для работы с событиями. Поддерживает как DOMEvent, так и кастомные события, как на DOMNode, так и на любой произвольном объекте.

Event.add

SG.Event.add( elem, event, callback )

elem - DOMNode|Object объект к которому привязывается обработчик на событие event
event - String событие. Возможно указание нескольких событий, достаточно разделить их пробелом, например "focus blur"
callback - Function

Метод добавления обработчиков событий

var elem = document.getElementById("some_link"),
	i = 0;
SG.Event.add( elem, "click", function( event ) {
	i++;
	this.innerHTML = "i = " + i;
	
	event.preventDefault();
});

Event.rm

1) SG.Event.rm( elem )
2) SG.Event.rm( elem, event )
2) SG.Event.rm( elem, event, callback )

elem - DOMNode|Object объект, с которого удаляется обработчик события
event - String событие. Возможно указание нескольких событий, достаточно разделить их пробелом, например "focus blur"
callback - Function

Удаляет с объекта все обработчики со всех событий
Удаляет все обработчики только с указанных событий
Удаляет только определенный обработчик с определенного события

Event.fire

SG.Event.fire( elem, event[, extra] )

elem - DOMNode|Object
event - String
extra - Array

Возбуждает событие event у элемента elem, с дополнительными параметрами extra обработчику, если были переданы

SG.evt

Содержит в себе все возможные события в саджестах

open -
openEnd -
close -
closeEnd -
enable -
enableEnd -
disable -
disableEnd -
destroy -
destroyEnd -
blockRequest -
successRequest -
completeRequest -
stopRequest -
errorRequest -
startRequest -
sendRequest -
passFilter -
failFilter -
rejectData -
acceptData -
render -
renderEnd -
focus -
focusEnd -
select -
selectEnd -
valueChange -
flushCache -
flushCacheEnd -
setCache -
setCacheEnd -
getCache -
getCacheEnd -

SG.utils

SG.utils.isArr

SG.utils.isArr( some_var )

Возвращает true если some_var - Array

SG.utils.isFn

SG.utils.isFn( some_var )

Возвращает true если some_var - Function

SG.utils.isObj

SG.utils.isObj( some_var )

Возвращает true если some_var - Plain Object ({})

SG.utils.isWin

SG.utils.isWin( some_var )

Возвращает true если some_var - Window

SG.utils.bind

SG.utils.bind( fn, context[, arg1[, ...[, argN]]])

fn - Function - функция, к которой привязывается контекст
context - Object|Null - привязываемый контекст
argN - Mixed параметры, которые будут переданы fn при вызове

Биндит контекст к функции

SG.utils.ext

1) SG.utils.ext( obj, extObj[, extObj1[, ...[, extObjN]]] )
2) SG.utils.ext( true, obj, extObj[, extObj1[, ...[, extObjN]]] )

Аналогичная с jQuery.extend

SG.utils.copy

SG.utils.ext( obj )

obj - Object|Array

Копирует объект или массив и возвращает копию

SG.utils.trim

SG.utils.trim( str )

str - String

Отрезает пробельные символы с начала и конца строки

SG.utils.arrEach

SG.utils.arrEach( arr, iter_fn( value, key ) )

alias Array.forEach

SG.utils.objEach

SG.utils.objEach( obj, iter_fn( value, key ) )

как SG.utils.arrEach, но для объектов

SG.utils.each

SG.utils.each( obj, iter_fn( value, key ) )

obj - Array|Object

SG.utils.map

alias Array.map

SG.utils.indexOf

alias Array.indexOf

SG.utils.format

SG.utils.format( str, replace )

str - String строка, в которой будет произведен поиск и замена
replace - Object объект с заменани, например {foo: "bar"}

Поиск и замена в str конструкций вида {some_macros} на значение ключен из replace

SG.utils.format( "Hello, {name}! Nice {time}!", {
    name: "World",
    daytime: "day"
})
// Hello, World! Nice day!

SG.utils.objFormat

SG.utils.objFormat( obj, replace )

str - Object объект, в свойствах которого будет произведен поиск и замена. Причем обрабатываются и вложенные объекты.
replace - Object объект с заменани, например {foo: "bar"}

Поиск и замена в obj конструкций вида {some_macros} на значение ключей из replace

SG.utils.objFormat({
    foo: "Hello, {name}!",
    bar: "Goodbye, {name} and good {daytime}!"
}, {
    name: "World",
    daytime: "night"
})
// {foo: "Hello, World!", bar: "Goodbye, World and good night!"}

SG.utils.walker

1) SG.utils.walker( obj, route )
2) SG.utils.walker( obj, route, value )

obj - Object
route - String путь до свойства
value - Mixed устанавливаемое значение

Идет по объекту obj с помощью дескриптора route, который в свой очередь представляет из себя запись обращения к свойствах объекта, например foo.bar.bar

Получает значение свойства. Если св-во не было найдено, то возвращает null
Устанавливает значение св-ва. Если объекта по пути не было, то он будет создан.

SG.utils.from

SG.utils.from( some )

some - Mixed

Создает массив из одного элемента, если some не был Array, или пустой, если some === null || some === undefined. Иначе возвращает some нетронутым

SG.utils.mkarr

SG.utils.mkarr( arrlike )

arrlike - Array|ArrayLike

Создает Array из arrlike, если arrlike уже был Array, то вернеться его копия

SG.utils.prm

SG.utils.prm( params )

params - Object

Сериализует params в querystring

SG.utils.aprm

SG.utils.aprm( url, params )

url - String
params - Object|String

Добавляет к url параметры params

SG.utils.url

SG.utils.url( parts )

parts - Object

Создает URL из parts.

SG.utils.url({
    scheme: "http",
    authority: "site.com",
    path: "path",
    query: "foo=bar" // or {foo: "bar"}
    fragment: "fragment"
});
// http://site.com/path?foo=bar#fragment

SG.utils.css

1) SG.utils.css( elem, cssProp )
2) SG.utils.css( elem, cssProp, cssValue )

elem - DOMNode
cssProp - String
cssValue - String|Number

Получает или устанавливает css св-во cssProp элемента elem

получает значение css св-ва cssProp
устанавливает значение cssProp: cssValue

SG.utils.addCls

SG.utils.addCls( elem, classname )

elem - DOMNode
classname - String

Добавляет элементу класс classname.

SG.utils.rmCls

SG.utils.rmCls( elem[, classname] )

elem - DOMNode
classname - String

Удаляет у элемента класс classname, если classname не был передан, то будут удалены все классы.

SG.utils.hasCls

SG.utils.hasCls( elem, classname )

elem - DOMNode
classname - String

Проверяет, есть ли класс classname у элемента elem. Возвращает true, если был найден.

SG.utils.cres

SG.utils.cres( html )

html - String html

Создает DOM-структуру по переданному html коду и возвращает созданные элементы в массиве.

SG.utils.cre

1) SG.utils.cre( nodeName )
2) SG.utils.cre( html )

nodeName, html - String

Создает DOM по переданному html-коду, или DOMNode по имени элемента

SG.utils.rme

SG.utils.rme( elem )

elem - DOMNode

Удаляет elem из DOM

SG.utils.empty

SG.utils.empty( elem )

elem - DOMNode

Очищает elem

SG.utils.attr

1) SG.utils.attr( elem, attr )
2) SG.utils.attr( elem, attr, value )

elem - DOMNode
attr - String
value - String|Number

Получает или устанавливает аттрибут у elem

SG.utils.hasFocus

SG.utils.hasFocus( elem )

elem - DOMNode

Возвращает true, если на элемент установлен focus

SG.utils.contains

SG.utils.contains( parent, child )

parent - DOMNode
child - DOMNode

Возвращает true, если child был найден в parent

SG.utils.parseXML

SG.utils.parseXML( xmlstring )

xmlstring - String

SG.utils.parseJSON

SG.utils.parseJSON( jsonstring )

jsonstring - String

SG.utils.tmpl

1) SG.utils.tmpl( template )
2) SG.utils.tmpl( template, data )

template - String|CSSSelector|DOMNode
data - Object

based on John Resig - JavaScript Micro-Templating

SG.utils.$

SG.utils.$( selector[, root])

selector - DOMNode|String
root - DOMNode|String

Ищет элемент по css-селектору selector, в root, если был передан, иначе в document

SG.utils.$$

SG.utils.$$( selector[, root])

selector - DOMNode|String
root - DOMNode|String

Ищет элементы по css-селектору selector, в root, если был передан, иначе в document, и возвращает Array

SG.utils.$ и SG.utils.$$ использует модифицированную библиотеку поиска элементов по css-селектору yass

SG.utils.Event

alias SG.Event

Static methods

SG.setup

SG.setup({
    ajax: {
        dataType: "json"
    }
});

устанавливает глобальные настройки саджестов

SG.tmpl

alias SG.utils.tmpl

SG.$

alias SG.utils.$

SG.$$

alias SG.utils.$$

Instance properties

cont - DOMNode блока саджестов
list - DOMNode блока с самими саджестами, если не был указан в опциях, то совпадает с cont
field - DOMNode игпута, к которому привязан саджест
form - DOMNode формы, содержащей инпут

Instance methods

enable

instance.enable()

Включает саджесты

disable

instance.disable()

Отключает саджесты

isDisabled

instance.isDisable()

Возвращает true, если саджесты отключены, иначе false

open

instance.open()

Открывает саджесты, с последним значением инпута.

close

instance.close()

Закрывает саджесты

isClosed

instance.isClosed()

Возвращает true, если саджесты закрыты, иначе false

destroy

instance.destroy()

Уничтожает экземпляр, вместе с событиями.

show

instance.show( value )

value - String

Показывает саджест по запросу value

flushCache

instance.flushCache()

Очищает кэш

focus

instance.focus( index )

index - Number

Ставит фокус на определенный саджест по переданному index.

moveFocus

instance.moveFocus( step )

step - Number

Сдвигает фокус. Если step отрицательный, то сдвигает вверх.

select

instance.select( index )

index - Number

Выбрать конкретный саджест по индексу.

on

instance.on( event, callback )

event - String
callback - Function

Подписаться на событие

instance.on( SG.evt.close, function( suggestValue ) {
    // do something
});

off

instance.off( event, callback )

event - String
callback - Function

Отписаться от события

instance.on( SG.evt.close, function( suggestValue ) {
	// do something
	instance.off( SG.evt.close, arguments.callee );
});

opts

1) instance.opts( option[, value] )
2) instance.opts( option )
3) instance.opts()

option - String|Object
value - Mixed

Устанавливает опции. Может быть передан один лишь Object option с перечисленными опциями, или могут быть переданы оба параметра: option, value; причем, если у опции глубокая вложенность, то можно обратиться через точку, например instance.opts("url.port", 80).
Получить значение отдельной опции передав параметром ее имя, например instance.opts("ajax.dataType")
Получает все опции экземпляра

getState

instance.getState()

Возвращает Object с текущим состоянием саджестов. Доступные свойства объекта:

current - текущее считанное значение из инпута
recent - последнее считанное значение из инпута, может совпадать с current
previous - предыдущее значение инпута
value - запрос, по которому были запрошены саджесты
data - данные саджестов
fullData - полные полученные данные по запросу
focused - индекс выделенного саджеста
method - метод выбора саджеста: mouse или keyboard
selected - индекс выбранного саджеста
result - текст выбранного саджеста, который будет подставлен в инпут
itemData - данные выбранного саджеста
hovered - индекс подсвеченного саджеста
items - элементы саджестов

Конструктор

SG( options );

new SG( options );

Опции

field

Selector|DOMNode инпут, к которому следует привязать саджесты

cont

Selector|DOMNode главный блок, который будет прятаться/показываться default: "#sg, .sg"

list

Selector|DOMNode блок, где будут рисоваться саджесты. Если не указан, то будет использоваться cont

enabled

Boolean указывает, будет ли включен саджест при создании экземпляра. Если false, то для включения нужно будет вызвать метод instance.enable(). default: true

correction

Boolean Если true, то будет включена автокоррекция блока cont относительно field, причем корректироваться будет только в случае, если у блока указан стиль position: absolute|relative|fixed. default: true

shiftX

Integer величина в пикселях, на которую следует скорректировать по горизонтали cont относительно 'field'. default: 0

shiftY

Integer величина в пикселях, на которую следует скорректировать по вертикали cont относительно 'field'. default: 0

switcher

String класс, который будет добавляться/удаляться, когда cont будет показан/убран. Если не указан, то у cont будет стираться и добавляться стиль 'display: none'

delay

Integer интервал, через которые будет проверяться field на наличие изменений в значении default: 250

valMin

Integer минимальное кол-во символов для срабатывания саджестов default: 1

valMax

Integer максимальное кол-во символов для срабатывания саджестов default: 255

valFilter

RegExp|Function фильтр, при положительном срабатывании которого будет срабатывать саджест default: /(?:\S)/

url

String|Object url, по которому будет запрашиваться саджест. default: "http://suggests.go.mail.ru/sg_u?q={query}"

обе записи идентичны:

SG({
    url: "http://suggests.go.mail.ru/sg_u?q={query}"
})

SG({
    url: {
        scheme: 'http',
        authority: 'suggests.go.mail.ru',
        path: "sg_u",
        query: {
            q: '{query}'
        }
    }
})

ajax

dataType - String text|html|xml|json|jsonp тип получаемых данных. В зависимости от значенния может выбираться разный способ создания запроса. default: "jsonp"
method - String POST|GET метод отправки запроса default: "GET"
data - Object параметры добавляемые запрашиваемуму url
contentType - String default: "application/x-www-form-urlencoded; charset=utf-8"
xhrFields - Object поля добавляемые в xhr объект при создании запроса. по умолчанию withCredentials: false
jsonp - String имя параметра в запросе для передачи имени колбэка при jsonp запросах. default: "callback"
jsonpCallback - String|Function имя колбэка, если используется jsonp. default: function() {return "{EXPANDO}_{REQUEST_ID}"}
scriptCharset - String кодировка в которую следует перевести ответ при jsonp запросах. default: "utf-8"
timeout - Integer таймаут запроса, по истечении которого будет принудительно вызван abort(), default: 5000
stackSize - Integer максимальное одновременное кол-во запросов. default: 2

callbackParam

deprecated, use ajax.jsonp

reqTimeout

deprecated, use ajax.timeout

reqMax

deprecated, use ajax.stackSize

reqDataType

deprecated, use ajax.dataType

reqData

deprecated, use ajax.data

scriptCharset

deprecated, use ajax.scriptCharset

dataFilter

Function фильтр данных пришедших по запросу

dataGet

Function функция извлекающая данные для элементов саджеста default: function( data ){return data && data.items ? data.items : [];}

cch

Boolean Если true, то включает кэширование данных по конкретному запросу. default: true

cchLimit

Integer кол-во хранимых запросов-данных. default: 128

max

Integer максимальное кол-во выводимых саджестов. default: 10

min

Integer минимальное кол-во выводимых саджестов. default: 0

autoSubmit

Boolean Если true, то будет выполняться submit() формы сразу после выбора конкретного саджеста. default: true

hover

String класс добавляемый элементу саджеста при выборе. default: "sg__item_hover"

item

String|Function|DOMNode шаблон или фукнция для генерации html каждого конкретного саджеста. default: <div class="sg__item"><%= itemData.textMarked %></div>'

result

Function функция, которая извлекает запрос из данных каждого конкретного саджеста. default: function( itemData ) {return itemData.text;}

select

Function hook-функция, которая должна быть вызвана при выборе саджеста. С помощью этой опции можно предовратить выбор саджеста, достаточно вернуть false в функции.

keynavDelay

Integer задержка при выборе саджеста с клавиатуры. default: 150

preview

Boolean если true, то подставляет запрос выделенного саджеста в field. Работает только если выбирать саджест с клавиатуры. default: true

on{SG.evt.*}

Помогает привязаться к событие сразу из конфига

var instance = SG({
    field: "#foo",
    onEnable: function() { // same instance.on(SG.evt.enable, function() {}) 
    	// do something
    },
    onDisable: function() { // same instance.on(SG.evt.disable, function() {})
    	// do something
    }
});

driverx / sg Goto Github PK

sg's Introduction

SG

Сборка

Простой пример

Static properties

SG.Event

Event.add

Event.rm

Event.fire

SG.evt

SG.utils

SG.utils.isArr

SG.utils.isFn

SG.utils.isObj

SG.utils.isWin

SG.utils.bind

SG.utils.ext

SG.utils.copy

SG.utils.trim

SG.utils.arrEach

SG.utils.objEach

SG.utils.each

SG.utils.map

SG.utils.indexOf

SG.utils.format

SG.utils.objFormat

SG.utils.walker

SG.utils.from

SG.utils.mkarr

SG.utils.prm

SG.utils.aprm

SG.utils.url

SG.utils.css

SG.utils.addCls

SG.utils.rmCls

SG.utils.hasCls

SG.utils.cres

SG.utils.cre

SG.utils.rme

SG.utils.empty

SG.utils.attr

SG.utils.hasFocus

SG.utils.contains

SG.utils.parseXML

SG.utils.parseJSON

SG.utils.tmpl

SG.utils.$

SG.utils.$$

SG.utils.Event

Static methods

SG.setup

SG.tmpl

SG.$

SG.$$

Instance properties

Instance methods

enable

disable

isDisabled

open

close

isClosed

destroy

show

flushCache

focus

moveFocus

select

on

off

opts

getState

Конструктор

Опции

field

cont

list

enabled

correction