= Szablony = eDokumenty umożliwiają obsługę szablonów pism. Procedura ich tworzenia jest prosta, a sam system zawiera kilka predefiniowanych szablonów. Szablony dostępne są w każdym miejscu w systemie, w którym możemy stworzyć nowy dokument z menu Nowy / Utwórz z szablonu -> wybór właściwego szablonu. Praca z szablonami, zarządzanie nimi oraz sposób ich tworzenia opisana jest w sekcji dotyczącej [wiki:UserGuide/BasicConfiguration/CompanyTemplateDocument szablonu pisma firmowego]. == Wykorzystanie znaczników w tworzeniu szablonów == W procesie tworzenia szablonów bardzo przydatna jest możliwość wykorzystania znaczników, które to podczas generowania dokumentu z szablonu są zamieniane na właściwe dane zarejestrowane w systemie. System zawiera szereg predefiniowanych znaczników. Ich lista widoczna jest w oknie dostępnym ze ścieżki ''Ustawienia / Panel sterowania/ Szablony dokumentów/'' zakładka ''Import znaczników'' [[Image(szablony_dokumentów.png)]][[br]]''Rys. 1'' Znaczniki, które uznamy za użyteczne w tworzeniu szablonów należy przenieść do zakładki ''Znaczniki szablonów'' poprzez ich zaznaczenie i użycie przycisku ''Zaimportuj znacznik''. Wstawienie wybranego znacznika do dokumentu należy wykonać za pomocą metody: - wpisz nazwę lub kopiuj&wklej do Word znacznik np. DATA.DZISIAJ - dodaj znaki # na początku i końcu - zaznacz cały utworzony w ten sposób znacznik, wytnij (Ctrl-X) - wklej używając funkcji "Wklej specjalnie" > "Tekst niesformatowany" - w razie potrzeby dopiero wtedy cały zaznaczony znacznik sformatuj np. dodaj pogrubienie Przykład wykorzystania znaczników : {{{ Nowe Miasto, dnia: #DATA.DZISIAJ# Znak sprawy: #SPRAWA.SYMBOL# Demo Sp. z o.o. Ul. Turinga 386 01-024 Nowe Miasto #KONTAKT.NAZWA_I_ADRES=bloczek# Wezwanie do zapłaty Wzywam #KONTAKT.NAZWA# do uregulowania zaległej płatności …. Z poważaniem #PISMO.NADAWCA# }}} == Tworzenie własnych znaczników == W przypadku, gdy zdefiniowane w systemie znaczniki, nie wyczerpują potrzeb klienta w tym temacie, istnieje możliwość stworzenia znaczników dodatkowych. W tym celu należy wybrać opcje ''Nowy znacznik'' z zakładki ''Znaczniki szablonów'' na oknie ''Szablony dokumentów''. [[Image(znaczniki_szablonow.png)]][[br]]''Rys. 4'' Znaczniki mogą być tworzone metodami: * z pomocnikiem * z tabeli * jako cecha * jako SQL === Znacznik z tabeli === Format takiego znacznika to #NAZWA_TABELI.NAZWA_POLA#. W oknie definicji takiego znacznika mamy do dyspozycji następujące pola: * ''Znacznik'' - powinno określać definicje znacznika z uwzględnieniem zasad - kolejne człony nazwy oddzielamy kropką i wszystko piszemy z dużą literą[[BR]] * ''Opis'' - określa opisową definicje znacznika[[BR]] * ''Tabela'' - określa tabelę bazy, z której będą pobierane dane przy tworzeniu dokumentu[[BR]] * ''Klucz główny'' - odnosi się do nazwy klucza głównego z tabeli, na którą wskazuje pole ''Tabela''. Jeśli pole tabela wskazuje na widok należy wskazać klucz główny w tym widoku[[BR]] * ''Kolumna danych'' - wskazuje na interesujące nas dane, które chcemy aby znalazły się w miejscu pojawienia się znacznika w szablonie[[BR]] * ''Kontekst'' - w przypadku wyboru tabel lub widoków, które są specyficzne różne od głównych: [[BR]] * dokument [[BR]] * dzienniki [[BR]] * umowa [[BR]] * sprawa [[BR]] * sprawa windykacyjna [[BR]] * kontakt [[BR]] * osoby kontaktowe [[BR]] należy wyspecyfikować kontekst i tak na przykład aby pobrać dane z widoku vindication.vind_proc_view np.: kolumnę vat należy wybrać kontekst sprawy windykacyjnej [[BR]] * ''Formatowanie'' - w przypadku jeśli chcemy, aby wymusić na pobieranych danych formatowanie określonego typu tzn. jeśli pobierana jest data w formacie 2000-01-01 08:00:00 jednak chcemy aby tylko pobrać z tego datę wtedy należy wybierać formatowane. Obecnie jest dostępne formatowanie daty, kwoty numerycznie oraz kwoty słownie. Poniżej znajduje się przykład znacznika wyciągającego pole opis z tabeli dokumentów. [[Image(znaczniki_dokumentow.png)]][[br]]''Rys. 5'' === Znacznik tworzony z cechy === Sposób definiowania tego typu znacznika jest bardzo podobny do poprzedniego z różnicą ostatniego pola ''Cecha''[[BR]] * ''Cecha'' - określa z jakiej cechy zostaną pobrane dane, jeśli wartość cechy będzie uzupełniona dla klucza określonego w polu ''Klucz główny''.W przypadku cech kontaktów (contacts) klucz główny to contid, natomiast w przypadku dokumentów jest to doc_id. === Znacznik z pomocnikiem === W przypadku definiowania znacznika metodą z pomocnikiem górna część definicji znacznika pozostaje taka sama jak w poprzednich przypadkach. Użyteczna pozostaje także lista predefiniowanych, pomocnych znaczników. Jest to najprostszy sposób definiowania znacznika, gdyż nie wymaga znajomości tabel jednak ma jedno ograniczenie. Pomocnik jest definiowany tylko przez programistę.[[BR]] * ''Znacznik'' - definicja znacznika wraz z ewentualnymi opcjami wyświetlania[[BR]] * ''Pomocnik'' - typ pomocnego znacznika z jakiego chcemy korzystać[[BR]] W przypadku tego pola znacznik może produkować dowolnie zdefiniowaną treść jak np.: generowanie tabelki z wykazem zadłużenia. [[BR]] Istnieje też możliwość dla własnych znaczników wydrukowanie listy bez tabelki. Wtedy trzeba zdefiniować w metodzie następującą treść: {{{ defined('TPL_TABLE_BORDER') ? null : define('TPL_TABLE_BORDER', FALSE); }}} [[BR]] W niektórych przypadkach, znaczniki utworzone metoda z pomocnikiem, mogą udostępniać różne sposoby wyświetlania. Aby spowodować wyświetlenie odpowiedniego formatowania w obrębie znacznika dodajemy odpowiedni token np. #KONTAKT.ADRES=bloczek# * Kontakt: dane adresowe: nazwa, adres, wszystko, bloczek.[[BR]] * Kontakt: sam adres: wiersz1, wiersz2, wszystko, bloczek.[[BR]] * Sprawa: strona sprawy: strona, adres, bloczek.[[BR]] * Sprawa: wierzyciel: nazwa, adres, wszystko, bloczek.[[BR]] * Sprawa: dłużnik: nazwa, adres, wszystko, bloczek.[[BR]] Możemy także tworzyć własnych pomocników.[[BR]] Gotowe skrypty umieszczamy w katalogu public_html\apps\edokumenty\classes\Templates\helpers[[BR]] Następnie aby skrypt był dostępny do użycia w znaczniku należy dodać wpis do bazy danych. Wpis umieszczamy w tabeli template_helper: - kolumna dscrpt zawiera opis pomocnika - kolumna thclnm zawiera nazwę pliku skryptu [wiki:UserGuide/AdvancedConfiguration/CreatingTemplates/Helpers Lista pomocników] === Znacznik jako SQL === Znacznik ten daje największe możliwości jeśli chodzi o pobieranie danych z bazy. Poza standardowymi polami, dostępne są dodatkowe: [[BR]] * ''Zapytanie SQL'' - definicja zapytania SQL, które zostanie wykonane * ''Kontekst'' - typ kontekstu, z jakiego będą pobrane dane * ''Źródło danych'' - jeśli chcemy aby dane były pobierane z innego systemu możemy to zrobić poprzez określenie źródła danych. Aby zdefiniować źródło danych należy przejść do Panelu sterowania -> Pozostałe ustawienia -> Źródła danych * ''Formatowanie'' - aby określić sposób wyświetlenia pobranych danych należy wybrać odpowiednie formatowanie. Obecnie dostępne sposoby formatowania dla znacznika SQL to: * data * kwota numerycznie * kwota słownie * tabelka (z nagłówkiem i lp) * tabelka bez lp (z nagłówkiem) * tabelka bez nagłówka (z lp) * tabelka bez nagłówka i bez lp W przypadku jeśli ma być nagłówek wtedy pierwszy wiersz wyniku jest nagłówkiem Dodatkowo dla formatowanie typu kwota (MONEY) - zapytanie musi być postaci {{{ SELECT 123, 'PLN' }}} * 1 kolumna to kwota * 2 kolumna to waluta Przykład wykorzystania tego znacznika [[BR]] Jako przykład niech posłuży pobranie numeru nip jednej ze stron umowy. Zapytanie wygląda następująco: [[BR]] * Zapytanie SQL: SELECT nip_ _ _ FROM contacts WHERE contid = (SELECT toctid FROM contract WHERE ctrcid={CONTEXT}) [[BR]] Kroki tworzenia takiego zapytania są następujące: * fraza pobierająca dane: SELECT nip_ _ _ FROM contacts * fraza warunku: WHERE contid * fraza podzapytania: (SELECT toctid FROM contract WHERE ctrcid={CONTEXT}) Podzapytanie tworzymy podobnie jak zwykłe zapytanie SQL ale jako warunek 'WHERE' wybieramy z listy kontekstów konkretny kontekst. W naszym przypadku będzie to kontekst 'Umowa'. Po wybraniu tego kontekstu w miejsce kursora w polu zapytania SQL pojawi się definicja ctrcid={CONTEXT}. Aby zmienić kontekst usuwamy fragment ctrcid={CONTEXT} i ponownie wybieramy kontekst. Aby obsłużyć brak danych i wypisać własny komunikat należy użyć formy np.[[BR]] {{{ SELECT COALESCE((SELECT nip_ _ _ FROM contacts WHERE contid=c.toctid)::text , 'brak numeru nip') FROM contract c WHERE ctrcid={CONTEXT} [[BR]] }}} == Parametry w znaczniku == Od wersji 4.0 dostępne są parametry przekazywane do znacznika bezpośrednio z dokumentu RTF - tylko dla znaczników zadeklarowanych jako SQL.[[BR]] W obrębie wykonania SQL jest dodatkowy token (przykładowy dokument o id 123): {{{ {TOKEN_PARAMS} }}} który przechowuje wszystkie przekazane parametry do tokena. Definicja tokena w dokumencie RTF: {{{ #DELEGACJA.KOSZTY.MIASTO;{CONTEXT},1# -- można używać {ENT_ID}, {LOGGED_USER}, {CONTEXT} - id dokumentu }}} Definicja znacznika SQL-owego może wyglądać tak: {{{ SELECT {TOKEN_PARAMS} lub SELECT getDelegationDetails('{TOKEN_PARAMS}', 'from__') -- trzeba zdefiniować funkcję pobierającą szczegóły kosztów delegacji faktyczne wykonanie będzie wyglądać następująco przy podanych parametrach SELECT getDelegationDetails('123,1', 'from__') }}} 123 - to id dokumentu w kontekście którego jest generowany dokument. Przekazanie parametrów odbywa się po średniku. Zawsze musi być robione jako ostatnie. Powodzenia. [[BR]] '''UWAGI'''[[BR]] W przypadku szablonów tworzonych w formacie rtf należy pamiętać, iż możliwe jest aby tekst w znaczniku był formatowany tak jak sobie tego życzy użytkownik. Znacznik można standardowo sformatować poprzez pogrubienie itd, jednak formatowaniu musi być poddany cały znacznik wraz z znakami '{{' lub '#'. === Przykłady użytecznych kwerend === {{{ -- kwerenda pobiera datę dokumentu który posłużył do wygenerowania aktualnego dokumentu -- np. procedura zapytania ofertowego tworzy ofertę - w ofercie chcemy pobrać do -- szablonu datę z zapytania. SELECT d2.adddat::date FROM documents d LEFT JOIN doc_link_doc dld ON d.doc_id = dld.doc_id LEFT JOIN documents_view d2 ON dld.rel_to = d2.doc_id WHERE d.doc_id = 905 -- Kwerenda pobiera zadania ze sprawy SELECT 'OPIS' AS opis, 'START' AS start, 'KONIEC' AS koniec, 'CZAS TRWANIA' AS czas UNION SELECT dscrpt, to_char(start_, 'YYYY-MM-DD HH:MI') AS start, to_char(end___, 'YYYY-MM-DD HH:MI') AS end, ((end___ - start_)::interval)::text AS duration FRom events_view WHERE prc_id IS NULL ORDER BY czas DESC -- Osoba tworząca pismo SELECT firnam || ' ' || lasnam FROM users u INNER JOIN documents d ON u.usr_id = d.adduid WHERE d.doc_id = 125 -- Pobranie opisu z nadrzędnej komórki organizacyjnej SELECT (SELECT regexp_replace(ndedsc, E'[\\n\\r]+', ' EDOK_LBR', 'g' ) FROM organization_units o WHERE orunid = get_ndedsc(8)::int) FROM orgtree_view u INNER JOIN documents d ON u.usr_id = d.adduid WHERE d.doc_id = 250 -- Status dokumentu (z ogólnego słownika statusów SELECT tops.dscrpt FROM types_of_processes_states tops LEFT JOIN documents d ON tops.tpstid = d.tpstid AND tops.clsnam = 'DOCUMENT' AND d.doc_id = 1 }}}