doc/bookmarks.rst

   1 .. _bookmarks:
   2
   3 Bookmarks
   4 =========
   5
   6 .. note::
   7
   8     You need to have configured the :ref:`linked-tables` for using bookmarks
   9     feature.
  10
  11 Storing bookmarks
  12 -----------------
  13
  14 Any query that is executed can be marked as a bookmark on the page
  15 where the results are displayed. You will find a button labeled
  16 :guilabel:`Bookmark this query` just at the end of the page. As soon as you have
  17 stored a bookmark, that query is linked to the database.
  18 You can now access a bookmark dropdown on each page where the query box appears on for that database.
  19
  20 Variables inside bookmarks
  21 --------------------------
  22
  23 Inside a query, you can also add placeholders for variables.
  24 This is done by inserting into the query SQL comments between ``/*`` and
  25 ``*/``. The special string ``[VARIABLE{variable-number}]`` is used inside the comments.
  26 Be aware that the whole query minus the SQL comments must be
  27 valid by itself, otherwise you won't be able to store it as a bookmark.
  28 Also, note that the text 'VARIABLE' is case-sensitive.
  29
  30 When you execute the bookmark, everything typed into the *Variables*
  31 input boxes on the query box page will replace the strings ``/*[VARIABLE{variable-number}]*/`` in
  32 your stored query.
  33
  34 Also remember, that everything else inside the ``/*[VARIABLE{variable-number}]*/`` string for
  35 your query will remain the way it is, but will be stripped of the ``/**/``
  36 chars. So you can use:
  37
  38 .. code-block:: mysql
  39
  40     /*, [VARIABLE1] AS myname */
  41
  42 which will be expanded to
  43
  44 .. code-block:: mysql
  45
  46     , VARIABLE1 as myname
  47
  48 in your query, where VARIABLE1 is the string you entered in the Variable 1 input box.
  49
  50 A more complex example, say you have stored this query:
  51
  52 .. code-block:: mysql
  53
  54     SELECT Name, Address FROM addresses WHERE 1 /* AND Name LIKE '%[VARIABLE1]%' */
  55
  56 If you wish to enter "phpMyAdmin" as the variable for the stored query, the full
  57 query will be:
  58
  59 .. code-block:: mysql
  60
  61     SELECT Name, Address FROM addresses WHERE 1 AND Name LIKE '%phpMyAdmin%'
  62
  63 **NOTE THE ABSENCE OF SPACES** inside the ``/**/`` construct. Any spaces
  64 inserted there will be later also inserted as spaces in your query and may lead
  65 to unexpected results especially when using the variable expansion inside of a
  66 "LIKE ''" expression.
  67
  68 Browsing a table using a bookmark
  69 ---------------------------------
  70
  71 When a bookmark has the same name as the table, it will be used as the query when browsing
  72 this table.
  73
  74 .. seealso::
  75
  76     :ref:`faqbookmark`,
  77     :ref:`faq6_22`