FRONTEND - CO I JAK?

Z CZEGO KORZYSTAMY?

• Vanilla JS + jQuery, czysty CSS oraz komponenty Kendo.
  • Kendo w wersji jQuery i .NetCore.
  • Przykłady w systemie: grid, dropdown, date picker, chart, tab, wizard, upload.
  • Przykładowa stronka w dokumentacji: https://demos.telerik.com/aspnet-core/grid i https://docs.telerik.com/kendo-ui/api/javascript/ui/grid
  • Tunningowanie pod specjalne potrzeby: extension (gdy coś się powtarza dla np. wielu gridów jak BoundEnumBadge) i ClientTemplate (gdy coś jest specyficzne dla danego grida np. Count w Segmentach). Komponenty kendo prawie zawsze stylujemy po naszemu nadpisując domyślne style kendo.
• Gdy zachodzi potrzeba to korzystamy z zewnętrznych bibliotek js'owych - ale to zazwyczaj jest poprzedzone researchem i ustaleniami z PM (jeśli bilbioteka jest płatna). Przykład to biblioteka goJS, która służy do budowania scenariuszów lub unlayer - edytor HTML w formie drag&drop.
  
  

FIGMA

• Służy do projektowania UI, który potem musimy zakodować w ramach taska.
• Linki do desingu podpięte do taska np. https://www.figma.com/design/KPdRkTslmxGXzL0VyhGeY2/Settings--?node-id=9763-155019&t=rzeTK3we3eYHnfU7-0
• Korzystamy ze wspólnego konta, aby móc korzystać z trybu DEV mode.
• DEV mode trzeba włączyć za pomocą toggle (na dole strony), aby np. móc badać style i odległości między elementami mockupu.
• Zaznaczamy interesujący nas element na mockupie i po prawej stronie w zakładce Properties widzimy style (wielkości i rodzaje czcionek, kolory, paddingi, marginy, radiusy itd.)
• Odległości pomiędzy elementami można sprawdzać zaznaczając jeden z interesujących nas elementów mockupa i najeżdżając kursorem na drugi, w tym momencie powinna pokazać się odległość w pikselach.
• Starajmy się wykorzystywać komponenty i style o ile już istnieją (buttony, okienka, gridy, tytuły, inputy itd.) szukając w kodzie, czy coś podobnego już istnieje i ma swoją klasę css, którą można użyć zamiast tworzyć nową (najczęściej znajdziemy je w pliku site.css w projekcie Web.Common, ale istnieją też inne jak np. grid.css.
  Zalecane jest znalezienie podobnego przypadku użycia w systemie, i sprawdzenie jak to jest robione, aby używać już istniejących klas, komponentów i nie powtarzać kodu, który jest już napisany.
• Nowe ikony pobieramy bezpośrednio z Figmy. Patrz niżej.

IKONY

• Te które są już dodane możemy podejrzeć w pliku w solucji C:\VSO\ECDP_GIT\Dev\Src\ExpertSender.Cdp.Web.Client\wwwroot\streamline\demo.html
  lub https://client.dev.ecdp/streamline/demo.html
• Ten plik odpalony w przeglądarce może służyć jako wyszukiwarka istniejących ikon. Nazwa ikony w figmie najczęściej powinna być zbliżona do tej w pliku demo i można szukać po słowach kluczowych, czy ikona którą potrzebujemy już jest dodana czy musimy ją dodać.
• Gdy ikona nie istnieje to pobieramy ją z Figmy jako svg i dodajemy do projektów Web.Administration i Web.Client według instrukcji.
• WAŻNE jest trzymanie się wytycznych z instrukcji, aby utrzymać porządek w ikonach.
  INSTRUKCJA: https://3xr.sharepoint.com/devel/wiki/Ikony%20w%20ECDP.aspx

OGÓLNE ZASADY

• Kolory, z-indexy, shadows trzymamy w zmiennych w pliku variable.css.
  Nie wrzucamy luzem kolorów w stylach. Zawsze staramy się korzystać z pliku variable.css.

• Style i skrypty:

  • Jeśli jest ich mało i dotyczą jednej konkretnej rzeczy to zazwyczaj wstawiamy w tym samym pliku co HTML danego widoku.
  • Jeśli dotyczą konkretnej części systemu jak np. segmentacja, ale jest ich dużo to tworzymy oddzielny plik(i) w folderze wwwroot.
  • Jeśli style są ogólne dla całego systemu to albo w site.css w web.common albo nowy plik w commonie jak np. grid.css ze stylami dla wszystkich gridów. Analogicznie skrypty dzielone przez cały system to np. plik site.js w Web.Common albo kendoNotification.js, itd.
  • Staramy się umieszczać funkcje w namespace sugerującym do jakiego feature'a należą, zamiast definiować je globalnie, np:
    
    

• Minifikacja - pliki js i css, które wrzucamy do wwwroot, zostaną automatycznie zminifikowane na środowiskach innych niż DEV oraz zlepione w jeden plik, który jest ładowany na wszystkich stronach.

Dlatego gdy wyodrębniamy oddzielny plik css i js, który jest specyficzny dla jakiegoś miejsca w systemie i nie chcemy żeby ładował się niepotrzebnie na wszystkich stronach, to należy to skonfigurować w Startup.cs.

Konfiguracja minifikacji i boundlingu na przykładzie projektu Web.Client znajduje się w Startup.cs w app.UseSmidge(…).

Przykład konfiguracji:



Przykład ładowania pliku w ramach widoku (oddzielna wersja dla środowiska DEV i pozostałych środowisk:

• libman.json - plik do pobierania bibliotek z cdn.

https://learn.microsoft.com/en-us/aspnet/core/client-side/libman/libman-vs?view=aspnetcore-9.0#use-the-add-client-side-library-dialog

• sitemap.json - do budowania nawigacji i menu aplikacji. Tzn. dodajemy tam nowe endpointy, które pojawią się w menu i wskakzujemy ich nazwę, ikonę, controller, metodę. Można też podać dozwolone role usera lub settingi, które mówią czy feature jest dostępny czy nie.

• Editor templates
  jest to gotowy zestaw HTML, JS dla pól w view modelach np. C:\VSO\ECDP_GIT\Dev\Dev\Src\ExpertSender.Cdp.Web.Common\Views\Shared\EditorTemplates\EsDropDown.cshtml
  
  Wystarczy w viewmodelu wskazać dla pola [UIHint="NazwaEditorTemplate"] aby zostało owinięte w odpowiedni HTML, js, css.

Warto zaglądać w pliki EditorTemplates, aby zobaczyć jakie funkcje już obsługują i na co pozwalają, bo czasami pozwalają przekazywać dodatkowe ustawienia.

Przykład użycia w viewmodelu:

W pliku EsDropdown.cshtml widać, że pozwala na dodatkowe opcjonalne konfiguracje m.in. CreateFunction - do tworzenia nowego obiektu w ramach listy, IsDescribed - do pobrania i wyświetlenia opisu elementu listy, itd. EsDropdown dodatkowo zawsze wymaga podania dodatkowego pola o takiej samej nazwie jak główne pole ale z suffixem „Options". Pole to musi zawierać listę elementów wyświetlanych w dropdownie, a główne pole wskazuje wartość zaznaczonego elementu:

• Layouty dla stron C:\VSO\ECDP_GIT\Dev\Dev\Src\ExpertSender.Cdp.Web.Client\Features\Shared\Authorized\

Domyślny _BasicLayout.cshtml.

• Layout to główny szablon widoku. Zawiera podstawowy HTML (menu, header, miejsce na główny content) oraz ładuje podstawowe pliki CSS - _Head.cshtml i JS - _Scripts.cshtml.

• Darkmode - dodanie klasy .darkmode w dowolnym elemencie HTML, który ma być w ciemnej stylistyce. Nie wszystko jest ostylowane w darkmodzie, więc ewentualne braki trzeba stylować na bieżąco w zależności od potrzeb.

• DRY! Generalnie gdy wiemy, że coś może zostać potem ponownie użyte w systemie albo już jest użyte w systemie to staramy się robić tak, aby było reużywalne - style, skrypty, partial views, KendoExtensions.cs (do rozszerzania funkcjonalności komponentów kendo), EditorTemplates (do pól view modeli), TagHelpers itd.

Przykład reużywalnej funkcjonalności - Templates. Szablony są używane przez wiele wizardów (email, popup, banner, forms). Mamy partial _TemplateMenuAndViews.cshtml, który gdy wstrzykujemy do jakiegoś widoku to podajemy mu w modelu specyficzne pola:

Dzięki temu wszystko może być generowane pod wybrany wizard.