path: root/docs/dev/templates.rst

.. _simple theme templates:

======================
Simple Theme Templates
======================

The simple template is complex, it consists of many different elements and also
uses macros and include statements.  The following is a rough overview that we
would like to give the developer at hand, details must still be taken from the
:origin:`sources <searx/templates/simple/>`.

A :ref:`result item <result types>` can be of different media types.  The media
type of a result is defined by the :py:obj:`result_type.Result.template`.  To
set another media-type as :ref:`template default`, the field ``template``
in the result item must be set to the desired type.

.. contents:: Contents
   :depth: 2
   :local:
   :backlinks: entry


.. _result template macros:

Result template macros
======================

.. _macro result_header:

``result_header``
-----------------

Execpt ``image.html`` and some others this macro is used in nearly all result
types in the :ref:`main result list`.

Fields used in the template :origin:`macro result_header
<searx/templates/simple/macros.html>`:

url :  :py:class:`str`
  Link URL of the result item.

title :  :py:class:`str`
  Link title of the result item.

img_src, thumbnail : :py:class:`str`
  URL of a image or thumbnail that is displayed in the result item.


.. _macro result_sub_header:

``result_sub_header``
---------------------

Execpt ``image.html`` and some others this macro is used in nearly all result
types in the :ref:`main result list`.

Fields used in the template :origin:`macro result_sub_header
<searx/templates/simple/macros.html>`:

publishedDate : :py:obj:`datetime.datetime`
  The date on which the object was published.

length: :py:obj:`time.struct_time`
  Playing duration in seconds.

views: :py:class:`str`
  View count in humanized number format.

author : :py:class:`str`
  Author of the title.

metadata : :py:class:`str`
  Miscellaneous metadata.


.. _engine_data:

``engine_data_form``
--------------------

The ``engine_data_form`` macro is used in :origin:`results,html
<searx/templates/simple/results.html>` in a HTML ``<form/>`` element.  The
intention of this macro is to pass data of a engine from one :py:obj:`response
<searx.engines.demo_online.response>` to the :py:obj:`searx.search.SearchQuery`
of the next :py:obj:`request <searx.engines.demo_online.request>`.

To pass data, engine's response handler can append result items of typ
``engine_data``.  This is by example used to pass a token from the response to
the next request:

.. code:: python

   def response(resp):
       ...
       results.append({
          'engine_data': token,
          'key': 'next_page_token',
       })
       ...
       return results

   def request(query, params):
       page_token = params['engine_data'].get('next_page_token')


.. _main result list:

Main Result List
================

The **media types** of the **main result type** are the template files in
the :origin:`result_templates <searx/templates/simple/result_templates>`.

.. _template default:

``default.html``
----------------

Displays result fields from:

- :ref:`macro result_header` and
- :ref:`macro result_sub_header`

Additional fields used in the :origin:`default.html
<searx/templates/simple/result_templates/default.html>`:

content :  :py:class:`str`
  General text of the result item.

iframe_src : :py:class:`str`
  URL of an embedded ``<iframe>`` / the frame is collapsible.

audio_src : uri,
  URL of an embedded ``<audio controls>``.


.. _template images:

``images.html``
---------------

The images are displayed as small thumbnails in the main results list.

title :  :py:class:`str`
  Title of the image.

thumbnail_src : :py:class:`str`
  URL of a preview of the image.

resolution :py:class:`str`
  The resolution of the image (e.g. ``1920 x 1080`` pixel)


Image labels
~~~~~~~~~~~~

Clicking on the preview opens a gallery view in which all further metadata for
the image is displayed.  Addition fields used in the :origin:`images.html
<searx/templates/simple/result_templates/images.html>`:

img_src : :py:class:`str`
  URL of the full size image.

content:  :py:class:`str`
  Description of the image.

author:  :py:class:`str`
  Name of the author of the image.

img_format : :py:class:`str`
  The format of the image (e.g. ``png``).

source : :py:class:`str`
  Source of the image.

filesize: :py:class:`str`
  Size of bytes in :py:obj:`human readable <searx.humanize_bytes>` notation
  (e.g. ``MB`` for 1024 \* 1024 Bytes filesize).

url : :py:class:`str`
  URL of the page from where the images comes from (source).


.. _template videos:

``videos.html``
---------------

Displays result fields from:

- :ref:`macro result_header` and
- :ref:`macro result_sub_header`

Additional fields used in the :origin:`videos.html
<searx/templates/simple/result_templates/videos.html>`:

iframe_src : :py:class:`str`
  URL of an embedded ``<iframe>`` / the frame is collapsible.

  The videos are displayed as small thumbnails in the main results list, there
  is an additional button to collaps/open the embeded video.

content :  :py:class:`str`
  Description of the code fragment.


.. _template torrent:

``torrent.html``
----------------

.. _magnet link: https://en.wikipedia.org/wiki/Magnet_URI_scheme
.. _torrent file: https://en.wikipedia.org/wiki/Torrent_file

Displays result fields from:

- :ref:`macro result_header` and
- :ref:`macro result_sub_header`

Additional fields used in the :origin:`torrent.html
<searx/templates/simple/result_templates/torrent.html>`:

magnetlink:
  URL of the `magnet link`_.

torrentfile
  URL of the `torrent file`_.

seed : ``int``
  Number of seeders.

leech : ``int``
  Number of leecher

filesize : ``int``
  Size in Bytes (rendered to human readable unit of measurement).

files : ``int``
  Number of files.


.. _template map:

``map.html``
------------

.. _GeoJSON: https://en.wikipedia.org/wiki/GeoJSON
.. _Leaflet: https://github.com/Leaflet/Leaflet
.. _bbox: https://wiki.openstreetmap.org/wiki/Bounding_Box
.. _HTMLElement.dataset: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset
.. _Nominatim: https://nominatim.org/release-docs/latest/
.. _Lookup: https://nominatim.org/release-docs/latest/api/Lookup/
.. _place_id is not a persistent id:
    https://nominatim.org/release-docs/latest/api/Output/#place_id-is-not-a-persistent-id
.. _perma_id: https://wiki.openstreetmap.org/wiki/Permanent_ID
.. _country code: https://wiki.openstreetmap.org/wiki/Country_code

Displays result fields from:

- :ref:`macro result_header` and
- :ref:`macro result_sub_header`

Additional fields used in the :origin:`map.html
<searx/templates/simple/result_templates/map.html>`:

content :  :py:class:`str`
  Description of the item.

address_label : :py:class:`str`
  Label of the address / default ``_('address')``.

geojson : GeoJSON_
  Geometries mapped to HTMLElement.dataset_ (``data-map-geojson``) and used by
  Leaflet_.

boundingbox : ``[ min-lon, min-lat, max-lon, max-lat]``
  A bbox_ area defined by min longitude , min latitude , max longitude and max
  latitude.  The bounding box is mapped to HTMLElement.dataset_
  (``data-map-boundingbox``) and is used by Leaflet_.

longitude, latitude : :py:class:`str`
  Geographical coordinates, mapped to HTMLElement.dataset_ (``data-map-lon``,
  ``data-map-lat``) and is used by Leaflet_.

address : ``{...}``
  A dicticonary with the address data:

  .. code:: python

     address = {
         'name'          : str,  # name of object
         'road'          : str,  # street name of object
         'house_number'  : str,  # house number of object
         'postcode'      : str,  # postcode of object
         'country'       : str,  # country of object
         'country_code'  : str,
         'locality'      : str,
     }

  country_code : :py:class:`str`
    `Country code`_ of the object.

  locality : :py:class:`str`
    The name of the city, town, township, village, borough, etc. in which this
    object is located.

links : ``[link1, link2, ...]``
  A list of links with labels:

  .. code:: python

     links.append({
         'label'       : str,
         'url'         : str,
         'url_label'   : str,  # set by some engines but unused (oscar)
     })

data : ``[data1, data2, ...]``
  A list of additional data, shown in two columns and containing a label and
  value.

  .. code:: python

     data.append({
        'label'   : str,
        'value'   : str,
        'key'     : str,  # set by some engines but unused
     })

type : :py:class:`str`  # set by some engines but unused (oscar)
  Tag label from :ref:`OSM_KEYS_TAGS['tags'] <update_osm_keys_tags.py>`.

type_icon : :py:class:`str`  # set by some engines but unused (oscar)
  Type's icon.

osm : ``{...}``
  OSM-type and OSM-ID, can be used to Lookup_ OSM data (Nominatim_). There is
  also a discussion about "`place_id is not a persistent id`_" and the
  perma_id_.

  .. code:: python

     osm = {
         'type': str,
         'id':   str,
     }

  type : :py:class:`str`
    Type of osm-object (if OSM-Result).

  id :
    ID of osm-object (if OSM-Result).

  .. hint::

     The ``osm`` property is set by engine ``openstreetmap.py``, but it is not
     used in the ``map.html`` template yet.



.. _template paper:

``paper.html``
--------------

.. _BibTeX format: https://www.bibtex.com/g/bibtex-format/
.. _BibTeX field types: https://en.wikipedia.org/wiki/BibTeX#Field_types

Displays result fields from:

- :ref:`macro result_header`

Additional fields used in the :origin:`paper.html
<searx/templates/simple/result_templates/paper.html>`:

content :  :py:class:`str`
  An abstract or excerpt from the document.

comments : :py:class:`str`
  Free text display in italic below the content.

tags : :py:class:`List <list>`\ [\ :py:class:`str`\ ]
  Free tag list.

type : :py:class:`str`
  Short description of medium type, e.g. *book*, *pdf* or *html* ...

authors : :py:class:`List <list>`\ [\ :py:class:`str`\ ]
  List of authors of the work (authors with a "s" suffix, the "author" is in the
  :ref:`macro result_sub_header`).

editor : :py:class:`str`
  Editor of the book/paper.

publisher : :py:class:`str`
  Name of the publisher.

journal : :py:class:`str`
  Name of the journal or magazine the article was published in.

volume : :py:class:`str`
  Volume number.

pages : :py:class:`str`
  Page range where the article is.

number : :py:class:`str`
  Number of the report or the issue number for a journal article.

doi : :py:class:`str`
  DOI number (like ``10.1038/d41586-018-07848-2``).

issn : :py:class:`List <list>`\ [\ :py:class:`str`\ ]
  ISSN number like ``1476-4687``

isbn : :py:class:`List <list>`\ [\ :py:class:`str`\ ]
  ISBN number like ``9780201896831``

pdf_url : :py:class:`str`
  URL to the full article, the PDF version

html_url : :py:class:`str`
  URL to full article, HTML version


.. _template packages:

``packages``
------------

Displays result fields from:

- :ref:`macro result_header`

Additional fields used in the :origin:`packages.html
<searx/templates/simple/result_templates/packages.html>`:

package_name : :py:class:`str`
  The name of the package.

version : :py:class:`str`
  The current version of the package.

maintainer : :py:class:`str`
  The maintainer or author of the project.

publishedDate : :py:class:`datetime <datetime.datetime>`
  Date of latest update or release.

tags : :py:class:`List <list>`\ [\ :py:class:`str`\ ]
  Free tag list.

popularity : :py:class:`str`
  The popularity of the package, e.g. rating or download count.

license_name : :py:class:`str`
  The name of the license.

license_url : :py:class:`str`
  The web location of a license copy.

homepage : :py:class:`str`
  The url of the project's homepage.

source_code_url: :py:class:`str`
  The location of the project's source code.

links : :py:class:`dict`
  Additional links in the form of ``{'link_name': 'http://example.com'}``


.. _template files:

``files.html``
--------------

Displays result fields from:

- :ref:`macro result_header` and
- :ref:`macro result_sub_header`

Additional fields used in the :origin:`code.html
<searx/templates/simple/result_templates/files.html>`:

filename, size, time: :py:class:`str`
  Filename, Filesize and Date of the file.

mtype : ``audio`` | ``video`` | :py:class:`str`
  Mimetype type of the file.

subtype : :py:class:`str`
  Mimetype / subtype of the file.

abstract : :py:class:`str`
  Abstract of the file.

author : :py:class:`str`
  Name of the author of the file

embedded : :py:class:`str`
  URL of an embedded media type (``audio`` or ``video``) / is collapsible.


.. _template products:

``products.html``
-----------------

Displays result fields from:

- :ref:`macro result_header` and
- :ref:`macro result_sub_header`

Additional fields used in the :origin:`products.html
<searx/templates/simple/result_templates/products.html>`:

content :  :py:class:`str`
  Description of the product.

price : :py:class:`str`
  The price must include the currency.

shipping : :py:class:`str`
  Shipping details.

source_country : :py:class:`str`
  Place from which the shipment is made.


.. _template answer results:

Answer results
==============

See :ref:`result_types.answer`

Suggestion results
==================

See :ref:`result_types.suggestion`

Correction results
==================

See :ref:`result_types.corrections`

Infobox results
===============

See :ref:`result_types.infobox`