| 1 |
Snippets |
| 2 |
======================== |
| 3 |
|
| 4 |
.. |ct| replace:: ``Control+J`` |
| 5 |
|
| 6 |
The calibre E-book editor supports *snippets*. A snippet is a |
| 7 |
piece of text that is either re-used often or contains a lot of redundant |
| 8 |
text. The editor allows you to insert a snippet with only a few key strokes. |
| 9 |
For example, suppose you often find yourself inserting link tags when editing |
| 10 |
HTML files, then you can simply type ``<a`` in the editor and press |
| 11 |
|ct|. The editor will expand it to:: |
| 12 |
|
| 13 |
<a href="filename"></a> |
| 14 |
|
| 15 |
Not only that, the word ``filename`` will be selected, with the cursor placed over |
| 16 |
it, so that you can easily type in the real filename, using the editor's nifty |
| 17 |
:ref:`editor_auto_complete` feature. And once you are done typing the filename, |
| 18 |
press |ct| again and the cursor will jump to the position in between the |
| 19 |
``<a>`` tags so you can easily type in the text for the link. |
| 20 |
|
| 21 |
The snippets system in the editor is very sophisticated, there are a few |
| 22 |
built-in snippets and you can create your own to suit your editing style. |
| 23 |
|
| 24 |
The following discussion of the built-in snippets should help illustrate the |
| 25 |
power of the snippets system. |
| 26 |
|
| 27 |
.. note:: |
| 28 |
You can also use snippets in the text entry fields in the :guilabel:`Search & replace` |
| 29 |
panel, however, placeholders (using |ct| to jump around) will not |
| 30 |
work. |
| 31 |
|
| 32 |
The built-in snippets |
| 33 |
------------------------ |
| 34 |
|
| 35 |
The built-in snippets are described below. Note that you can override them by |
| 36 |
creating your own snippets with the same trigger text. |
| 37 |
|
| 38 |
Inserting filler text [Lorem] |
| 39 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 40 |
|
| 41 |
The first built-in snippet, and the simplest is used to insert filler text into |
| 42 |
a document. The filler text is taken from `De finibus bonorum et malorum |
| 43 |
<https://en.wikipedia.org/wiki/De_finibus_bonorum_et_malorum>`_ a philosophical |
| 44 |
work by Cicero (translated to English). To use it simply type ``Lorem`` in an |
| 45 |
HTML file and press |ct|. It will be replaced by a couple of paragraphs of |
| 46 |
filler. |
| 47 |
|
| 48 |
The definition of this snippet is very simple, the trigger text is defined as |
| 49 |
``Lorem`` and the template is defined simply as the literal text to be |
| 50 |
inserted. You can easily customize it to use your favorite form of filler text. |
| 51 |
|
| 52 |
Inserting a self-closing HTML tag [<>] |
| 53 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 54 |
|
| 55 |
Now let's look at a simple example of the powerful concept of *placeholders*. |
| 56 |
Say you want to insert the self-closing tag ``<hr/>``. Just type ``<>``, and |
| 57 |
press |ct|, the editor will expand the snippet to:: |
| 58 |
|
| 59 |
<|/> |
| 60 |
|
| 61 |
Here, the ``|`` symbol represents the current cursor position. You can then |
| 62 |
type ``hr`` and press |ct| to move the cursor to after the end of the tag. |
| 63 |
This snippet is defined as:: |
| 64 |
|
| 65 |
Trigger: <> |
| 66 |
Template: <$1/>$2 |
| 67 |
|
| 68 |
Placeholders are simply the dollar ($) sign followed by a number. When the |
| 69 |
snippet is expanded by pressing |ct| the cursor is positioned at the first |
| 70 |
placeholder (the placeholder with the lowest number). When you press |ct| again |
| 71 |
the cursor jumps to the next placeholder (the placeholder with the next higher |
| 72 |
number). |
| 73 |
|
| 74 |
Inserting an HTML link tag [<a] |
| 75 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 76 |
|
| 77 |
HTML link tags all share a common structure. They have an ``href`` attribute and |
| 78 |
some text between the opening and closing tags. A snippet to make typing them |
| 79 |
more efficient will introduce us to some more features of placeholders. To use |
| 80 |
this snippet, simply type ``<a`` and press |ct|. The editor will expand this |
| 81 |
to:: |
| 82 |
|
| 83 |
<a href="filename|"></a> |
| 84 |
|
| 85 |
Not only that, the word ``filename`` will be selected, with the cursor placed |
| 86 |
over it, so that you can easily type in the real filename, using the editor's |
| 87 |
nifty :ref:`editor_auto_complete` feature. And once you are done typing the |
| 88 |
filename, press |ct| again and the cursor will jump to the position in between |
| 89 |
the ``<a>`` tags so you can easily type in the text for the link. After you are |
| 90 |
done typing the text, press |ct| again to jump to the point after the closing |
| 91 |
tag. This snippet is defined as:: |
| 92 |
|
| 93 |
Trigger: <a |
| 94 |
Template: <a href="${1:filename}">${2*}</a>$3 |
| 95 |
|
| 96 |
There are a couple of new features here. First the ``$1`` placeholder has |
| 97 |
become more complex. It now includes some *default text* (the word |
| 98 |
``filename``). If a placeholder contains default text, the default text is |
| 99 |
substituted for the placeholder when the snippet is expanded. Also when you |
| 100 |
jump to a placeholder with default text using |ct|, the default text is |
| 101 |
selected. In this way, you can use default text to act as a reminder to you to |
| 102 |
fill in important parts of the template. You can specify default text for a |
| 103 |
placeholder by using the syntax: ``${<number>:default text}``. |
| 104 |
|
| 105 |
The other new feature is that the second placeholder has an asterisk after it |
| 106 |
(``${2*}``). This means that any text that was selected before expanding the |
| 107 |
template is substituted for the placeholder. To see this in action, select some |
| 108 |
text in the editor, press |ct|, type ``<a`` and press |ct| again, the template |
| 109 |
will be expanded to:: |
| 110 |
|
| 111 |
<a href="filename">whatever text you selected</a> |
| 112 |
|
| 113 |
Inserting an HTML image tag [<i] |
| 114 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 115 |
|
| 116 |
This is very similar to inserting an HTML link, as we saw above. It allows you |
| 117 |
to quickly input an ``<img src="filename" alt="description" />`` tag and jump |
| 118 |
between the ``src`` and ``alt`` attributes:: |
| 119 |
|
| 120 |
Trigger: <i |
| 121 |
Template: <img src="${1:filename}" alt="${2*:description}" />$3 |
| 122 |
|
| 123 |
Insert an arbitrary HTML tag [<<] |
| 124 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 125 |
|
| 126 |
This allows you to insert an arbitrary full HTML tag (or wrap previously |
| 127 |
selected text in the tag). To use it, simply type ``<<`` and press |ct|. |
| 128 |
If you want to wrap selected text, first select the text, press |ct| then |
| 129 |
type ``<<`` and press |ct| again. |
| 130 |
The editor will expand it to:: |
| 131 |
|
| 132 |
<|></> |
| 133 |
|
| 134 |
Type the tag name, for example: ``span`` and press |ct|, that will result in:: |
| 135 |
|
| 136 |
<span>|</span> |
| 137 |
|
| 138 |
You will note that the closing tag has been automatically filled with ``span``. |
| 139 |
This is achieved with yet another feature of placeholders, *mirroring*. |
| 140 |
Mirroring simply means that if you specify the same placeholder more than |
| 141 |
once in a template, the second and all later positions will be automatically |
| 142 |
filled in with whatever you type in the first position, when you press |ct|. |
| 143 |
The definition for this snippet is:: |
| 144 |
|
| 145 |
Trigger: << |
| 146 |
Template: <$1>${2*}</$1>$3 |
| 147 |
|
| 148 |
As you can see, the first placeholder ($1) has been specified twice, the second |
| 149 |
time in the closing tag, which will simply copy whatever you type in the |
| 150 |
opening tag. |
| 151 |
|
| 152 |
Inserting an arbitrary HTML tag with a class attribute [<c] |
| 153 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 154 |
|
| 155 |
This is very similar to the insert arbitrary tag example above, except that it |
| 156 |
assumes that you want to specify a class for the tag:: |
| 157 |
|
| 158 |
Trigger: <c |
| 159 |
Template: <$1 class="${2:classname}">${3*}</$1>$4 |
| 160 |
|
| 161 |
This will allow you to first type the tag name, press |ct|, type the class |
| 162 |
name, press |ct| type the contents of the tag and press |ct| one last time to |
| 163 |
jump out of the tag. The closing tag will be auto-filled. |
| 164 |
|
| 165 |
|
| 166 |
Creating your own snippets |
| 167 |
---------------------------- |
| 168 |
|
| 169 |
Snippets really shine because you can create your own to suit your editing |
| 170 |
style. To create your own snippets go to :guilabel:`Edit->Preferences->Editor |
| 171 |
settings->Manage snippets` in the editor. This will pop-up an easy to use |
| 172 |
dialog to help you create your own snippets. Simply click the :guilabel:`Add |
| 173 |
snippet` button and you will see a dialog that looks like: |
| 174 |
|
| 175 |
.. image:: images/snippets-editor.png |
| 176 |
:alt: The create your own snippets tool |
| 177 |
:align: center |
| 178 |
:class: fit-img |
| 179 |
|
| 180 |
First give your snippet a name, something descriptive, to help identify the |
| 181 |
snippet in the future. Then specify the *trigger*. A trigger is simply the text |
| 182 |
that you have to type in the editor before pressing |ct| in order to expand the |
| 183 |
snippet. |
| 184 |
|
| 185 |
Then specify the snippet template. You should start with one of the examples |
| 186 |
above and modify it to suit your needs. Finally, specify which file types you |
| 187 |
want the snippet to be active for. This way you can have multiple snippets with |
| 188 |
the same trigger text that work differently in different file types. |
| 189 |
|
| 190 |
The next step is to test your newly created snippet. Use the :guilabel:`Test` |
| 191 |
box at the bottom. Type in the trigger text and press |ct| to expand the |
| 192 |
snippet and jump between placeholders. |