<commit_before>.. highlight:: rest

The :mod:`saliweb::frontend` Perl module
========================================

This module provides Perl functions and classes useful for implementing
the web frontend.

.. class:: saliwebfrontend(config_file, version, server_name)

   The main class used by the frontend. Typically a web service will subclass
   this class and override one or more methods to actually implement the
   web interface. The class creates a Perl CGI object which can be used to
   actually output web pages, and provides methods that behave similarly to
   the corresponding methods in CGI.pm, such as
   :meth:`~saliwebfrontend.start_html`.

   .. attribute:: htmlroot

      The top-level URL under which all static web files (HTML, style sheets,
      images) are found (read-only).

   .. attribute:: cgiroot

      The top-level URL under which all CGI scripts are found (read-only).

   .. attribute:: http_status

      The HTTP status code (e.g. 200 OK, 404 Not Found) that will be
      reported when the web page is printed.

   .. attribute:: version

      The version number of this web service (read-only).

   .. attribute:: user_name

      If a user is authenticated against the service, this is their user
      name; otherwise, it is undef (read-only).

   .. attribute:: email

      If a user is authenticated against the service, this is their email
      address; otherwise, it is undef (read-only).

   .. attribute:: modeller_key

      If a user is authenticated against the service and has already provided
      a MODELLER key, this is it; otherwise, it is undef (read-only).

   .. attribute:: cgi

      A pointer to the CGI.pm object used to display HTML (read-only).

   .. attribute:: dbh

      The database handle.

   .. attribute:: index_url
                  submit_url
                  queue_url
                  help_url
                  faq_url
                  links_url
                  about_url
                  news_url
                  contact_url
                  results_url
                  download_url

      Absolute URLs to each web page (read-only).

   .. method:: get_header_page_title()

      Return the HTML fragment used to display the page title inside a div in
      the page header. By default, this just displays the lab logo and the page
      title, but can be overridden if desired.

   .. method:: get_lab_navigation_links()

      Return a reference to a list of lab resources and services, used by
      :meth:`~saliwebfrontend.get_header`. This can be overridden in
      subclasses to add additional links.

   .. method:: get_navigation_links()

      Return a reference to a list of navigation links, used by
      :meth:`~saliwebfrontend.get_header`. This should be overridden for each
      service to add links to pages to submit jobs, show help, list jobs
      in the queue, etc.

   .. method:: get_project_menu()

      Return an HTML fragment which will be displayed in a project menu,
      used by :meth:`~saliwebfrontend.get_header`. This can contain general
      information about the service, links, etc., and should be overridden
      for each service.

   .. method:: display_index_page()
               display_submit_page()
               display_queue_page()
               display_help_page()
               display_results_page()
               display_download_page()

      Convenience methods designed to be called from CGI scripts. Each displays
      a complete web page by calling :meth:`~saliwebfrontend.start_html`,
      :meth:`~saliwebfrontend.get_header`, :meth:`~saliwebfrontend.get_footer`,
      and :meth:`~saliwebfrontend.end_html`. The actual page content is obtained
      from a similarly named get_*_page() method; for example,
      :meth:`~saliwebfrontend.display_index_page` calls
      :meth:`~saliwebfrontend.get_index_page`.
      Each method also calls :meth:`~saliwebfrontend.check_page_access` to
      check whether access to the page is permitted.

   .. method:: get_index_page()

      Return the HTML content of the index page. This is empty by default, and
      must be overridden for each web service. Typically this will display a
      form for user input (multi-page input can be supported if intermediate
      values are passed between pages).

   .. method:: get_submit_page()

      Return the HTML content of the submit page (that shown when a job is
      submitted to the backend). This is empty by default, and
      must be overridden for each web service. Typically this method will
      perform checks on the input data (throwing an
      :exc:`~saliweb::frontend.InputValidationError`
      to report any problems), then call :meth:`~saliwebfrontend.make_job`
      and its own :meth:`~saliweb::frontend.IncomingJob.submit` method to
      actually submit the job to the cluster, then point the user to the URL
      where job results can be obtained.
      
   .. method:: get_results_page(job)

      Return the HTML content of the results page (that shown when the user
      tries to view job results). It is passed a
      :class:`~saliweb::frontend.CompletedJob` object
      that contains information such as the name of the job and the time
      at which job results will be removed, and is run in the job's directory.
      This method is empty by default, and
      must be overridden for each web service. Typically this method will
      display any job failures (e.g. log files), display the job results
      directly, or provide a set of links to allow result files to be
      downloaded. In the last case, these URLs are simply the main results
      URL with an additional 'file' parameter that gives the file name;
      see :meth:`~saliwebfrontend.allow_file_download` and
      :meth:`~saliwebfrontend.get_file_mime_type`.

   .. method:: get_queue_page()

      Return the HTML content of the queue page. By default this simply shows
      all jobs in the queue in date order, plus some basic help text. (Note that
      there is currently no interface defined to do this any differently. If
      you need to customize the queue page, please talk to Ben so we can design
      a suitable interface.)

   .. method:: get_help_page(type)

      Return the HTML content of help, contact, FAQ, links, about, or news
      pages; the passed *type* parameter will be *help*, *contact*, *faq*,
      *links*, *about*, or *news*. By default
      this simply displays a suitable text file installed as part of the web
      service in the ``txt`` directory, named ``help.txt``, ``contact.txt``,
      ``faq.txt``, ``links.txt``, ``about.txt``, or ``news.txt`` respectively.

   .. method:: get_download_page()

      Return the HTML content of the download page. This is empty by default.
   .. method:: check_page_access(page_type)

      Check whether access to the given *page_type* is allowed. *page_type*
      is one of 'index', 'submit', 'queue', 'results', 'help', 'download'.
      It should simply return if access is allowed, or throw an
      :exc:`~saliweb::frontend.AccessDeniedError` exception if access is not
      permitted. By default, it simply returns, allowing all access.

   .. method:: allow_file_download(file)

      When downloading a results file (see
      :meth:`~saliwebfrontend.get_results_page`) this
      method is called to check whether the file is allowed to be downloaded,
      and should return true if it is. (For example, the job results directory
      may contain intermediate output files that should not be downloaded for
      efficiency or security reasons.) By default, this method always returns
      true.

   .. method:: get_file_mime_type(file)

      When downloading a results file (see
      :meth:`~saliwebfrontend.get_results_page`) this
      method is called to get the correct MIME type for the file. By default,
      it always returns 'text/plain'.

   .. method:: get_submit_parameter_help()<commit_msg>Give more information about MIME types.<commit_after>.. highlight:: rest

The :mod:`saliweb::frontend` Perl module
========================================

This module provides Perl functions and classes useful for implementing
the web frontend.

.. class:: saliwebfrontend(config_file, version, server_name)

   The main class used by the frontend. Typically a web service will subclass
   this class and override one or more methods to actually implement the
   web interface. The class creates a Perl CGI object which can be used to
   actually output web pages, and provides methods that behave similarly to
   the corresponding methods in CGI.pm, such as
   :meth:`~saliwebfrontend.start_html`.

   .. attribute:: htmlroot

      The top-level URL under which all static web files (HTML, style sheets,
      images) are found (read-only).

   .. attribute:: cgiroot

      The top-level URL under which all CGI scripts are found (read-only).

   .. attribute:: http_status

      The HTTP status code (e.g. 200 OK, 404 Not Found) that will be
      reported when the web page is printed.

   .. attribute:: version

      The version number of this web service (read-only).

   .. attribute:: user_name

      If a user is authenticated against the service, this is their user
      name; otherwise, it is undef (read-only).

   .. attribute:: email

      If a user is authenticated against the service, this is their email
      address; otherwise, it is undef (read-only).

   .. attribute:: modeller_key

      If a user is authenticated against the service and has already provided
      a MODELLER key, this is it; otherwise, it is undef (read-only).

   .. attribute:: cgi

      A pointer to the CGI.pm object used to display HTML (read-only).

   .. attribute:: dbh

      The database handle.

   .. attribute:: index_url
                  submit_url
                  queue_url
                  help_url
                  faq_url
                  links_url
                  about_url
                  news_url
                  contact_url
                  results_url
                  download_url

      Absolute URLs to each web page (read-only).

   .. method:: get_header_page_title()

      Return the HTML fragment used to display the page title inside a div in
      the page header. By default, this just displays the lab logo and the page
      title, but can be overridden if desired.

   .. method:: get_lab_navigation_links()

      Return a reference to a list of lab resources and services, used by
      :meth:`~saliwebfrontend.get_header`. This can be overridden in
      subclasses to add additional links.

   .. method:: get_navigation_links()

      Return a reference to a list of navigation links, used by
      :meth:`~saliwebfrontend.get_header`. This should be overridden for each
      service to add links to pages to submit jobs, show help, list jobs
      in the queue, etc.

   .. method:: get_project_menu()

      Return an HTML fragment which will be displayed in a project menu,
      used by :meth:`~saliwebfrontend.get_header`. This can contain general
      information about the service, links, etc., and should be overridden
      for each service.

   .. method:: display_index_page()
               display_submit_page()
               display_queue_page()
               display_help_page()
               display_results_page()
               display_download_page()

      Convenience methods designed to be called from CGI scripts. Each displays
      a complete web page by calling :meth:`~saliwebfrontend.start_html`,
      :meth:`~saliwebfrontend.get_header`, :meth:`~saliwebfrontend.get_footer`,
      and :meth:`~saliwebfrontend.end_html`. The actual page content is obtained
      from a similarly named get_*_page() method; for example,
      :meth:`~saliwebfrontend.display_index_page` calls
      :meth:`~saliwebfrontend.get_index_page`.
      Each method also calls :meth:`~saliwebfrontend.check_page_access` to
      check whether access to the page is permitted.

   .. method:: get_index_page()

      Return the HTML content of the index page. This is empty by default, and
      must be overridden for each web service. Typically this will display a
      form for user input (multi-page input can be supported if intermediate
      values are passed between pages).

   .. method:: get_submit_page()

      Return the HTML content of the submit page (that shown when a job is
      submitted to the backend). This is empty by default, and
      must be overridden for each web service. Typically this method will
      perform checks on the input data (throwing an
      :exc:`~saliweb::frontend.InputValidationError`
      to report any problems), then call :meth:`~saliwebfrontend.make_job`
      and its own :meth:`~saliweb::frontend.IncomingJob.submit` method to
      actually submit the job to the cluster, then point the user to the URL
      where job results can be obtained.
      
   .. method:: get_results_page(job)

      Return the HTML content of the results page (that shown when the user
      tries to view job results). It is passed a
      :class:`~saliweb::frontend.CompletedJob` object
      that contains information such as the name of the job and the time
      at which job results will be removed, and is run in the job's directory.
      This method is empty by default, and
      must be overridden for each web service. Typically this method will
      display any job failures (e.g. log files), display the job results
      directly, or provide a set of links to allow result files to be
      downloaded. In the last case, these URLs are simply the main results
      URL with an additional 'file' parameter that gives the file name;
      see :meth:`~saliwebfrontend.allow_file_download` and
      :meth:`~saliwebfrontend.get_file_mime_type`.

   .. method:: get_queue_page()

      Return the HTML content of the queue page. By default this simply shows
      all jobs in the queue in date order, plus some basic help text. (Note that
      there is currently no interface defined to do this any differently. If
      you need to customize the queue page, please talk to Ben so we can design
      a suitable interface.)

   .. method:: get_help_page(type)

      Return the HTML content of help, contact, FAQ, links, about, or news
      pages; the passed *type* parameter will be *help*, *contact*, *faq*,
      *links*, *about*, or *news*. By default
      this simply displays a suitable text file installed as part of the web
      service in the ``txt`` directory, named ``help.txt``, ``contact.txt``,
      ``faq.txt``, ``links.txt``, ``about.txt``, or ``news.txt`` respectively.

   .. method:: get_download_page()

      Return the HTML content of the download page. This is empty by default.
   .. method:: check_page_access(page_type)

      Check whether access to the given *page_type* is allowed. *page_type*
      is one of 'index', 'submit', 'queue', 'results', 'help', 'download'.
      It should simply return if access is allowed, or throw an
      :exc:`~saliweb::frontend.AccessDeniedError` exception if access is not
      permitted. By default, it simply returns, allowing all access.

   .. method:: allow_file_download(file)

      When downloading a results file (see
      :meth:`~saliwebfrontend.get_results_page`) this
      method is called to check whether the file is allowed to be downloaded,
      and should return true if it is. (For example, the job results directory
      may contain intermediate output files that should not be downloaded for
      efficiency or security reasons.) By default, this method always returns
      true.

   .. method:: get_file_mime_type(file)

      When downloading a results file (see
      :meth:`~saliwebfrontend.get_results_page`) this
      method is called to get the correct
      `MIME type <http://en.wikipedia.org/wiki/Internet_media_type`_
      for the file. By default, it always returns 'text/plain'. You may need
      to override this, for example, if some of your results files are tar
      files ('application/x-tar') or PNG images ('image/png').

   .. method:: get_submit_parameter_help()
{'fraction_non_alphanumeric': 0.0737877288471054, 'fraction_numerical': 0.0007422068283028204, 'mean_word_length': 2.813443396226415, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 24, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2098160', 'n_tokens_mistral': 4329, 'n_tokens_neox': 4103, 'n_words': 1933}