diff --git a/doc/QueryShortcuts/doc.pdf b/doc/QueryShortcuts/doc.pdf deleted file mode 100644 index 0f7e46bb78b4f8c6cf7a30216cb9f507be747ad4..0000000000000000000000000000000000000000 Binary files a/doc/QueryShortcuts/doc.pdf and /dev/null differ diff --git a/doc/QueryShortcuts/doc.tex b/doc/QueryShortcuts/doc.tex deleted file mode 100644 index 4cd78391d1cda808dc9c332328d3a984ae5926d8..0000000000000000000000000000000000000000 --- a/doc/QueryShortcuts/doc.tex +++ /dev/null @@ -1,192 +0,0 @@ -\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} diff --git a/doc/QueryShortcuts/choose_edit.png b/src/doc/extension/images/choose_edit.png similarity index 100% rename from doc/QueryShortcuts/choose_edit.png rename to src/doc/extension/images/choose_edit.png diff --git a/doc/QueryShortcuts/create_shortcut.png b/src/doc/extension/images/create_shortcut.png similarity index 100% rename from doc/QueryShortcuts/create_shortcut.png rename to src/doc/extension/images/create_shortcut.png diff --git a/doc/QueryShortcuts/create_success.png b/src/doc/extension/images/create_success.png similarity index 100% rename from doc/QueryShortcuts/create_success.png rename to src/doc/extension/images/create_success.png diff --git a/doc/QueryShortcuts/delete_shortcuts.png b/src/doc/extension/images/delete_shortcuts.png similarity index 100% rename from doc/QueryShortcuts/delete_shortcuts.png rename to src/doc/extension/images/delete_shortcuts.png diff --git a/doc/QueryShortcuts/delete_success.png b/src/doc/extension/images/delete_success.png similarity index 100% rename from doc/QueryShortcuts/delete_success.png rename to src/doc/extension/images/delete_success.png diff --git a/doc/QueryShortcuts/edit_shortcut.png b/src/doc/extension/images/edit_shortcut.png similarity index 100% rename from doc/QueryShortcuts/edit_shortcut.png rename to src/doc/extension/images/edit_shortcut.png diff --git a/doc/QueryShortcuts/edit_success.png b/src/doc/extension/images/edit_success.png similarity index 100% rename from doc/QueryShortcuts/edit_success.png rename to src/doc/extension/images/edit_success.png diff --git a/doc/QueryShortcuts/shortcut_toolbox.png b/src/doc/extension/images/shortcut_toolbox.png similarity index 100% rename from doc/QueryShortcuts/shortcut_toolbox.png rename to src/doc/extension/images/shortcut_toolbox.png diff --git a/src/doc/extension/query_templates.rst b/src/doc/extension/query_templates.rst new file mode 100644 index 0000000000000000000000000000000000000000..015d26a21fe20bc09dc97db9c7a3e7a1ca58a0b3 --- /dev/null +++ b/src/doc/extension/query_templates.rst @@ -0,0 +1,216 @@ +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()