10 вещей, которые надо знать при использовании jQuery в SharePoint

Для чего нужен jQuery в SharePoint? Обычно его используют для четырех целей:

Вызывать код JavaScript в момент загрузки страницы с помощью $(document).ready.
Использовать Ajax функции для доступа к данным на сервере.
Использовать готовые плагины,такие как tooltip или tabs, для того, чтобы расширить функционал сайта.
Проводить некоторые манипуляции с объектной модели документа (DOM).

Если Вы собираетесь использовать jQuery на страницах SharePoint, то вам нужно знать следующие вещи:

1. Используйте mQuery и RequestExecutor в простых случаях

Если у вас простой случай, то Вы можете использовать библиотеку mQuery для манипуляции DOM и RequestExecutor для ajax запросов. Кроме того, вместо Ajax запросов гораздо выгоднее использовать JSOM и TypeScript для клиентской разработки. Об этом я писал ранее.

Если Вы, все таки, решили использовать jQuery, то вам нужно помнить следующее:

2. jQuery(document).ready срабатывает не вовремя

Это происходит потому, что $(document).ready взрывается при событии DOMContentLoaded. А это события создано для тех случаев, когда весь контент страницы загружается с сервера. Оно происходит после того как браузер скачал всю страницу, связанные файлы и всё распарсил. SharePoint использует механизмы динамического формирования страницы, когда скрипты в теле страницы запускаются и формируют части страницы. В этом случае использовать DOMContentLoaded, отрабатывает до того как сформирована страница. Гораздо более надежный способ вызова после загрузки страницы – с помощью события body.onload. Для этого в SharePoint есть готовые функции.

3. Используйте _spBodyOnLoadFunctions или _spBodyOnLoadFunctionNames

Эти два массива (да-да, обычные JS массивы). _spBodyOnLoadFunctionNames содержит имена глобальных функций, которые необходимо вызвать на событие body.onload. _spBodyOnLoadFunctions содержит объекты-функции, что гораздо удобнее, но доступно только в SharePoint 2013. Кроме того есть переменная _spBodyOnLoadCalled, которая равна true, если функции уже были выполнены.

Пример:

(function() {
    if (!_spBodyOnLoadCalled) {
        _spBodyOnLoadFunctions.push(pageLoad);
    } else {
        pageLoad();
    }

    function pageLoad() {
        //onload code
    }
})();

4. Используйте RegisterModuleInit

Если у вас на сайте используется Minimal Download Strategy (MDS), то вам необходимо написать дополнительный код, чтобы вызывать функцию при каждой асинхронной загрузке страницы. MDS был создан для того, чтобы загружать не полностью страницу сервера, а только изменившуюся часть. В этом случае не происходит полная загрузка страницы и не вызывается событие body.onload. Для того, чтобы ваш код работал, вам необходимо вызвать функцию RegisterModuleInit, в которую передать имя скрипта и функцию, которая будет вызвана при асинхронной загрузке.

Пример кода загрузки с учетом

(function() {
    if (!_spBodyOnLoadCalled) {
        _spBodyOnLoadFunctions.push(pageLoad);
    } else {
        pageLoad();
    }

    function pageLoad() {
        //onload code
    }

    RegisterModuleInit(
        _spPageContextInfo.webServerRelativeUrl 
            + 'appname/script.js', 
        pageLoad);
})();

5. Для подключения jQuery используйте CustomAction ScriptLink

Не используйте другие способы, не трогайте masterpage, не создавайте ссылки в разметке. Чтобы поместить jQuery на все страницы сайта надо использовать следующий элемент в фиче:

<CustomAction 
    Location="ScriptLink" 
    ScriptSrc="~site/AppName/jquery.js" 
    Sequence="10001"/>

Этот код код добавляет ссылку на скрипт в тег head каждой страницы сайта. Он автоматически добавляет дополнительный параметр в url, который изменяется при изменении версии фичи.

Параметр Sequence позволяет управлять в каком порядке добавляются ссылки на скрипты.

Сам файл jQuery и скрипты размещайте в корне коллекции сайтов в папке с именем вашего приложения. И не забудьте включить BlobCache. Если Вы добавите такой элемент в фичу уровня Site, то jQuery будет добавлен также на все страницы всех подсайтов.

Но нужно помнить, что при подключении jQuery возникают проблемы:

6. jQuery ломает Asset Picker

Переменная $, определяемая в jQuery, конфликтует с именем переменной в диалоге выбора актива сайта (Asset Picker). В результате Asset Picker не работает после подключения jQuery.

7. jQuery в разных решениях будут конфликтовать друг с другом

Другая проблема, которая не просто часто, а постоянно встречается, заключается в том, что разные компоненты разных вендоров ставят jQuery. Это приводит к тому, что последняя версия перетирает все предыдущие.

Для этой и предыдущей проблемы есть решение:

8. Используйте jQuery.noConflict(true)

Эта функция делает две вещи:

Восстанавливает переменную $
При указании true в качестве параметра восстанавливает старое значение jQuery.

Сама функция возвращает текущий объект jQuery, который Вы можете сохранить в переменной.

9. Используйте IIFE

Для того, чтобы было удобно писать и копипастить из интернета код с jQuery удобно использовать Immediately-Invoked Function Expression (IIFE). По сути это объявление анонимной функции, совмещенное с вызовом. Выше я уже приводил пример кода с IIFE, но при использовании параметров можно сделать еще более удобный код:

window.myappName$ = window.myappName$ 
                    || jQuery.noConflict(true);

(function($) {
    if (!_spBodyOnLoadCalled) {
        _spBodyOnLoadFunctions.push(pageLoad);
    } else {
        pageLoad();
    }

    function pageLoad() {
        $('#pageTitle span').text('Hello from jQuery');
    }

    RegisterModuleInit(
            _spPageContextInfo.webServerRelativeUrl 
                + 'appname/script.js', 
            pageLoad);
})(window.myappName$);

Таким образом внутри вашего кода, Вы сможете использовать обычный jQuery код без извращений и конфликтов с другим решениями и частями SharePoint.

10. Используйте SPCop или R# c spcafcontrib

Последний совет - используйте инструменты SPCop\SPCAF и R# (ReSharper) с расширением SPCAFContrib.

Для SPCop\SPCAF расширение доступно на сайте http://spcafcontrib.codeplex.com/

Для R# плагин можно поставить из галереи расширений

Расширение содержит правила, которые находят неправильное использование jQuery в SharePoint проектах. В R# также есть возможность чинить неверный код автоматически (эта функциональность сейчас в процессе разработки).

Это расширение создается в основном Дмитрием Долотовских (страна должна знать своих героев), ему помогают Антон Вишняков, Алексей Большаков и я.