3 простых способа подружить KnockoutJs и SharePoint

Попал на старый проект, SharePoint 2010. Бывает, что тут сделаешь! Спасаюсь от скуки только благодаря KnockoutJs :) Всвязи с чем - этот пост.

KnockoutJs как MVVM фреймворк на самом деле ничем не уступает тому же Angular'у. Единственная вещь, которую нужно очень хорошо изучить и вызубрить в Knockout - это когда скобки () нужны, а когда нет, и как этот ko observable wrapping вообще работает. Преодолев этот порог, больше с Knockout проблем не возникает. Angular конечно помощнее, более фундаментальный, но и всякой магии в нем намного больше, траблшутить крайне сложно, и модель освоения Angular действительно вот такая (проверено на собственном опыте):

Так что, в своих SharePoint-проектах я преимущественно использую именно Knockout. И в этом посте я опишу три простых техники использования Knockout совместно с SharePoint.

CamlJs 2.0

В предыдущем посте я писал немного о том, как мне удалось улучшить условия разработки CamlJs: про внутренний переход на TypeScript, введение юнит-тестов и визуального diff'а. Благодаря этим внутренним усовершенствованиям, мне удалось быстро привести проект в порядок, добавить в него существенные улучшения и выпустить релиз 2.0, который выходит сегодня, ура! :)

В этом посте я расскажу, что это за улучшения и как CamlJs может облегчить запросы к спискам в ваших проектах.

Зачем нужен CamlJs

Итак, проект CamlJs позволяет формировать строку Caml Query на стороне клиента (в JavaScript) для использования совместно с SP.CamlQuery или SPServices. CamlJs привносит следующие основные преимущества перед использованием просто строк с XML:

1. Читаемость. Захардкоженный XML в коде выглядит жутковато и громоздко, запросы написанные на CamlJs читать намного проще и они гораздо компактнее.
   
   
   
   
2. Защита от опечаток. XML - это по сути "magic string", в котором очень легко сделать опечатку. SharePoint в этом случае возвращает, как водится, совершенно безумные, вводящие в заблуждение сообщения об ошибках. Чтобы понять, что на самом деле ты где-то просто забыл закрывающую кавычку или что-то в этом духе, приходится тратить кучу времени...
3. Intellisense. CamlJs дает intellisense и inline подсказки, благодаря чему даже люди, не в совершенстве знающие CAML Query, могут составлять сложные запросы без ошибок.
4. Обработка SharePoint-овских "багофич". Например, многие ли из вас знают, что при попытке применить условие <Includes> для MultiLookup полей указывающих на поле типа DateTime SharePoint вернет ошибку? :) А CamlJs знает это - и еще кучу тонкостей, которые я собрал за долгие годы работы с CAML Query...

Что нового в версии 2.0

Версия 2.0 существенно улучшена по сравнению с 1.0. При этом, синтаксически версии оставлены максимально совместимыми.

1. Поддержка скобочных выражений и генерации частей запросов. CamlJs 1.0 не поддерживал возможности создания скобочных выражений. Все операции в запросах генерились строго в порядке справа налево, и более-менее сложную логику с множеством вложенных Or и And реализовать было, к сожалению, невозможно :( Теперь это исправлено за счет введения операторов All и Any.
2. Значительно улучшен Intellisense. Теперь набор возможных сравнений для поля зависит от типа этого поля, т.е. например к полям Integer нельзя применить сравнение Contains и т.д.
3. Изменена обработка Lookup-полей. Теперь элемент LookupField поддерживает методы Id() и ValueAs<type>(), которые уже в свою очередь возвращают корректный набор операций. Например, если у вас есть Lookup-поле "City", которое ссылается на текстовое поле "Title" в таблице "Cities", то чтобы получить все записи у которых город начинается на "М", надо использовать запрос LookupField("City").ValueAsText().BeginsWith("M").
4. Улучшен элемент UserField. Помимо изменений связанных с изменениями Lookup-полей (а User-поле это как известно частный случай Lookup-а), функционал элемента Membership теперь реализуется несколькими функциями элемента UserField. Кроме того, для удобства, была добавлен метод "EqualToCurrentUser()", который функционально эквивалентен конструкции "EqualTo(CamlBuilder.CamlValues.UserId)".
5. Улучшен элемент DateRangesOverlap. К сожалению, выяснилось что этот элемент невозможно использовать вместе с SP.CamlQuery, поскольку CSOM игнорирует тэг QueryOptions, а для DateRangesOverlap нужно задавать QueryOptions/CalendarDate и QueryOptions/ExpandRecurrence. Однако, остается возможность использовать DateRangesOverlap хотя бы вместе с SPServices.
6. Добавлен новый элемент BooleanField для полей типа Boolean.
7. Добавлен новый элемент UrlField для полей типа URL.
8. DateField и DateTimeField теперь конвертируют дату (Date) к правильному формату.

Также, проект теперь написан на TypeScript и покрыт юнит-тестами, благодаря чему можно гарантировать повышенные стабильность и правильность работы.

Наконец, проект теперь доступен через Nuget (добавляет camljs.js в папку Scripts вашего проекта):

PM> Install-Package CamlJs
Определения для TypeScript также доступны через Nuget:

PM> Install-Package camljs.TypeScript.DefinitelyTyped

Миграция с версии 1.0 на 2.0

Логика работы системы осталась в основном прежней, никакие старые элементы не были удалены или переименованы, поэтому как правило, миграция НЕ требуется. Однако, т.к. синтаксис стал немного более строгим, возможно потребуется что-то подкорректировать. Если у вас возникли проблемы с запросами из версии 1.0, смело пишите в комментарии, решим.

Также, обратите пожалуйста внимание на то, что элементы Membership и LookupIdField теперь помечены как "deprecated" и будут убраны в следующем большом релизе. Рекомендуется переписать запросы с их использованием на эквивалентные конструкции LookupField("...").Id() и UserField("...").IsInCurrentUserGroups() и т.д.

Заключение

В SharePoint 2013 роль JavaScript неимоверно возросла. Появилась необходимость создания комплексных JavaScript-решений, работающих полностью на стороне клиента. В этих условиях, приобретают повышенное значение всевозможные инструменты и расширения для клиентских операций, в том числе и разрабатываемый мною opensource-проект CamlJs.

Надеюсь, CamlJs поможет вам улучшить ваши JavaScript-решения и упростить реализацию задач, связанных с генерацией сложных запросов к спискам. Удачи!

Рабочие процессы SharePoint 2013: Workflow Services API в примерах

В предыдущем посте я очень кратко (но ёмко) прошелся по Workflow в SharePoint 2013. Сегодня хочу продолжить тему и рассказать о новом клиентском API под названием Workflow Services (и показать, как его можно использовать), которое доступно в том числе из SharePoint JavaScript Object Model.

Wait/loading диалоги в SharePoint

Пара недокументированных стандартных диалогов. Сделаны по тому же принципу, что я описывал для Confirmation-диалогов, но уже входят в состав SharePoint - что приятно :) Возможно, пригодятся.

Буду краток:

Этот диалог выводится следующим куском JS:

var dialog = SP.UI.ModalDialog.showWaitScreenWithNoClose("test", "test message", 190, 350)
// делаем что-нибудь асинхронное и долгое
// по завершении, вызываем
dialog.close(SP.UI.DialogResult.OK);

Можно использовать для каких-нибудь долгих асинхронных операций.

Если вы хотите дать пользователю возможность отменить вашу операцию (что желательно), используйте другой метод:

var dialog = SP.UI.ModalDialog.showWaitScreenSize("test", "test message", function (dialogResult) { alert(dialogResult); }, 150, 350);

Вы автоматически получите кнопку "Отмена" и при ее нажатии, сработает callback (dialogResult будет равен 0, т.е. SP.UI.DialogResult.cancel).

К слову, в клиентской объектной модели и SP.UI в SharePoint 2013 добавилось очень много всего недокументированного (те же callback'и чего стоят, или SP.Taxonomy). Надеюсь, задокументируют позже - все-таки лазать в сгенерированных Script#-ом исходных кодах SharePoint JavaScript API, где все локальные переменные заобфусцированы - то еще удовольствие :(

Видео доклада SharePoint Ribbon и Office 365

Видеозапись моего доклада с SharePoint Conference Russia наконец-то опубликована (как, впрочем, и видеозаписи докладов всех других участников)!

Те, кто еще не смотрел, могут посмотреть.

Работа с XML в SharePoint из Javascript

SharePoint очень тесно связан с XML. Все эти схемы полей и списков, определения элементов Ribbon, SharePoint Batch API, запросы SPQuery/CamlQuery - и многое другое. И если на стороне сервера всё более-менее понятно, там есть XmlReader/XmlWriter, XmlSerializer, XDocument и т.д., то что делать на стороне клиента?

Как обрабатывать XML, формировать или изменять его, и какие для этого есть функции в SharePoint EcmaScript  - всю эту информацию я постарался собрать в сегодняшней статье.