diff options
Diffstat (limited to 'docs/dev/templates.rst')
| -rw-r--r-- | docs/dev/templates.rst | 577 |
1 files changed, 577 insertions, 0 deletions
diff --git a/docs/dev/templates.rst b/docs/dev/templates.rst new file mode 100644 index 000000000..b62c6b732 --- /dev/null +++ b/docs/dev/templates.rst @@ -0,0 +1,577 @@ +.. _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 developerat 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 code: + +``code.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/code.html>`: + +content : :py:class:`str` + Description of the code fragment. + +codelines : ``[line1, line2, ...]`` + Lines of the code fragment. + +code_language : :py:class:`str` + Name of the code language, the value is passed to + :py:obj:`pygments.lexers.get_lexer_by_name`. + +repository : :py:class:`str` + URL of the repository of the code fragment. + + +.. _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` |