Язык @-формул в LotusDomino R 6.

Функции, используемые в Web-приложениях


@URLOpen

@URLOpen( "URL"; флаги; "MIME_набор_символов";

      "имя_web_пользователя"; "web_пароль";

      "имя_пользователя_для_прокси_сервера";

      "пароль_для_прокси_сервера")

Область применения: нельзя использовать в формулах отбора, колонок, видимости объекта, редактируемой секции, заголовка окна, полей и формы.

В первом варианте синтаксиса (т.е. без параметров) функция в интерфейсе клиента Notes открывает (если не было открыто ранее) в панели инструментов поле задания URL, и устанавливает на него фокус. Данный синтаксис в Web-приложениях не поддерживается.

Во втором варианте синтаксиса функция может быть использована как в клиенте Notes, так и в браузере. Первый параметр "URL" обязателен, и задает адрес Web-ресурса, который требуется открыть. Остальные параметры необязательные, и предназначены для использования в Notes браузере в контексте баз данных "Server Web Navigator" и "Personal Web Navigator". Рассмотрим эти параметры подробнее:

  • флаги – определяют параметры перезагрузки запрашиваемой страницы, а также принудительного сохранения всех ссылок с запрашиваемой страницы. Данные операции имеют смысл только в рамках баз данных "Server Web Navigator" и "Personal Web Navigator". Если необходимо опустить параметр флаги, но определить следующие за ним параметры, то для флаги нужно указать значение 0 (например, @URLOpen( "http://www.ibm.com"; 0; "myusername"; "mypassword" ) ). С точки зрения синтаксиса, параметр флаги

    может быть списком из следующих значений:

  • [RELOAD] – перегружает страницу с интернет сервера;
  • [RELOADIFMODIFIED] – перегружает страницу, только если она была изменена на интернет сервере;
  • [URLLIST] – сохраняет все гиперссылки с запрашиваемой страницы в полях URLLinksN. Первое поле будет называться URLLinks1, далее, когда содержимое этого поля превысит размер в 64К, то будет создано новое поле под ссылки с именем URLLinks2 и т.д. Впоследствии можно использовать эти поля (например, в агенте) для актуализации данных ссылок. Включение данного флага может серьезно сказаться на производительности приложения.



  • "MIME_набор_символов"

    – принудительно устанавливает указанный символьный набор MIME для указанной страницы. Предназначен для использования в случае, когда Web Navigator определяет символьный набор MIME некорректно;


  • "имя_web_пользователя" и "web_пароль" – предназначены для задания имени/пароля при обращении к ресурсу, требующему аутентификации. Данные параметры применимы только в контексте Notes Web Navigator, в других браузерах для аутентификации используются свои средства;


  • "имя_пользователя_для_прокси_сервера"  и "пароль_для_прокси_сервера"

    – предназначена для аутентификации в рамках прокси сервера.


  • Наиболее часто функция применяется с одним параметром "URL".

    Если требуется открывать указанную страницу в другом фрейме, то в документации приводится решение с добавлением в параметр "URL" атрибута target, заключенного в кавычки. Данная конструкция (учитывая, что в документации пример приведен с синтаксической ошибкой) у автора к нужным результатам не привела. Однако, применение перед @URLOpen функции @SetTargetFrame решает поставленную задачу.

    Пример. Формула, примененная в кнопке формы, открывает в новом окне сайт lotus.com.

    @SetTargetFrame( "_blank" );

    @URLOpen( "http://www.lotus.com" )

    J @URLEncode( "формат"; значение )

    Область применения: без ограничений.

    Преобразует значение, представленное в виде строки или списка строк, к формату пригодному для использования в URL. Параметр "формат" может задаваться в виде имени символьного набора MIME (например, "KOI8-R" или "ISO-8859-1") или в виде одной из двух предопределенных строк:

    • "Domino" – соответствует символьному набору MIME "UTF-8";


    • "Platform" – преобразует параметр значение в соответствии с базовым символьным набором операционной системы.


    • Функция преобразует не-ASCII символы второго параметра в указанный символьный набор, а затем кодирует их в формат %XX, где XX есть шестнадцатеричное представление символа.



      В Domino 5- й версии разработчики достаточно часто использовали эту функцию в Web-приложениях, однако на тот момент она была недокументированна. Кроме этого при переходе к 6-й версии Domino изменился набор допустимых значений параметра "формат".

      Функция бывает очень полезна при передаче через URL параметров, значения которых не укладывается в ASCII набор символов.

      Пример. Формула, примененная в кнопке формы, открывает Web-страницу, получаемую в результате поиска фразы "перезагрузка сервера" на форуме компании «Интертраст».

      @URLOpen("http://www.intertrust.ru/site/itforum.nsf/KK/?SearchView&Query=" + @URLEncode( "Platform"; "перезагрузка сервера" ))

      J @URLDecode( "формат"; значение )

      Область применения: без ограничений.

      Выполняет обратное преобразование по отношению к функции @URLDecode. Синтаксис и смысловое значение параметров "формат"

      и значение соответствует функции @URLEncode.

      Пример. Если форма открывается в Web-приложении по URL вида «… имя_БД/имя_формы?OpenForm&FIO=%CF%EE%EB%FF%EA%EE%E2%20%C5.%C2.», то для того, чтобы присвоить некоторому полю значение из параметра FIO из URL, достаточно определить для него следующую Defaut Value формулу:

      @URLDecode( "Platform"; @UrlQueryString( "FIO" ))

      Следует заметить, что значение параметра FIO из URL было предварительно получено с использованием функции @URLEncode, так же с первым параметром "Platform".

      J @GetHTTPheader( "имя_header_поля" )

      Область применения: разрешается использовать только в Web-приложениях и в контексте видимости объекта, редактируемой секции, заголовка окна, гиперобъекта, полей, формы, акций вида и формы, а также навигатора. В интерфейсе клиента Notes всегда возвращает пустую строку.

      В Web-приложениях возвращает значение полей типа header fields (более подробно о них можно посмотреть в документе http://www.w3.org/Protocols/rfc1945/rfc1945

      раздел 10 «Header Field Definitions»). Значения имя_header_поля могут принимать допустимые значения для полей типа header fields (например, User-Agent, Last-Modified, Content-Type и т.д.).



      Пример. Следующая формула в Web-приложении без использования в форме CGI-поля "HTTP_User_Agent", возвращает значение, например, «Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)»

      @GetHTTPHeader( "User-Agent" )

      J @SetHTTPHeader( "имя_response_header_поля"; значение )

      Область применения: нельзя использовать в формулах кнопок панели инструментов, колонок, любых типов агентов, видимости объекта, редактируемой секции, всплывающих окон и области размещения.

      В Web-приложениях устанавливает значение для полей заголовка  HTTP-отклика (response header field). Подробнее о данном типе полей можно посмотреть в документе RFC 2616 (http://www.w3.org/Protocols/rfc2616/rfc2616.html, http://book.itep.ru/4/45/http4561.htm).

      Возвращает значение 1 (TRUE) – при успешной установке значения полю, и 0 (FALSE) в противном случае. В интерфейсе клиента Notes функция всегда возвращает 0 (FALSE).

      Параметр имя_response_header_поля задается текстовой строкой, и определяет имя поля, которому требуется установить значение. Некоторые поля заголовка HTTP-отклика доступны только для чтения (например, Connection, Content-Type, Date и Server), и поэтому не могут быть изменены функцией @SetHTTPHeader. Следует еще помнить, что помимо строго полей заголовка HTTP-отклика, в качестве параметра имя_response_header_поля

      могут использоваться общие поля заголовка (general header field).

      Параметр значение представляет собой значение для поля заголовка HTTP-отклика. Формат параметра соответствует ожидаемому значению, и может быть текстовой строкой, числом или датой. В последнем случае параметр должен быть в формате RFC 1123 (например, «Sun, 09 Nov 2003 08:49:37 GMT»). Пустая строка в качестве значения

      удаляет соответствующее поле вместе со значением (данное утверждение автор не смог проверить на практике).

      Пример 1. На форме разместим две кнопки. Для первой определим заголовок (Label) «Установить Cookie», затем в программной панели для поля Run выберем значения «Client» и «Formula», а в качестве формулы введем:



      @SetHTTPHeader("Set-Cookie"; "My_Proba=777")

      Для второй кнопки определим: Label – «Прочитать Cookie», Run – «Web» и «JavaScript», код:

      alert(getCookie('My_Proba'));

      В объект JS Header формы  внесем следующий код:

      function getCookie(name) {

              var prefix = name + "="

              var cookieStartIndex = document.cookie.indexOf(prefix)

              if (cookieStartIndex == -1)

                      return null

              var cookieEndIndex = document.cookie.indexOf(";", cookieStartIndex + prefix.length)

              if (cookieEndIndex == -1)

                      cookieEndIndex = document.cookie.length

              return unescape(document.cookie.substring(cookieStartIndex + prefix.length, cookieEndIndex))

      }

      После последовательного клика сначала по «Установить Cookie», а затем по «Прочитать Cookie», - получаем окно со значением 777.

      J @URLQueryString( [параметр] )

      Область применения: нельзя использовать в формулах кнопок панели инструментов, отбора, колонок, агентов, всплывающих окон и области размещения. В интерфейсе клиента Notes всегда возвращает пустую строку.

      В Web-приложениях возвращает параметры из текущего URL. При отсутствии аргумента возвращает все параметры URL в виде списка. При передаче допустимого параметра, возвращает его значение, или пустую строку, если такого параметра нет в URL. Пустое значение так же возвращается, если параметр передается в виде ключевого слова (например, http://www.inttrust.ru/test/test.nsf/Form?OpenForm&Par1=100&Par2&Par3=No).

      Пример 1. Если URL текущего документа есть "http://dominornext.inttrust.ru/test/test.nsf/Form?OpenForm&Seq=7" функция вернет список "OpenForm" : " Seq=7"

      @URLQueryString;

      Пример 2. Если URL текущего документа есть "http://dominornext.inttrust.ru/test/test.nsf/Form?OpenForm&Seq=7" функция вернет строку "7".

      @URLQueryString( "Seq" );

      J @WebDBName

      Область применения: без ограничений.

      Возвращает имя текущей базы данных в формате, пригодном для использования в URL. При этом символ обратного слеша («\») заменяется на обычный слеш («/»), двойной обратный слеш («\\») из имени удаляется, символ тире («-») остается без изменений, так же не изменяется расширение файла, начинающееся с символа точки. Остальные специальные символы заменяются на %xx, где xx – шестнадцатеричное представление символа. Так например, пробел заменяется на символ %20.

      Функция главным образом предназначена для дальнейшего использования в URL командах.

      Пример. Формула, используемая в кнопке формы, формирует URL открытия текущей БД.

      @URLOpen( "http://" + @GetHTTPHeader( "Host" ) + "/" + @WebDbName + "?OpenDatabase")


      Содержание раздела