Subsections


A. Język LSP


1 Zmienne i ich wartościowanie

LSP używa składni XPath do pobierania wyników zapytań oraz do pobierania fragmentów drzew źródłowych w przypadku pobierania danych z plików XML. Użycia zmiennych mogą więc wyglądać następująco: 

  {$res/name} - {$res/email}
  {$x} {$y}
  {$res/xml::[descendant-or-self]/elem/value[position()=1]}

Pierwszy wiersz odpowiada polom name oraz email pewnego zapytania, gdzie res jest nazwą zmiennej, na którą jest przypisany aktualny rekord wyniku zapytania.

Drugi wiersz to zmienne lokalne bądź parametry, mogą one być ustawione przez użytkownika przy użyciu odpowiednich instrukcji.

Trzeci wiersz to wyrażenie XPath wybierające węzeł z dokumentu XML zawartego w polu xml wyniku zapytania (którego wynik przypisany jest do res.

W kolejnych podrozdziałach znajduje się spis funkcji obsługiwanych przez LSP, stanowiących rozszerzenie względem standardowych funkcji XPath.

Przetwarzanie zawartości pól następuje dopiero w chwili pierwszego użycia pola jako zbioru węzłów XML. Jeśli operujemy tylko na całych polach , to dane będą traktowane jako tekst.


1 bind

Sposób użycia: bind($node)

Powoduje, że zmienna nie jest wartościowana bezpośrednio w miejscu wstawienia, a poprzez referencję. Jest to bardzo użyteczne dla przyspieszania wykonywania zapytań SQL, mogą one być dzięki temu kompilowane raz i wykonywane dla wielu parametrów.


2 date

Sposób użycia: date($node,$format)

Zamienia czas z wartości liczbowej (liczba sekund -- tzw. znacznik czasowy, ang. timestamp) lub opisowej na wartość opisową (w innym formacie). Argument $format może przyjmować wartości:

Wszelkie nazwy (miesięcy, dni) zostaną sformatowane zgodnie z ustawieniami locale dla całej aplikacji bądź zgodnie ze zmienną LOCALE -- o ile jest ustawiona.


3 interval

Sposób użycia: interval($node,$format)

Zamienia przedział z wartości liczbowej (określającej liczbę sekund) lub opisowej na wartość opisową (w innym formacie). Argument $format ma podobne znaczenie jak dla funkcji date.


4 raw

Sposób użycia: raw($nodeset)

Wstawia węzeł bądź zbiór węzłów (wraz z wszystkimi znacznikami) bez żadnego przekształcania do dokumentu wynikowego. Domyślnie wartości są przekształcane do takiej postaci, aby w dokumencie wynikowym były traktowane jako czysty tekst. W ten sposób można wstawić fragment dokumentu XML pobrany z bazy do dokumentu wynikowego. Zmienna będąca argumentem jest pobierana jako tekst i tak wstawiana, co umożliwia wygenerowanie kodu niepoprawnego składniowo, więc należy jej używać ostrożnie. Jeżeli argument jest zbiorem węzłów będącym wynikiem wyrażenia XPath, to wstawiana wartość będzie poprawnym fragmentem dokumentu.


5 xml

Sposób użycia: xml($nodeset)

Działa podobnie jak funkcja raw, lecz zawsze sprawdza poprawność wstawianego dokumentu.


2 Zmienne systemowe

LSP udostępnia kilka zmiennych dla użytku aplikacji. Większość z nich jest tylko do odczytu i nie należy definiować swoich własnych zmiennych o identycznych nazwach, ponieważ mogą zostać nadpisane przez funkcje systemu.

1 Parametry wykonania

Podstawową zmienną zawierającą parametry wykonywania jest LSPinfo Pole LSPinfo/file zawiera nazwę aplikacji wywołanej przez użytkownika. LSPinfo/format to żądany format dokumentu wyjściowego (określony na podstawie rozszerzenia pliku podanego przez użytkownika). Możliwe wartości to html, tex, pdf, xls, txt.

2 Uwierzytelnianie

Zmienna LSPauth jest ustawiana przez moduł uwierzytelniania, jej pola zawierają informacje na temat aktualnego użytkownika. Pola LSPauth/username oraz LSPauth/userid zawierają (odpowiednio) jego nazwę i identyfikator. Pole LSPauth/usergroups zawiera listę grup do których należy użytkownik (ale nie należy tej informacji wykorzystywać zamiast atrybutów autoryzacyjnych), w postaci identyfikatorów oddzielonych przecinkami. Pole LSPauth/profile zawiera profil (poziom uprawnień) użytkownika.

3 Czas i statystyki

Pole LSPstatstarttime zawiera czas uruchowienia programu, LSPstatsurrenttime natomiast czas aktualny. Obie wartości są typu liczbowego. Dodatkowo dostępne są wartości LSPstatssptime, LSPstatsslttime oraz LSPstatsqltime, oznaczające odpowiednio czas spędzony na wykonywaniu instrukcji LSP, przekształceniach XSLT oraz zapytaniach SQL.

3 Wspólne atrybuty

Atrybuty wymienione w dalszej części rozdziału są wykorzystywane w wielu instrukcjach, dlatego szczegółowo opisane są tutaj, natomiast opisy poszczególnych elementów będą jedynie zawierać informację o ich wykorzystywaniu.


1 Atrybuty autoryzacyjne

Wykorzystywane głównie w wyrażeniach logicznych. Dokładny opis ich znaczenia znajduje się w p. 3.4.2.

Wszystkie te atrybuty są opcjonalne i można je dowolnie łączyć.


2 Atrybuty zapytań

Używane w elementach, które pobierają dane z bazy SQL.


4 Instrukcje

Wszystkie węzły w dokumencie są poprzedzone przedrostkiem lsp:, zgodnie z ustaleniami przyjętymi w [ns99].


1 APPLICATION

Główny węzeł dokumentu.


Atrybuty:


Zawartość:

Dowolna (z wyjątkiem APPLICATION).


Przykład: 

  <?xml version="1.0"?>
  <lsp:application name="test">
    Witaj, Świecie!
  </lsp:application>


2 QUERY

Wszystko co jest zawarte pomiędzy otwarciem a zamknięciem tego znacznika zostanie wykonane dla każdego rekordu wynikowego zapytania wyspecyfikowanego w argumentach.


Atrybuty:


Występowanie:

Dowolnie (z wyjątkiem węzłów których zawartość nie przewiduje możliwości umieszczania w nich elementów LSP).


Zawartość:

Dowolne elementy LSP z wyjątkiem APPLICATION oraz PARAM, tekst, elementy dokumentu wyjściowego.


Opis:

Aktualny rekord wynikowy znajdować się będzie na zmiennej określonej atrybutem name, poszczególne pola nazwane tak jak poszczególne kolumny - por. też p. A.1.

Atrybut db decyduje o tym z jakią bazą danych zostanie nawiązane połączenie. Jeżeli nie jest on obecny, to jest pobierany z najbliższego węzła nadrzędnego bądź z ustawień globalnych aplikacji.

Jeżeli w żaden sposób nie wyspecyfikowano zapytania, to zawartość zostanie przetworzona jeden raz, tworząc blok dokumentu, który można wielokrotnie wykorzystywać za pomocą atrybutu use.


Przykład: 

  <query name="deps"
         sql="SELECT projects.* FROM deps,projects WHERE
              deps.project_id=[?=params.project_id] AND
              deps.after_id=projects.project_id">
    <a href="main.xml?project_id="></a><br/>     
  </query>


3 PARAM

Definiuje parametr raportu.


Atrybuty:


Występowanie:

Tylko w głównym węźle APPLICATION, przed jakimikolwiek innymi węzłami, oraz w węzłach INCLUDE.


Zawartość:

Może zawierać wartość domyślną parametru. Jeżeli podany jest atrybut value, ro zawartość jest ignorowana. Nie może zawierać elementów LSP.


Opis:

Typ zmiennej jest sprawdzany tylko przy pobieraniu jej ze środowiska CGI (lub analogicznego, np. zmiennych SOAP dla aplikacji SOAP). Dane strukturalne najlepiej przesyłać jako xml. Jeżeli typy danych przekazanych przez użytkownika nie zgadzają się z deklaracją, to aplikacja nie wykona się i zostanie przekazany błąd brak dostępu.

Wewnątrz węzłów INCLUDE środowisko stanowią aktualne wartości zmiennych; poza tym zasady pozostają te same, choć definiowanie typów zmiennych nie jest konieczne (są i tak najprawdopodobniej zadeklarowane wewnątrz wołanej aplikacji).


Przykład: 

  <lsp:application name="foobar">
    <lsp:param name="foo" type="string(1,128)" value="bar"/>
    <lsp:param name="bar" type="integer" preserve="preserve"/>
    <lsp:param name="baz" type="xml">
      <data><a>7</a><b>8</b></data>
    </lsp:param>

    Foobar: {$foo}{$bar}

    baz.a: {$baz/data/a}

  </lsp:application>


4 SET

Ustawia wartość zmiennej.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Może zawierać wartość domyślną parametru. Jeżeli podany jest atrybut value, to zawartość jest ignorowana. Może zawierać elementy LSP. W ten sposób można zapamiętać na zmiennej fragment dokumentu wynikowego (to samo można osiągnąć definiując odpowiednie QUERY, co jest trochę wolniejsze).


Opis:

Powoduje zapamiętanie na zmiennej określonej atrybutem name wartości określonej atrybutem value lub stanowiącej zawartość tego węzła.

Nie zachodzi żadne sprawdzanie typów, można więc zapisać zmienną napisową na parametr zadeklarowany jako liczbowy.


Przykład: 

  <lsp:set name="foo">
    <bar> foobar </bar>
  </lsp:set>
  <lsp:set name="bar" value="{$foo}"/>


5 IF


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2), może występować w elemencie CHOOSE.


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Jeżeli wyrażenie nie jest spełnione (wartość 0 lub FALSE), to zawartość elementu IF jest pomijana.


Przykład: 

  <lsp:if expr="$x=5">
    X równe jest 5!
  </lsp:if>


6 ELSE


Atrybuty:


Występowanie:

Jak IF (p. A.4.5).


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Jeżeli żadne z poprzedzających wyrażeń IF nie zostało spełnione, to przetwarza się zawartość tego elementu.


Przykład: 

  <lsp:if expr="$x=3">
    X równe jest 5!
  </lsp:if>
  <lsp:else>
    X nie jest równe 5!
  </lsp:else>


7 CHOOSE

Wybór jednej z możliwości.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Wyłącznie elementy IF oraz ELSE.


Opis:

Przetwarzany jest pierwszy element IF, którego wyrażenie zostanie spełnione oraz każdy poprzedzający go w dokumencie element ELSE (jeśli żadna gałąź IF nie zostanie spełniona, to przetwarzane są wszystkie gałęzie ELSE).


Przykład: 

  <lsp:choose>
    <lsp:if expr="$x=1">
      X=Jeden
    </lsp:if>
    <lsp:if expr="$x=2">
      X=Dwa
    </lsp:if>
    <lsp:else>
      Ani Jeden, Ani Dwa... hmmm...
    </lsp:else>
    <lsp:if expr="$x=3">
      Aha, X=Trzy
    </lsp:if>
    <lsp:else>
      X=NieWiadomoCo.
    </lsp:else>
  </lsp:choose>


8 WHILE


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Zawartość jest przetwarzana wielokrotnie, tak długo, jak długo będzie spełniony warunek logiczny.


Przykład: 

  <lsp:application>
    <lsp:param name="group" value="1" type="integer"/>
    <lsp:while class="projekty" group="{$group}" level="{$level}">
      <lsp:set name="level" value="{$level+1}">
    </lsp:while>
    Maksymalny poziom: {$level}
  <lsp:application>


9 LOAD

Wczytuje plik XML z dysku i przypisuje do zmiennej.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Zostanie przetworzona, jeśli plik istnieje i zostanie poprawnie wczytany (tj. jeśli jest poprawnym plikiem XML).


Opis:

Po wczytaniu zawartość pliku dostępna jest na zmiennej określonej atrybutem name (podobnie jak wyniki zapytania), tyle, że cała struktura dokumentu znajduje się na jednej zmiennej.


Przykład: 

  <lsp:load name="foo" src="bar.xml">
    Tytuł: {$lsp/document/title}
  </lsp:load>


10 INCLUDE

Wstawia wynik wykonania aplikacji LSP.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Elementy PARAM.


Opis:

Plik jest uruchamiany ze środowiskiem budowanym na podstawie elementów PARAM, a wynik przetwarzania wstawiany do wynikowego dokumentu.


Przykład: 

  <lsp:include src="menubar.lsp">
    <lsp:param name="color" value="blue"/>
    <lsp:param name="foo" value="3"/>
  </lsp:include>


11 CACHE

Buforowanie wyników kontrolowane przez użytkownika.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Upraszcza procedurę zachowywania fragmentów dokumentu przypisując przetworzoną zawartość węzła do klucza buforowania zadanego argumentem key. Dodatkowo daje możliwość pominięcia fragmentu jeżeli nie jest spełnione wyrażenie regularne określone atrybutem regexp.


Przykład: 

  <lsp:while expr="$bar<17">
    <lsp:set name="bar" value="{$bar+1}"/>
    <lsp:cache key="foo-{$bar}-17">
      <lsp:query name="row" src="foobar.sql">
        Bardzo skomplikowane zapytanie: {$row/name}
      </lsp:query>
    </lsp:cache">
  </lsp:while>


12 STORE

Zapisywanie dokumentów XML na dysku.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Jak QUERY (p. A.4.2). Jeżeli podany jest atrybut value, to zawartość jest ignorowana.


Opis:

Umożliwia zachowanie na dysku dokumentów XML. Pliki zachowywane są w bieżącym katalogu aplikacji (atrybut dst może zawierać również nazwę katalogu).


Przykład: 

  <lsp:store dst="files/{$name}.xml">
     <document>
       <title>{$title}</title>
       <content>{$content}</content>
     </document>
  </lsp:store>
  
  Indeks dokumentów:
  
  <lsp:load name="foo" src="files/*.xml">
    Tytuł: {$lsp/document/title}
  </lsp:load>


13 CALL

Interfejs mechanizmu rozszerzeń.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Podobnie jak QUERY, zawartość jest przetwarzana wielokrotnie, dopóki, dopóty funkcja zwraca wyniki. Wynik działania funkcji zapisywany jest na zmiennej o nazwie podanej atryb

Mechanizm CALL służy do implementacji rozszerzeń systemu LSP, podstawowe środowisko nie zapewnia żadnych funkcji, które można by w ten sposób wywoływać.

Funkcje mogą również nie zwracać żadnych wyników a jedynie wykonywać inne operacje, mogą także bezpośrednio generować treść dokumentu wyjściowego.


Przykłady: 

<lsp:call function="exec" param="/usr/games/fortune"/>

<lsp:call function="findstudent" param="name(Dominika)" name="student">
  <p>Imię: {$student/name}, Nazwisko: {$student/nazwisko}</p>
</lsp:call>


14 TRANSFORM

Wykonuje przekształcenia XSLT.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Po przetworzeniu całej zawartości, przesyłana jest ona do procesora XSLT i przekształcana za pomocą arkusza stylów określonego atrybutem xsl.


Przykład: 

<lsp:transform xsl="records.xsl">
  <lsp:query table="users">
    <login>{$users/login}</login>
    <name>{$users/name}</name>
    <email}{$users/email}</email>
  </lsp:query>
</lsp:transform>


15 KEEP

Zachowywanie zmiennych w sesji.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Brak.


Opis:

Zachowuje w sesji wartość określoną atrybutem value pod kluczem określonym atrybutem key. Zmienne zachowane w ten sposób można odczytać za pomocą instrukcji FIND (p. A.4.16). Nazwa klucza nie może zaczynać się od znaku podkreślenia, "_".


Przykład: 

<lsp:query table="users" key="user_id">
  Użytkownik {$users/login} wybrany. 
  <lsp:keep key="email" value="{$users/email}"
</lsp:query>


16 FIND

Pobieranie zmiennych z sesji.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Brak.


Opis:

Pobiera z sesji wartość znajdującą się pod kluczem określonym atrybutem key i zapisuje ją na zmiennej określonej atrybutem name. Można w ten sposób między innymi odczytać wartości wstawiane do sesji przez moduł automatycznej obsługi formularzy, można także pobrać wartości wcześniej zapamiętane za pomocą instrukcji KEEP (p A.4.15).


Przykład: 

<lsp:find key="email" name="defaultemail"/>
<lsp:input name="email" type="string(1,128)" value="{$defaultemail}"/>


17 FORM

Formularz LSP.


Atrybuty:


Występowanie:

Jak QUERY (p. A.4.2), nie może być zagnieżdżany, w programie nie mogą występować dwa formularze o tej samej nazwie.


Zawartość:

Jak QUERY (p. A.4.2), może też zawierać komponenty formularzy.


Opis:

Otwiera formularz (przekształcany na formularz HTML). Z bazy pobierany jest rekord zgodnie z wyspecyfikowanym zapytaniem. Jeżeli zapytanie przekaże pusty wynik, to wypełnienie formularza spowoduje dodanie nowego elementu do tabeli, w przeciwnym wypadku, elementy formularza zostaną wypełnione danymi z bazy. Jeżeli zapytanie przekaże więcej niż jeden element, to aplikacja zwróci błąd. Jeżeli nie jest podany atrybut table, to formularz zostanie wygenerowany, a wartości domyślne pól pobrane ze zmiennych o tej samej nazwie. W takiej sytuacji nie można użyć automatycznej obsługi formularza.

W trakcie generowania formularza, do tablicy sesji wstawiane są klucze edit_table, edit_key, edit_page, edit_action, o wartościach pobranych z odpowiednich atrybutów. Wszystkie klucze edit_*, type_*, value_* są usuwane w trakcie obsługi kolejnego żądania w ramach tej samej sesji. Dzięki temu formularz zostanie przetworzony co najwyżej raz (nie zostanie przetworzony, jeżeli np. użytkownik otworzy inną stronę serwisu)

Wartości pól formularza wprowadzone przez użytkownika są przekazywane do aplikacji obsługującej jako parametry field_@name, gdzie @name to nazwa pola formularza.


Przykład: 

<lsp:form table="movies" key="movie_id" page="movielist.lsp">
  <lsp:input name="title_pl" type="text(1,128)">
  <lsp:input name="title_en" type="text(0,128)">
  ...
</lsp:form>


18 INPUT

Pole tekstowe formularza.


Atrybuty:


Występowanie:

Wewnątrz FORM (p. A.4.17).


Zawartość:

Brak.


Opis:

Wstawia do tabeli session klucz o nazwie type_@name (@name to wartość atrybutu name) i wartośći pobranej z atrybutu type. Klucz ten jest wykorzystywany do automatycznej obsługi formularza. Jeżeli pole jest typu hidden, to nie jest wstawiany typ -- zamiast tego wstawiana jest wartość podana w atrybucie value, a jako nazwa klucza używa się value_@name.


Przykład:

Patrz p. A.4.17.


19 LINK

Pole wyboru (wiązanie z inną tabelą).


Atrybuty:


Występowanie:

Wewnątrz FORM (p. A.4.17).


Zawartość:

Brak.


Opis:

Tworzy pole wyboru na podstawie zawartości pobranych z bazy danych. Zapytanie wybierające może zostać podane lub skonstruowane na podstawie odpowiednich atrybutów. W trakcie przetwarzania do tablicy sesji wstawiane są możliwe wartości pola, wszystkie z kluczem value_@name. System sprawdzania poprawności wykorzystuje te informacje do ustalenia, czy użytkownik nie próbuje przekazać nieprawidłowej wartości.


Przykład: 

  ...
  <TD>Profil zabezpieczeń</TD>
  <TD>
    <lsp:link name="profile_id" table="profiles" label="name"
     filter="profile_id>={bind($LSPauth/profile)}"
     value="{$profil}">
  </TD>
  ...


20 BUTTON

Przycisk formularza.


Atrybuty:


Występowanie:

Wewnątrz FORM (p. A.4.17).


Zawartość:

Brak.


Opis:

Zawartość pola action zostanie przekazana do aplikacji obsługującej (jeżeli nie jest używana obsługa automatyczna) jako parametr o nazwie action.


Przykład: 

<lsp:form table="users" key="user_id" page="users.lsp">
...
<lsp:button name="OK" action="submit"/>
<lsp:button name="Cancel" action="cancel"/>
</lsp:form>


21 BOOLEAN

Pole logiczne formularza, przedstawiane jako przełącznik lub lista wyboru.


Atrybuty:


Występowanie:

Wewnątrz FORM (p. A.4.17).


Zawartość:

Brak.


Opis:

Wstawia do tablicy sesji z kluczem value_@name dwie wartości 0 oraz 1. Pole to jest obsługiwane na identycznych zasadach jak element LINK (p. A.4.19).


Przykład: 

<lsp:form action="search.lsp">
<TR><TD>Szukaj w nazwie</TD>
    <TD><lsp:input name="nazwa"/></TD>
<TR><TD>Tylko z województwa {$woj} </TD>
    <TD><lsp:boolean name="limit" value="1"/></TD>
<lsp:input type="hidden" name="woj" value="{$woj}"/>
<lsp:button name="OK" action="submit">
</lsp:form>


22 COMMENT

Przepisuje zawartość jako komentarz do pliku wyjściowego.


Występowanie:

Jak QUERY (p. A.4.2).


Zawartość:

Jak QUERY (p. A.4.2).


Opis:

Przetwarza zawartość, ale umieszcza ją w znacznikach komentarza HTML, co umożliwia wstawianie komentarzy w dokumentach wynikowych.


Przykład: 

<lsp:application>
  <!-- to zniknie -->
  <lsp:comment>
    To będzie w komentarzu
  </lsp:comment>
  A to będzie treść.
</lsp:application>