gandjustas' blog

Загрузка скриптов в SharePoint

July 29, 2014

В прошедшем недавно семинаре про клиентской разработке в SharePoint (записи – по ссылке) я показывал как сделать клиентский скрипт, который выполняет некоторый код после окончания загрузки страницы в SharePoint.

Эта, казалось бы, простая задача далеко не тривиально реализуется в SharePoint.

Причины

SharePoint формирует интерфейс динамически. Многие блоки добавляются на страницу по событию body.onload. Это событие возникает позже, чем DOMContentLoaded. Именно это событие перехватывает jQuery.ready. Поэтому использование jQuery часто не приводит к хорошему результату. Подробнее об использовании jQuery в SharePoint.
Minimal Download Strategy (MDS), появившийся в SharePoint 2013, загружает страницу один раз, потом обновляет блоки страницы, поэтому нужно выполнять дополнительные действия, чтобы скрипт выполнился после загрузки страницы под MDS.
Механизм загрузки скриптов, о котором я писал ранее, требует чтобы скрипт самостоятельно оповещал об окончании выполнения.

Для скриптов в виртуальной файловой системе SharePoint

Чаще всего скрипты SharePoint деплоятся как файлы в виртуальной файловой системе. Это прекрасно работает как в on premises, так и в online.

Для размещения скриптов на странице используется контрол ScriptLink, в таком виде:

<SharePoint:ScriptLink Name="autofill.js" runat="server" OnDemand="true" LoadAfterUI="true" Localizable="false" />

или с помощью CustomAction ScriptLink в элементе решения

<CustomAction Location="ScriptLink" ScriptSrc="~site/Extensions/typescripttemplates.js" />

Внутри скрипта нужно выполнить следующие действия:

Оповестить SharePoint об окончании загрузки.
Добавить функцию, которую необходимо вызывать после загрузки страницы, в массив _spBodyOnLoadFunctions.
Добавить зарегистрировать скрипт в системе MDS.

Код:

// IIFE для изоляции
(function () {
    "use strict";

    // Имя скрипта должно совпадать с тем, что указано в ScriptLink
    var scriptLink = "~site/Scripts/myscript.js";

    // Код здесь будет выполняться ДО окончания загрузки страницы


    if (_spBodyOnLoadCalled) {
        // Если событие body.onload уже обработано
        // напрмиер при LoadAfterUI="true" или OnDemand="true"
        // то сразу вызываем функцию init
        init();
    } else {
        // Иначе добавляем функцию в массив
        _spBodyOnLoadFunctions.push(init);
    }

    function init() {
        // заменяем токены "~site" и "~sitecollection" на реальные URL 
        // с помощьюв SPClientRenderer.ReplaceUrlTokens
        // но эта функция доступна после загрузки CSR
        // поэтому нужно выполнить зарузку CSR и дождаться её окончания
        // если CSR уже был загружен, то функция выполнится сразу
        SP.SOD.executeFunc("clientrenderer.js", "SPClientRenderer.ReplaceUrlTokens", function() {            
            // тепрь регистрируем скрипт в MDS
            RegisterModuleInit(SPClientRenderer.ReplaceUrlTokens(scriptLink), init);
        });

        // Код здесь будет выполняться ПОСЛЕ окончания загрузки страницы
    }


    SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs(scriptLink);
})();

Если вы сами деплоите страницу, на которой будет работать ваш скрипт, то можете воспользоваться библиотекой mQuery и функцией m$.ready. Эта функция делает тоже самое, что и блок if\else в коде выше.

Для скриптов в layouts

Если вы размещаете свой скрипт в _layouts, то есть несколько особенностей:

При добавлении скрипта надо указывать только имя файла.
SOD автоматически регистрирует в MDS вызов функции с именем $_global_имя_файла_без_js

Код для файла в _layouts

"use strict";

// эта функция должна быть в глобальном пространстве имен
function $_global_myscript() {
    // Код здесь будет выполняться ПОСЛЕ окончания загрузки страницы
}


if (_spBodyOnLoadCalled) {
    // Если событие body.onload уже обработано
    // напрмиер при LoadAfterUI="true" или OnDemand="true"
    // то сразу вызываем функцию init
    init();
} else {
    // Иначе добавляем функцию в массив
    _spBodyOnLoadFunctions.push(init);
}

// этот вызов автоматически добавит регистрацию в MDS
SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("myscript.js");

Универсальные скрипты

Если ваши скрипты будут вызываться вне страниц SharePoint, то обращение к “пространству имен” SP вызовет ошибку. Кроме того есть свой механизм оповещения о загрузке скриптов в MsAjax библиотеке, поэтому в конце скрипта надо использовать такой блок:

// Оповестить MsAjax об окончании загрузки
if (typeof Sys != "undefined" && Sys && Sys.Application) {
    Sys.Application.notifyScriptLoaded();
}

// Оповестить SharePoint об окончании загрузки
if (typeof SP != "undefined" && SP && SP.SOD) {
    SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("myscript.js");
}

Заключение

Более подробно о загрузке скриптов, TypeScript, особенностях SharePoint и Client Side Rendering можете узнать подробнее, посмотрев записи семинара - http://blog.gandjustas.ru/shop/spclient/

Я выступаю на DevCon 2014

May 23, 2014

Немного запоздалый, но все же анонс.

28 и 29 мая я буду выступать на конференции DevCon 2014. В этот раз у меня целых два доклада. Первый (28 мая в 17:10) на тему новых возможностей BI в SharePoint 2013, где я буду рассказывать рол PowerPivot и PowerView. Второй доклад (29 мая в 10.30) про BI в облаках с применением PowerBI и Office 365.

Приходите на доклады, кто будет присутствовать на конференции или смотрите трансляцию.

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

May 20, 2014

Для чего нужен 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# также есть возможность чинить неверный код автоматически (эта функциональность сейчас в процессе разработки).

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

Видеозаписи докладов с ноябрьской встречи RUSUG

April 23, 2014

Внезапно у меня оказались записи докладов со встречи, которая проходила 25 ноября 2013 года.

Доклад Михаила Бондаревского.

Доклад Сергея Слукина.

Office 365 Day

April 3, 2014

17 апреля 2014 года состоится мини-конференция Office 365 Day в Microsoft Technology Center на Белорусской.

Раньше встречи были посвящены в основном SharePoint, теперь расширяем формат. Office 365 это не только SharePoint, но и Lync, Exchange, Yammer, Office, Project, Dynamics CRM, облачные технологии и гибридные архитектуры.

В программе два потока: технологический и бизнес-ориентированный.
Предварительный перечень докладов:

Создание веб-сайта на базе Sharepoint Online - Виталий Жуков
Создание корпоративного портала в Office 365 – Сергей Слукин
Стратегия миграции внутренних решений в Office 356 – Александр Романов
Новые API и возможности приложений Office – Михаил Бондаревский
Облачный инструмент совместной работы – Yammer. Кто здесь? – Роман Марусяк
Гибридные среды. Выгоды и проблемы – Станислав Выщепан

Финальная программа будет опубликована позднее, следите за обновлениями.

Регистрация на мероприятие обязательна, регистрироваться по ссылке -http://o365day.timepad.ru/event/116000/

До встречи.

Стас Выщепан

Автор, спикер, консультант, основатель и руководитель vnextsoft.

Моя компания

Подписаться на блог

RSS