Debian Codegraph @

manual/snippets.rst

raw
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.