Skip to content
Snippets Groups Projects
Commit b2267eb4 authored by Alexander Schlemmer's avatar Alexander Schlemmer
Browse files

DOC: converted pdf doc for query templates into standard doc and added a few additional sections

parent b7113bfb
No related branches found
No related tags found
2 merge requests!47Release v0.4.0,!39DOC: converted pdf doc for query templates into standard doc and added a few additional sections
Pipeline #12962 passed
Stage: linting
Stage: test
Stage: deploy
Show whitespace changes
Inline Side-by-side
Showing
with 216 additions and 192 deletions
doc/QueryShortcuts/doc.pdf deleted 100644 → 0
+ 0
− 0
View file @ b7113bfb
File deleted
doc/QueryShortcuts/doc.tex deleted 100644 → 0
+ 0
− 192
View file @ b7113bfb
\documentclass{article}
% General document formatting
\usepackage[margin=0.7in]{geometry}
\usepackage[parfill]{parskip}
\usepackage[utf8]{inputenc}
\usepackage{graphicx}
% Related to math
\usepackage{amsmath,amssymb,amsfonts,amsthm}
\title{Documentation Query Shortcuts}
\begin{document}
\maketitle
\section{Introduction}\label{introduction}
The WebUI supports the creation of query shortcuts which appear below
the normal query input field. These shortcuts facilitate looking for
data as query strings which are used frequently. They can be stored and
reused.
\begin{figure}[h]
\centering
\includegraphics[width=.8\textwidth]{shortcut_toolbox.png}
\caption{The Shortcuts in the Query Panel; Note the Toolbox for in the top
right}
\end{figure}
There are two ways to integrate query templates into the WebUI:
\begin{itemize}
\item
Global shortcuts are integrated by the webmaster only. They are
defined and stored in a\\
\texttt{./conf/ext/json/globale\_query\_shortcuts.json} in the root
directory of the webui.
\item
User-defined templates can be defined by users and are only visible
for the user who created them. In this sense, user-defined shortcuts
are also private, whereas global shortcuts are always publicly
visible.
\end{itemize}
\section{User-defined Query Shortcuts}\label{user-defined-query-shortcuts}
\subsection{Create a New Shortcut}\label{create-a-new-shortcut}
New Query Shortcuts can be generated by any authenticated user with
sufficient write permissions.
In the web interface, click \texttt{Query}. In the \texttt{Shortcuts}
section, click the wrench (on the right side).
In the drop-down menu, click \texttt{Create}.
It now opens a form with two input fields, \texttt{Description} and
\texttt{Query}.
\begin{figure}[h]
\centering
\includegraphics[width=.6\textwidth]{create_shortcut.png}
\caption{The view to create a new shortcut}
\end{figure}
See \ref{basic-shortcut} and
\ref{advanced-shortcut} for further
explanation of the components of a Query Shortcut.
Edit the fields and click \texttt{Submit} for the creation of the new
shortcut or click \texttt{Cancel} to cancel the process.
The new shortcut is shown in the shortcuts section.
\begin{figure}[h]
\centering
\includegraphics[width=.6\textwidth]{create_success.png}
\caption{The view when creation was successful}
\end{figure}
\subsection{Change an Existing Shortcut}\label{change-an-existing-shortcut}
Existing Query Shortcuts which are visible in your shortcuts section can
be edited directly in the shortcuts section.
In the web interface, click \texttt{Query}. In the \texttt{Shortcuts}
section, click the wrench (on the right side).
In the drop-down menu, click \texttt{Edit}.
\begin{figure}[h]
\centering
\includegraphics[width=.6\textwidth]{choose_edit.png}
\caption{Choosing which shortcut to edit}
\end{figure}
Every editable shortcut (note: global shortcuts are not editable in the
webinterface at all) will receive a new button \texttt{Edit}
Click \texttt{Edit} of the shortcut that is to be changed.
It now opens a form with two input fields, \texttt{Description} and
\texttt{Query}, pre-filled.
See \ref{basic-shortcut} and
\ref{advanced-shortcut} for further
explanation of the components of a Query Shortcut.
Edit the fields and click \texttt{Submit} for the creation of the new
shortcut or click \texttt{Cancel} to cancel the process.
The updated shortcut is shown in the shortcuts section.
See the
\subsection{Delete an Existing Shortcut}\label{delete-an-existing-shortcut}
Existing Query Shortcut which are visible in your shortcuts section can
be edited directly in the shortcuts section.
In the web interface, click \texttt{Query}. In the \texttt{Shortcuts}
section, click the wrench (on the right side).
In the drop-down menu, click \texttt{Delete}.
\begin{figure}[h]
\centering
\includegraphics[width=.6\textwidth]{delete_shortcuts.png}
\caption{Choosing which shortcuts to delete}
\end{figure}
Every user-defined shortcut (note: global shortcuts are not deletable in
the webinterface at all) will receive checkbox and \texttt{Delete} and
\texttt{Cancel} buttons appear at the bottom of the shortcuts section.
Check all shortcuts which are to be deleted and click \texttt{Delete} or
click \texttt{Cancel} to cancel the deletion.
All deleted shortcuts are marked as deleted afterwards and will not
appear again in the shortcuts section after reload.
\subsection{Basic Shortcut}\label{basic-shortcut}
The \texttt{Description} is a verbose definition of the query,
e.g.~``Search for experiments and return a table.''. It will be the text
that is visible in the shortcuts section.
The \texttt{Query} is the query that will be executed with the shortcut.
It adheres to the definition of the CaosDB Query Language (CQL).
The corresponding query of our example is
\texttt{SELECT\ date,\ name\ FROM\ Experiment}.
\subsection{Advanced Shortcut}\label{advanced-shortcut}
The basic shortcut does not allow for any parameterization. It is just a
plain string or like a bookmark.
Advanced shortcuts use a special syntax, where text placeholders are
used to define parameters of the shortcut. The parameters can be set by
the user at the time of the execution. An example can best illustrate
what that means:
Suppose you want to search for experiments by their year. The query for
that would be
\texttt{SELECT\ date,\ name\ FROM\ Experiment\ WITH\ date\ IN\ 2018}.
Now, the actual year in the query can be made editable by replacing the
year \texttt{2018} with \texttt{\{year\}}.
The \texttt{Description} now must also contain this placeholder
\texttt{\{year\}}, e.g.~``Search for experiements conducted in year
\{year\}''. When the shortcut is displayed in the shortcuts section
below the query input field, the placeholder is replaced by a text input
field and the user can insert a year and execute the shortcut with the
year being inserted into the query.
\subsubsection{Placeholders}\label{placeholders}
The placeholders have simple rules. A placeholder always starts and ends
with curly brackets, like in the example \texttt{\{year\}}. The text
inside the brackets (the placeholder's \emph{id}) may contain any
combination of alphanumeric signs (0-9,a-z,A-Z). The use of special
characters like colons, commas or the like is discouraged. They are
reserved for future extensions of the placeholders. Apart from that, you
are free to choose any placeholder \emph{id} that seems suitable for
you.
Both components of the query shortcut (description and query) must
contain the same set of placeholders, otherwise the query shortcuts
might not work as intended. If there is a \texttt{\{year\}} in the
query, there must be a \texttt{\{year\}} in the description.
Each placeholder \emph{id} must occur only once in both components -- if
you need to use two years in your shortcut you have to use
\texttt{\{year1\}} and \texttt{\{year2\}} or any other combinations of
placeholder \emph{ids}.
\end{document}
src/doc/extension/query_templates.rst 0 → 100644
+ 216
− 0
View file @ b2267eb4
Introduction
============
The WebUI supports the creation of query shortcuts which appear below
the normal query input field. These shortcuts facilitate looking for
data as query strings which are used frequently. They can be stored and
reused.
.. figure:: images/shortcut_toolbox.png
:alt: The Shortcuts in the Query Panel; Note the Toolbox for in the
top right
The Shortcuts in the Query Panel; Note the Toolbox for in the top
right
There are two ways to integrate query templates into the WebUI:
- | Global shortcuts are integrated by the webmaster only. They are
defined and stored in a
| ``./conf/ext/json/global_query_shortcuts.json`` in the root
directory of the webui. (See the example below.)
- User-defined templates can be defined by users and are only visible
for the user who created them. In this sense, user-defined shortcuts
are also private, whereas global shortcuts are always publicly
visible.
User-defined Query Shortcuts
============================
Create a New Shortcut
---------------------
New Query Shortcuts can be generated by any authenticated user with
sufficient write permissions.
In the web interface, click ``Query``. In the ``Shortcuts`` section,
click the wrench (on the right side).
In the drop-down menu, click ``Create``.
It now opens a form with two input fields, ``Description`` and
``Query``.
.. figure:: images/create_shortcut.png
:alt: The view to create a new shortcut
The view to create a new shortcut
See `2.4 <#basic-shortcut>`__ and `2.5 <#advanced-shortcut>`__ for
further explanation of the components of a Query Shortcut.
Edit the fields and click ``Submit`` for the creation of the new
shortcut or click ``Cancel`` to cancel the process.
The new shortcut is shown in the shortcuts section.
.. figure:: images/create_success.png
:alt: The view when creation was successful
The view when creation was successful
Change an Existing Shortcut
---------------------------
Existing Query Shortcuts which are visible in your shortcuts section can
be edited directly in the shortcuts section.
In the web interface, click ``Query``. In the ``Shortcuts`` section,
click the wrench (on the right side).
In the drop-down menu, click ``Edit``.
.. figure:: images/choose_edit.png
:alt: Choosing which shortcut to edit
Choosing which shortcut to edit
Every editable shortcut (note: global shortcuts are not editable in the
webinterface at all) will receive a new button ``Edit``
Click ``Edit`` of the shortcut that is to be changed.
It now opens a form with two input fields, ``Description`` and
``Query``, pre-filled.
See `2.4 <#basic-shortcut>`__ and `2.5 <#advanced-shortcut>`__ for
further explanation of the components of a Query Shortcut.
Edit the fields and click ``Submit`` for the creation of the new
shortcut or click ``Cancel`` to cancel the process.
The updated shortcut is shown in the shortcuts section.
See the
Delete an Existing Shortcut
---------------------------
Existing Query Shortcut which are visible in your shortcuts section can
be edited directly in the shortcuts section.
In the web interface, click ``Query``. In the ``Shortcuts`` section,
click the wrench (on the right side).
In the drop-down menu, click ``Delete``.
.. figure:: images/delete_shortcuts.png
:alt: Choosing which shortcuts to delete
Choosing which shortcuts to delete
Every user-defined shortcut (note: global shortcuts are not deletable in
the webinterface at all) will receive checkbox and ``Delete`` and
``Cancel`` buttons appear at the bottom of the shortcuts section.
Check all shortcuts which are to be deleted and click ``Delete`` or
click ``Cancel`` to cancel the deletion.
All deleted shortcuts are marked as deleted afterwards and will not
appear again in the shortcuts section after reload.
Basic Shortcut
--------------
The ``Description`` is a verbose definition of the query, e.g. “Search
for experiments and return a table.”. It will be the text that is
visible in the shortcuts section.
The ``Query`` is the query that will be executed with the shortcut. It
adheres to the definition of the CaosDB Query Language (CQL).
The corresponding query of our example is
``SELECT date, name FROM Experiment``.
Advanced Shortcut
-----------------
The basic shortcut does not allow for any parameterization. It is just a
plain string or like a bookmark.
Advanced shortcuts use a special syntax, where text placeholders are
used to define parameters of the shortcut. The parameters can be set by
the user at the time of the execution. An example can best illustrate
what that means:
Suppose you want to search for experiments by their year. The query for
that would be ``SELECT date, name FROM Experiment WITH date IN 2018``.
Now, the actual year in the query can be made editable by replacing the
year ``2018`` with ``{year}``.
The ``Description`` now must also contain this placeholder ``{year}``,
e.g. “Search for experiements conducted in year {year}”. When the
shortcut is displayed in the shortcuts section below the query input
field, the placeholder is replaced by a text input field and the user
can insert a year and execute the shortcut with the year being inserted
into the query.
Placeholders
~~~~~~~~~~~~
The placeholders have simple rules. A placeholder always starts and ends
with curly brackets, like in the example ``{year}``. The text inside the
brackets (the placeholder’s *id*) may contain any combination of
alphanumeric signs (0-9,a-z,A-Z). The use of special characters like
colons, commas or the like is discouraged. They are reserved for future
extensions of the placeholders. Apart from that, you are free to choose
any placeholder *id* that seems suitable for you.
Both components of the query shortcut (description and query) must
contain the same set of placeholders, otherwise the query shortcuts
might not work as intended. If there is a ``{year}`` in the query, there
must be a ``{year}`` in the description.
Each placeholder *id* must occur only once in both components – if you
need to use two years in your shortcut you have to use ``{year1}`` and
``{year2}`` or any other combinations of placeholder *ids*.
Example for global_query_shortcuts.json
---------------------------------------
The following example for the file global_query_shortcuts.json would create two global query shortcuts for finding experiments. The second example includes a variable for specifying the year.
.. code-block:: json
[
{
"description": "Show a list of all Experiments",
"query": "FIND Record Experiment"
},
{
"description": "Show a table of Experiments for year: {year}",
"query": "SELECT date, project, identifier FROM Record Experiment with date in {year}"
},
]
Data Model for User Query Templates
-----------------------------------
The current default data model for CaosDB does not include the RecordTypes which are needed for the user query templates. See https://gitlab.indiscale.com/caosdb/src/caosdb-webui/-/issues/104 for details.
The solution is to create the RecordTypes, e.g. using the Python interface, as follows:
.. code-block:: python
datamodel = caosdb.Container()
datamodel.extend([
caosdb.Property("Query", datatype=caosdb.TEXT),
caosdb.Property("templateDescription", datatype=caosdb.TEXT),
caosdb.RecordType(
"UserTemplate"
).add_property("Query", importance=caosdb.OBLIGATORY
).add_property("templateDescription", importance=caosdb.OBLIGATORY),
])
datamodel.insert()
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment