<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="VX-S-6">
  <refmeta>
    <refentrytitle>Advanced VSPX programming</refentrytitle>
    <refmiscinfo>tutorial</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>VSPX login control</refname>
    <refpurpose>Simple login dialog</refpurpose>
  </refnamediv>
  <refsect1 id="VS-S-6a">
    <title>Login example</title>
    <para>The vspx:login is a special control, it may occur inside VSPX page only once. In it's representation it may be a visual or it may be a hidden depending of intended purpose. 
    The purposes of that control are two: to verify login credentials and to ask user to enter a login.
    On pages that are authorized the control is hidden, but in case login fails, redirect will be made to a page which will ask for login. Reasonable question is what kind of authorization is supported? The answer is: HTTP Digest, URL poisoning and with Cookies. As Digest and Cookie are not well supported in world of browsers the most effective way is URL poisoning.  
    </para>
    <para>
    The attributes on vspx:login control are: 
    </para>
    <itemizedlist mark="bullet">
      <listitem>mode - designate type of authorization : "digest", "url" or "cookie". In out example it would be the "url"</listitem>
      <listitem>realm - this is a unique string within applications space. This is used to distinguish logins from one application to other. In other words: area of usability of performed login.</listitem>
      <listitem>user-password - name of PL function. This function is used when the mode is "digest". As digest do not send clear-text passwords this is used to retrieve from some source the password on server side.</listitem>
      <listitem>user-password-check - this is PL function which is used to check password for given user. It's used when "cookie" and "url" authorization is performed.</listitem>
    </itemizedlist>
    <para>In our example the setup script defines both functions: for digest and URL poisoning, so as exercise the type can be changed to "digest" and appropriate attribute to be set. 
    Also please note that digest on Netscape (up to 7.0) or Mozilla browsers will not function properly as they have a defect in digest handling. But anyway on IE5.0 or greater this can be experimented.
    </para>
    <para>The following children elements are interesting:</para>
    <itemizedlist mark="bullet">
      <listitem>template[if-no-login] - the content of it will be displayed when login failed. It may have special attribute "redirect" which will cause redirect to another page.</listitem>
      <listitem>template[if-login] - the content will be shown if request is authorized.</listitem>
      <listitem>login-form - this is a special form to ask user for entering the credentials. It may have defaults, but special content is also possible as in that example.</listitem>
      <listitem></listitem>
    </itemizedlist>
    <para>As note we should say that login-form contains special buttons and fields named "username", "password" and "login". These are used to represent custom login form. These must be with the exactly that names. And one vspx:button with special function - "logout", it is used to terminate the current session. The logout button may appear in any place of login control but it's usually in if-login template.</para>
    <para>Finally we should notice that when login control is used the connection variables and persistent page variables can be used. (for more details see vspx:variable and connection_set () , conenction_get () functions)
    </para>
  </refsect1>
</refentry>
