SharePoint Online Hosted App + Angular

Kamil Warowny

SharePoint Online Hosted App + Angular
Listopad 30, 2017 Katarzyna Sobczak

SharePoint Online Hosted App + Angular

Artykuł przedstawia sposób wykonania dodatku (Add-In) dla SharePoint Online lub 2016 w połączeniu z Angular

Wprowadzenie

Jak wspomniałem w poprzednim artykule, od wielu lat firmy posiadające w swojej infrastrukturze Microsoft SharePoint Server lub posiadające licencje SharePoint Online rozbudowują jego możliwości poprzez budowanie własnych dodatków. Od wersji SharePoint 2013 promowane są aplikacje w technologii SharePoint Hosted App i Provider Hosted App. Aplikacje SharePoint Hosted znajdują się na serwerze SharePoint, ale cała ich logika wykonywana jest w przeglądarce po stronie klienta (lub w zewnętrznych usługach REST). Provider Hosted App przechowywane są na zewnętrznych serwerach, np. Windows z IIS i ich logika wykonuje się na tych serwerach lub częściowo po stronie klienta.

W niniejszym artykule postaram się pokazać, jak stworzyć aplikację SharePoint Hosted w połączeniu z Angular. Angular pozwala na budowanie zaawansowanych aplikacji mobilnych pisanych w TypeScript, dzięki czemu programiści, którzy wcześniej tworzyli projekty Farm Solution w C#, łatwiej zapoznają się z nową technologią.

Angular

Niniejszy artykuł nie mam na celu zapoznania czytelnika z technologią Angular. Zainteresowanych podstawową wiedzą odsyłam do artykułów Bartosza Szewczykadokumentacji Angular oraz wyszukiwarki Google.

SharePoint Hosted App

Dodatki SharePoint Hosted App są jednymi z promowanych rozwiązań przeznaczonych do tworzenia nowych funkcjonalności na platformę SharePoint 2013/2016 i SharePoint Online. Nie mogą zawierać kodu wykonywanego po stronie serwera, jak jest to w przypadku Farm Solutions. Cała logika musi opierać się o operacje wykonywane po stronie klienta (przeglądarka internetowa) lub być umieszczona w zewnętrznych usługach typu REST. Takie podejście gwarantuje, iż wykonywany kod nie spowoduje awarii serwerów SharePoint czy ich nadmiernego obciążenia. Z drugiej strony, dodatki są ograniczone funkcjonalnie przez możliwości Java Scriptu oraz fakt, że nie zawsze jest możliwość użycia dodatkowych serwisów REST na potrzeby pisanego rozwiązania. Korzystając z wbudowanych serwisów REST, dostępnych w ramach SharePoint, również możemy trafić na różnego rodzaju ograniczenia.

Środowisko Deweloperskie

W celu utworzenia projektu musimy posiadać maszynę deweloperską z zainstalowanym SharePoint Server (np. 2013/2016) oraz Visual studio (np. 2015). Do prac deweloperskich można także wykorzystać SharePoint Online.

Osobiście preferuję SP Online, gdyż nie wymaga skomplikowanej konfiguracji, jak to ma miejsce w przypadku SharePoint Server. Należy jedynie zezwolić na wgrywanie rozwiązań z VS korzystając ze skryptu PowerShell.

Projekt

W VS klikamy „New Project”, a następnie wybieramy typ projektu „SharePoint Add-In”, podajemy nazwę i klikamy przycisk „OK”.

SharePoint Add-in

Na kolejnym ekranie podajemy URL witryny przeznaczonej na dewelopowanie aplikacji, wybieramy typ aplikacji i klikamy „Next”.

SharePoint hosted

Kolejny ekran poprosi nas o zalogowanie się do SharePoint. Po poprawnym zalogowaniu wskazujemy SharePoint, dla którego tworzymy rozwiązanie. Wskazujemy wersję i klikamy przycisk „Finish”.

SharePoint Online

VS po chwili wygeneruje aplikację. Możemy ją uruchomić klikając F5 na klawiaturze.

SharePoint Angular

Nie jestem fanem domyślnego szablonu aplikacji, ale dzięki doświadczeniu i współpracy z grafikami udało nam się stworzyć powtarzalny i przede wszystkim przyjemny dla oka, własny szablon aplikacji.

Na witrynie, na której wgrana została aplikacja, pojawi się nowy link pozwalający na jej uruchomienie.

SharePoint Angular

Kolejnym wymaganym krokiem do utworzenia naszego rozwiązania jest dodanie modułu. Na nazwie projektu klikamy PPM i wybieramy opcję „Add” > „New Item”. Wybieramy „Module”, podajemy nazwę i klikamy przycisk „Add”.

Module

Angular

Uruchamiamy PowerShell. Przechodzimy do folderu naszego modułu AngularApp.

moduł AngularApp.

Generujemy aplikację wydając kolejno polecenia:

  • npm install -g @angular/cli
  • ng new SharePoint-Angular4

Wykonujemy kolejne dwa, aby zobaczyć czy instalacja wykonała się poprawnie:

  • cd SharePoint-Angular4
  • npm run build –prod

Jeśli otrzymamy efekt jak poniżej, oznacza to, że wszystko działa właściwie:

cd SharePoint-Angular4

Przechodzimy do VS. W solution explorer włączamy pokazywanie wszystkich plików.

pokazywanie wszystkich plików

W module „AngularApp” rozwijamy folder „SharePoint-Angular4” i zaznaczamy w nim wszystkie pliki/foldery poza node_modules. Klikamy PPM i wybieramy opcję „Include in project”.

SharePoint-Angular4

Kolejnym krokiem jest delikatna modyfikacja pliku Element.xml, gdyż nie wszystkie pliki w module powinny trafić na serwer podczas wgrywania paczki. Zmieniamy plik zgodnie z przykładem. Zmiana polega na wycięciu linii <File>, które nie dotyczą plików z folderu „dist”:

modyfikacja pliku Element.xml

Następnie otwieramy plik /Pages/Default.aspx

W górnej części pliku należy dodać deklarację przestrzeni nazw SharePoint:

deklaracja przestrzeni nazw SharePoint

Poniżej zastępujemy sekcję PlaceHolderMain jak na rysunku:

zastępienie sekcji PlaceHolderMain

Dla wyjaśnienia: SRC to nasza ścieżka w module.

Angular App

Naciskamy F5 na klawiaturze i po chwili naszym oczom powinna ukazać się stworzona aplikacja.

aplikacja angular

SharePoint REST

Do komunikacji z SharePoint w przypadku tworzenia aplikacji SharePoint Hosted należy skorzystać z serwisów REST lub JavaScript object model (JSOM).

Chcąc przesyłąć dane poprzez serwisy REST wykorzystujemy typowe zapytania GET czy POST. Dokumentację i przykłady użycia serwisów znajdziemy bez większego problemu w popularnych wyszukiwarkach oraz oficjalniej dokumentacji (zob. REST API reference and samples Get to know the SharePoint REST service).

Znaczna cześć przykładów dla SP 2013 jest poprawna dla SP 2016 i SPO.

Niektóre operacje nie zostały jednak zaimplementowane jako REST. Cześć z nich dostępna jest poprzez JSOM. Są to specjalistyczne biblioteki JS, przygotowane do komunikacji z SharePoint. Przykłady użycia także są bezproblemowo dostępne w Internecie (zob. Complete basic operations using JavaScript library code in SharePoint).

Przykład oparty o SPFX i TS. Łatwo go dostosować do SP Hosted Add-in z Angular (zob. Connect to SharePoint using the JavaScript Object Model (JSOM)).

Przejdźmy do przykładu.

Otwórzmy plik app.component.ts i zmieńmy go zgodnie z rysunkiem:

plik app.component.ts
plik app.component.ts

Zmiany w pliku: app.component.html (pierwszy div bez zmian)

Zmiany w pliku: app.component.html

Zmiany w pliku app.module.ts

Zmiany w pliku app.module.ts

Po wprowadzeniu zmian kompilujemy aplikację Angular poleceniem:

  • npm run build –prod

Jeśli kompilacja przebiegnie pomyślnie, w konsoli uzyskamy wynik podobny do poniższego:

polecenie npm run build –prod

Pozostaje jeszcze nadanie naszej aplikacji uprawnień do odczytu danych z witryny host. W tym celu otwieramy plik AppManifest.xml i w zakładce Permissions ustawiamy uprawnienia jak na rysunku:

plik AppManifest.xml

Teraz już można nacisnąć F5 i po chwili nasza aplikacja uruchomi się w przeglądarce:

Angular4 app

Cel osiągnięty.

Fast Deploy to SP App

Każde naciśnięcie F5 powoduje usunięcie aplikacji z witryny SP i wgranie jej ponownie, co nie jest zbyt szybkim rozwiązaniem. W sytuacji, gdy zmiany wprowadzamy tylko w plikach aplikacji angular można ułatwić sobie prace deweloperskie korzystając z dodatku do VS.

Po przebudowaniu aplikacji angular w PowerShell wystarczy tylko przejść w VS do folderu „dist”, zaznaczyć pliki js i map, kliknąć PPM i wybrać opcję „Fast deploy”. Po chwili pliki są już na serwerze i możemy testować.

SP App

Jeśli mimo wgania plików aplikacja nie działa poprawnie proszę pamiętać, że pliki JS mogą być buforowane przez przeglądarkę, więc trzeba wyczyścić cache.

Przy pierwszej próbie użycia Fast Deploy zostaniemy zapytani o podanie użytkownika i hasła. Podany użytkownik musi być administratorem witryny, na której znajduje się wgrana aplikacja.

Podsumowanie

Budując aplikacje w modelu SharePoint Hosted możemy uzyskać ciekawe dodatki SharePoint. Pomocą służą nam gotowe frameworki, jak Angular, Bootstrap, Office Fabric UI. Wspólnie pozwalają szybko tworzyć efektywne i „miłe dla oka” rozwiązania, pracujące wyłącznie po stronie klienta, a zarazem komunikujące się z SharePoint poprzez usługi REST. W momencie tworzenia tego artykułu model SharePoint Hosted jest jednym z zalecanych sposobów pisania aplikacji dla SharePoint. Innymi są wspomniany Provider Hosted oraz SPFX, o którym również można przeczytać na naszym blogu.

Cały projekt jest do pobrania tutaj:GITHUB

Podziel się

Autor: Kamil Warowny

Kamil Warowny

Kamil Warowny

Zespół: Apps

Ostatnie artykuły autora

SharePoint Online + Azure Free, Część 2: Zdarzenia dodania i edycji elementu listy bądź dokumentu

SharePoint Online + Azure Free, Część 2: Zdarzenia dodania i edycji elementu listy bądź dokumentu

W artykule przedstawiono możliwość wykorzystania bezpłatnych funkcjonalności Azure Functions w połączeniu z SharePoint Online celem automatycznych reakcji na dodanie lub edycję elementu listy lub dokumentu w witrynie SharePoint.

SharePoint Online + Azure Free, Cześć 1: Cykliczne przetwarzanie danych

SharePoint Online + Azure Free, Cześć 1: Cykliczne przetwarzanie danych

Niniejszy artykuł przedstawia możliwość wykorzystania bezpłatnych funkcjonalności Azure w połączeniu z SharePoint Online celem automatyzacji przetwarzania cyklicznego danych zamieszczonych w witrynie SharePoint.

SharePoint 2016 Farm Solutions + Angular

SharePoint 2016 Farm Solutions + Angular

Artykuł przedstawia sposób wykonania dodatku SharePoint 2016 Farm Solution w połączeniu z Angular.

Skontaktuj się z Kamilem

 

Administratorem danych gromadzonych z wykorzystaniem formularza jest A.P.N. Promise S.A. Podane przez Ciebie dane będą przetwarzane w zakresie niezbędnym do podjęcia kontaktu lub realizacji określonego żądania zgodnie z art. 6 ust. 1 lit. b RODO przez okres niezbędny dla realizacji Twojego zgłoszenia. Wszelkie informacje w zakresie przetwarzania podanych przez Ciebie w formularzu danych oraz posiadanych uprawnieniach znajdziesz w Polityce prywatności. Kliknij i dowiedz się więcej jeżeli informacje podane powyżej nie są dostatecznie jasne!