bem-history doc

README.md

bem-history

EN

What is this?

BEM wrap for History API:

• supports browsers with a native History API and hashchange event;
• provides manipulations with url, browser location and history in the terms of BEM (http://bem.info/).

Components

• uri – module for an url parsing;
• history – module provides work with a browser History with two modificators:
• provider_history-api – supports a native History API;
• provider_hashchange – supports fallback on the hashchange event;
• location – high-level module for a window.location change.

Scheme of library work

Usage

uri

modules.require(['uri'], function(Uri) {

    // Parse url
    var u = Uri.parse('http://example.org:8080/path?test=1&test=2&param2=22');
    
    // Change port
    u.setPort(80);
    
    // Change query params
    u.deleteParam('test', '2');
    u.replaceParam('param2', 2);
    
    // Serialize url
    u.toString(); // "http://example.org:8080/path?test=1&param2=2"
    
});

history

modules.require(['history'], function(History) {

    // Create history instance
    var history = new History();

    // Push new or replace history state
    history.changeState('push', { title: 'Title', url: 'http://example.org:8080/path' });
    history.changeState('replace', { title: 'Title', url: 'http://example.org:8080/path?test=1' });
    
});

location

modules.require(['location'], function(location) {

    // Change `window.location` using a full url
    location.change({ url: 'http://example.org:8080/path' });

    // Change current location using only the new query params
    location.change({ params: { param1: [11,12], param2: 'ololo' } });
    window.location.href; // "http://example.org:8080/path?param1=11&param1=12&param2=ololo"  
    
});

README.ru.md

bem-history

RU

Что это?

БЭМ-обертка над History API:

• работает в браузерах со встроенной поддержкой History API и с возможностью фолбэка на событие hashchange;
• позволяет работать с url, location и history браузера в терминах БЭМ (http://bem.info/).

Состав

Блоки

• uri – блок для парсинга url;
• history – блок, обеспечивающий взаимодействие с браузерным History API с помощью двух модификаторов:
• provider_history-api – если есть встроенная поддержка History API;
• provider_hashchange – реализация с помощью фолбэка hashchange;
• location – высокоуровневый блок для изменения window.location.

Схема работы

Использование

uri

modules.require(['uri'], function(Uri) {

    // Парсим url
    var u = Uri.parse('http://example.org:8080/path?test=1&test=2&param2=22');
    
    // Изменяем порт
    u.setPort(80);
    
    // Изменяем параметры запроса
    u.deleteParam('test', '2');
    u.replaceParam('param2', 2);
    
    // Обратно сериализуем url
    u.toString(); // "http://example.org:8080/path?test=1&param2=2"
    
});

history

modules.require(['history'], function(History) {

    // Создаем инстанс history
    var history = new History();

    // Добавляем запись или заменяем текущее состояние с помощью методов pushState/replaceState
    history.changeState('push', { title: 'Title', url: 'http://example.org:8080/path' });
    history.changeState('replace', { title: 'Title', url: 'http://example.org:8080/path?test=1' });
    
});

location

modules.require(['location'], function(location) {

    // Изменяем `window.location` с помощью полного url
    location.change({ url: 'http://example.org:8080/path' });

    // Изменяем текущий location, используя только новые параметры запроса
    location.change({ params: { param1: [11,12], param2: 'ololo' } });
    window.location.href; // "http://example.org:8080/path?param1=11&param1=12&param2=ololo"
    
});