summaryrefslogtreecommitdiffstats
path: root/doc/quanta/working-with-quanta.docbook
blob: 54471778efed344ed47f06dfe66cfb2abe4b7e9d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
<?xml version="1.0" encoding="UTF-8" ?>

<chapter id="using-quanta-3-2">
<chapterinfo>
<title>Working With...</title>
<authorgroup>
<author>
<firstname>Robert</firstname>
<surname>Nickel</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
</author>
<author>
  <firstname>Andr&aacute;s</firstname>
  <surname>Mantia</surname>
  <affiliation>
    <address><email>[email protected]</email></address>
  </affiliation>
</author>

<othercredit role="reviewer">
<firstname>Christopher</firstname>
<surname>Hornbaker</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>

<othercredit role="reviewer">
<firstname>Fabrice</firstname>
<surname>Mous</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>
</chapterinfo>

<title>Working With...</title>

<para>
This chapter describes the parts of &quantaplus; that you will be
interacting with mostly. These not only make your more productive, but
they also allow you to customize &quantaplus; to your work-flow.
</para>

<sect1 id="toolbars-howto-3-2">
<title>Toolbars</title>

<para>
As previously mentioned, toolbars in &quantaplus; are primarily managed
through the <guimenu>Toolbars</guimenu> menu. Usage and creation are
somewhat different. The creation of toolbars is discussed in a later
section entitled <quote><link linkend="creating-toolbars-3-2">Creating
Toolbars</link>.</quote>
</para>

<para>
Using toolbars is quite simple. When you click on an icon for a desired
element or action, one of three possibilities occur: the element is
inserted (optionally with a closing element); an element dialog is
activated, allowing you to fill in the attributes in a dialog box; or,
lastly, an action is activated and does something nifty for your current
file or project. If you find yourself doing tedious and redundant typing
for a particular element, that is not in &quantaplus;, then you can add it.
See <xref linkend="dtep-intro-3-2" /> for more information.
</para>

<para>
Configuring the toolbars and the elements on it can be done either by
using the context menu (right click on a toolbar), where you can 
create a <guilabel>New Action</guilabel>, a <guilabel>New Toolbar</guilabel>, you can perform other actions like <guilabel>Remove Toolbar</guilabel>, <guilabel>Rename Toolbar</guilabel> or <guilabel>Configure Toolbars</guilabel>, which will get you the dialog where you can specify which actions should be visible on this or other toolbars.
</para>
<para>
  By invoking the context menu on an action (icon) placed to a toolbar, aside of the above actions you will see the <guilabel>Remove Action</guilabel> and <guilabel>Edit Action</guilabel> entries, which speak for themselves.
</para>
<para>
  The toolbars and the actions on them can be configured by using the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice> and <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Actions..</guimenuitem></menuchoice> menu entries.
</para>
<para>
  About the user definable actions you can read in <xref linkend="user-actions" />.
</para>

<para>
A tag dialog looks just like the following:

<mediaobject>
<imageobject>
<imagedata fileref="taginputex.png" format="PNG" />
</imageobject>
<caption><para>An example of a tag dialog.</para></caption>
</mediaobject>
</para>

<para>
The above image is the dialog for the anchor tag. If you know &HTML;/&XHTML;,
then you should have noticed that all the attributes that you can use, in
an anchor element, are available. Notice the tabs above for
<guilabel>Main</guilabel>, <guilabel>Core and i18n</guilabel>,
<guilabel>Events</guilabel>, and <guilabel>Focus</guilabel>, they hold
all of the other attributes, according to their purpose, available to the
anchor element. All you need do is: fill in the blanks for the attributes
you want in your anchor, omit the attributes you do not want, and click OK.
You now have a well formed anchor set down at the current cursor position.
</para>
</sect1>

&quanta-projects;

<sect1 id="templates-3-2">
<title>Templates</title>

<para>
Templates are basically skeleton documents, code snippets and files to
link to. &quantaplus; uses templates fundamentally as a standard file
system with enhanced organization and interfacing. You can copy, move or
link any repository currently on your system into the templates tree.
Think of &quantaplus; templates as having roughly the limitations to your
imagination that your file system has.
</para>

<para>
Templates exist in nested folders. There is no limit to how deep you
can nest them, however, within any given folder &quantaplus; expects a
consistent action for the base template type described below. Additionally
templates allow for pre and post text to be concatenated to non document
type templates. This facilitates tag creation. The next update after the
introduction is scheduled to add the ability to pass variables to the text
such as image size information to assist in tag creation.
</para>

<para>
Our goal with templates is to extend them to include multi file
<quote>concept</quote> templates useful for things like placing an order or
creating an about section. Ideally this will be a tool for making your
work more productive and dynamic. An eventual goal is to have a structural
template design mode to deal with site layout and structure which you
could use to design and interactively update your sites. If you would like
to be involved, check out our
<ulink url="http://quanta.sourceforge.net/main1.php?contfile=needs">help
wanted</ulink> page.
</para>

<important>
<para>
Some of the templates that ship with &quantaplus; have conditions for
their usage. Please read carefully the usage statement of conditions at
the top of each template before you use it.
</para>
</important>

<sect2 id="template-types-3-2">
<title>Template Types</title>

<para>
There are various template types supported by &quantaplus;.
These are:
</para>
<para>
<simplelist>
<member>Binary templates</member>
<member>Document templates</member>
<member>Text snippets</member>
<member>Site templates</member>
</simplelist>

Examples for these types are provided with &quantaplus;.
</para>
<variablelist>
<varlistentry>
<term>Binary templates</term>
<listitem>
<para>
Binaries are anything not identified purely in text. They can be any file,
except text, including images, &PDF;s, flash files, etc. Binary templates
are usually included in your document via links (&ie; images as
an <sgmltag class="starttag">img src=/src/url</sgmltag>).
Some examples can be found in the Templates tree under Global Templates.
Please see <xref linkend="qit-3-2" /> for more information on the
<guilabel>Templates</guilabel> tree.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Document templates</term>
<listitem>
<para>
Documents can be any type of text document. You can create new documents
based on these templates. Generally you would want to nest
more specific or diverse documents in subfolders. Here you can make a
basic framework for what you do and deliver it to your work in an
organized fashion and realize much better efficiency. Some examples
can be found in the Templates tree under Global Templates.
Please see <xref linkend="qit-3-2" /> for more information on the
<guilabel>Templates</guilabel> tree.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Text snippets</term>
<listitem>
<para>
This type of template is useful when you don't want to create a new
document based on a template, but want to insert the same text area
over and over in your documents. They can contain anything, starting
with a comment and ending with a complete menu handling JavaScript
method or perl script. Some examples can be found in the Templates
tree under Global Templates.
Please see <xref linkend="qit-3-2" /> for more information on the
<guilabel>Templates</guilabel> tree.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Site templates</term>
<listitem>
<para>
As the name says these templates are useful to build a whole site
from a template. They are a collection of various documents which
can be organized in a directory structure, everything gathered in
a compressed tar archive. As of writing there are no example site
templates in &quantaplus;.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="template-scope-3-2">
<title>Template Scopes</title>

<para>
Templates are accessible based upon their established
<link linkend="quanta-workspaces-3-2">workspace</link> in &quantaplus;
</para>

</sect2>

<sect2 id="creating-templates-3-2">
<title>Creating Templates</title>

<sect3 id="creating-document-templates">
<title>Creating document templates</title>
<para>
Create a document structure that you love (&XML;, &HTML;, DocBook, &etc;.)
and click on
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as Template</guimenuitem>
<guimenuitem>Save as Local/Project Template</guimenuitem>
</menuchoice>.
</para>

<para>
Once this is done, you will notice that (even if it is saved as a Project
template) the template does <emphasis>not</emphasis> show in the project
tab view. Look into the templates view to find your template under the
Project templates tab.
</para>
</sect3>
<sect3 id="creating-text-templayes">
<title>Creating text snippets</title>
<para>Select some text in your document and click on
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as Template</guimenuitem>
<guimenuitem>Save Selection to Local/Project Template file</guimenuitem>
</menuchoice>.
Alternatively you can just use drag and drop to drag the selection to the <guilabel>Templates</guilabel> treeview.
</para>
</sect3>
<sect3 id="creating-binary-templates">
<title>Creating binary templates</title>
<para>Creation of a binary template is simple: just copy the file
into a template folder. You can use standard file management
functions to do it, like drag and drop or copy and paste from
Konqueror or the <guilabel>Files Tree</guilabel>.
</para>
</sect3>
<sect3 id="creating-site-templates">
<title>Creating site templates</title>
<para>
In the <guilabel>Files Tree</guilabel> or the <guilabel>Project Files</guilabel>
treeviews right click on a folder and select <guilabel>Create Site Template</guilabel>,
pick up a name for the template and save it. By default it will try
to save to the project template folder, but of course you can choose
to save it as a local or global template as well.
</para>
</sect3>
</sect2>

<sect2 id="using-templates-with-projects-3-2">
<title>Using Templates With Projects</title>

<para>
Project templates allow you to be more tightly focused. You can create
headers, footers or go dynamic with &PHP; include files and link them.
Additionally there are some very cool things we took into consideration
when using templates in projects.
</para>

<para>
When creating a project you can opt to copy to your local project, all the
existing global and user templates. Legacy project get default templating
abilities so nothing is lost You can choose where to locate your template
files so they can be in your server root and easy to upload or you can
make them secure to link to below server root which is a very cool trick.
When linking to a file not in the project templates you will be prompted
to copy the file to the project templates prior to linking. This will prevent
broken links on upload. You always have control where you place your
templates so you can choose to move them. However &quantaplus; does not
track this so you will need to change links.
</para>

</sect2>

<sect2 id="managing-templates-3-2">
<title>Managing Templates</title>

<para>
Template structure on the template tab is based on the files found in
<filename class="directory">
$<envar>TDEDIR</envar>/share/apps/quanta/templates</filename> and
<filename class="directory">
$<envar>HOME</envar>/.kde/share/apps/quanta/templates</filename>. Each of
these folders is specified as one of four types of container as explained <link linkend="template-types-3-2">above</link>.
</para>

<para>
To set the behavior of each folder, &RMB; click in the template view on
the folder and choose <guimenuitem>Properties</guimenuitem>. The
following dialog will come up:

<mediaobject>
<imageobject>
<imagedata fileref="template-rmb.png" format="PNG" />
</imageobject>
<caption><para>Properties dialog.</para></caption>
</mediaobject>
</para>

<variablelist>
<varlistentry>
<term><guilabel>Type</guilabel></term>

<listitem>
<para>
Drop down box with the three types discussed previously; files, text,
template. This box will be grayed out if you have the <guilabel>Inherit
parent attribute box</guilabel> checked.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Inherit parent attribute</guilabel> (<sgmltag
class="starttag">foo</sgmltag>)</term>
<listitem>
<para>
This is checked by default and is fine for all but the top level
folders in your templates tree. If the top level folder has this
checked, it will basically deactivate templates for that folder and all
that aren't explicitly set below it. If this is not a top level folder,
then the <sgmltag class="starttag">blah</sgmltag> will say something like
<literal>Text snippet</literal>. If it says nothing, then chances are that
you are on a top level folder.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Use pre/post text</guilabel></term>
<listitem>
<para>
Enables pre and post text for templates in this folder. This could be a
common header/footer for all of your templates for a given project and
then you copy content templates into that folder and have a complete
page with the custom header/footer as a starting point.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Pre-text</guilabel></term>
<listitem>
<para>
The actual text to insert before your templates content.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Post-text</guilabel></term>
<listitem>
<para>
The actual text to insert after your templates content.
</para>
</listitem>
</varlistentry>
</variablelist>
<!--<para>
The properties for a template file looks a bit different:
<mediaobject>
<imageobject>
<imagedata fileref="template-file-rmb.png" format="PNG" />
</imageobject>
<caption><para>Properties dialog.</para></caption>
</mediaobject>

</para>-->
<para>
Additionally if you look at your options with the &RMB; you will see
complete file management tools for creating folders or copying and
pasting templates from one location to another.
</para>
</sect2>
</sect1>

<sect1 id="vpl-3-2">
<sect1info>
<title><application>Visual Page Layout</application></title>
<authorgroup>
<author>
<firstname>Nicolas</firstname>
<surname>Deschildre</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
</author>

<othercredit role="reviewer">
<firstname>Christopher</firstname>
<surname>Hornbaker</surname>
<affiliation>
<address><email>[email protected]</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>
</sect1info>

<title><application>Visual Page Layout</application></title>

<sect2 id="vpl-views-3-2">
<title>&VPL; Modes</title>

<para>
The <application>Visual Page Layout</application> (&VPL;) editor (also known
as <acronym>WYSIWYG</acronym> (What You See Is What You Get)) allows you
to edit a &HTML; or &XHTML; document while seeing the changes on-the-fly.
Just like your favorite wordprocessor, you can click on your document and
a cursor will appear, thus enabling you to enter text, insert images,
apply text decorations, &etc;. &VPL;'s aim is to allow you to create great,
valid web pages without any knowledge of Internet markup languages.
</para>

<para>
&quantaplus; offers two modes: <guilabel>&VPL; Editor</guilabel> and
<guilabel>&VPL; &amp; Source Editors</guilabel>, which are accessible from
the <guimenu>View</guimenu> menu. The first replaces the <guilabel>Source
Editor</guilabel> with the <guilabel>&VPL; Editor</guilabel>, and the
second splits the editor window into two parts: the <guilabel>Source
Editor</guilabel> and the <guilabel>&VPL; Editor</guilabel>.
</para>

<para>
The <guilabel>&VPL; Editor</guilabel> works like so: It loads a document
like a normal &HTML; or &XHTML; page and a cursor appears. Then you can
edit it, and switching back to <guilabel>Source Editor</guilabel>, you see
that the changes you made on the <guilabel>&VPL; Editor</guilabel> have
been merged in the <guilabel>Source Editor</guilabel>.
</para>

<note>
<para>
When working in the <guilabel>&VPL; Editor</guilabel> with a document that
contains &PHP;, you will see a small green icon representing the &PHP;
code. You cannot directly edit it with the <guilabel>&VPL;
Editor</guilabel>. To edit &PHP;, you will still need to use the
<guilabel>Source Editor</guilabel>. There are no plans to change this
functionality.
</para>
</note>

<para>
The second mode behaves exactly like the first, except that you instantly
see the impact that your changes have made, either in the <guilabel>Source
Editor</guilabel> or in the <guilabel>&VPL; Editor</guilabel>, and the
cursors of the source editor and of the <guilabel>&VPL; Editor</guilabel>
are synchronized. Pressing <keycap>F9</keycap> loads this mode, but, if
it is already loaded, it will move the focus from one view to the other,
while keeping you at the same location of the document.
</para>

<para>
The refresh intervals between the <guilabel>&VPL; Editor</guilabel> and
the <guilabel>Source Editor</guilabel> are configurable. Go to
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Quanta...</guimenuitem>
</menuchoice>. Select the <guimenu>&VPL; View</guimenu> tab. You can
choose whether you want to refresh a view only when you click on it or
automatically. If you choose automatically, then you can choose a refresh
interval. The general recommendation is: A smaller number for fast
computers and a bigger number for slower ones.
</para>

<mediaobject>
<imageobject>
<imagedata fileref="vplsourceview.png" format="PNG" />
</imageobject>
<caption><para>The <guilabel>&VPL; &amp; Source Editors</guilabel> mode.</para></caption>
</mediaobject>
</sect2>

<sect2 id="vpl-editing-3-2">
<title>&VPL; Editing</title>

<sect3 id="doc-prop-dia-3-2">
<title>The <guilabel>Document Properties</guilabel> Dialog</title>

<para>
Now, let's say you want to edit the title of your web page. How do you do
it? Simply launch
<menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Document Properties</guimenuitem>
</menuchoice>. This tool allows editing of <quote>invisible</quote>
tags when using the <guilabel>&VPL; Editor</guilabel>. The
<guilabel>Document Properties</guilabel> dialog is also launched when you
create a new document while in the <guilabel>&VPL; Editor</guilabel>. This
is in order to lessen the amount of hand coding you need to perform. With
it, you can edit:
</para>

<variablelist>
<varlistentry>
<term><guilabel>Title</guilabel></term>
<listitem>
<para>
The title of the document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Meta items</guilabel></term>
<listitem>
<para>
Meta tags allow you to store information about the document itself
&eg; keywords for the Internet search engines. You can add or remove
<guilabel>Meta items</guilabel> by pressing the two buttons below,
and edit them by clicking on the list &eg; put <quote>keywords</quote> on
the <quote>name</quote> column and <quote>keyword1 keyword2</quote> on the
<quote>content</quote> column.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>CSS Rules</guilabel></term>
<listitem>
<para>
<guilabel>CSS Rules</guilabel> are the new way to tell your web browser
how to present the page. You can add or delete the <guilabel>CSS
Rules</guilabel> by pressing the buttons below. You can also fill the
fields like the <guilabel>Meta items</guilabel>. The editing of
<guilabel>CSS Rules</guilabel> is not yet supported.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Link CSS Stylesheet</guilabel></term>
<listitem>
<para>
You can also link an external CSS stylesheet. Simply click on the
<guilabel>Browse</guilabel> button and select your file.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="vpl-editor-3-2">
<title>The <guilabel>&VPL; Editor</guilabel></title>

<para>
You can use your cursor like you do in a wordprocessor, moving with the
arrows. There may come a time when the cursor does not want to go where you
want it to go (a pesky bug). Selection also works as usual. You can insert
text by typing and remove text by pressing the &Backspace; or Delete key.
</para>

<para>
Now we come to tag insertion. You can insert images, applets, text
decorations such as bold and so on by using the same toolbars you use in
the source editor. Note that the insertion of tags does not remove previous
identical tags &eg; if you insert an anchor tag around some text, then you
must remove any other anchor tag around it.
</para>

<note>
<para>
Some toolbar items will be disabled, such as the <guilabel>Table
Wizard</guilabel> or <guilabel>Quick List Wizard</guilabel>. They will
work later in &VPL;, but, for this release, you should use the
<guilabel>Tables</guilabel> or <guilabel>Lists</guilabel> toolbars.
</para>
</note>

<para>
To edit a tag (be it an image, an applet, or whatever), switch to the
<guilabel>Attribute Tree</guilabel>, accessible via
<menuchoice>
<guimenu>View</guimenu>
<guisubmenu>Tool views</guisubmenu>
</menuchoice>. Click on the tag you wish to edit, or, if you cannot access
it, click on an object contained by it. The <guilabel>Attribute
Tree</guilabel> will show the current tag name as well as a list of all its
parents and attributes. Currently &VPL; does not support, say,
&XHTML;+<acronym>MathML</acronym>, but you will see that you can edit
namespaces via this view. You can simply click on the
<guilabel>Value</guilabel> field and modify whatever you want. If you want
to access a parent of the current tag, then select it and the
<guilabel>Attribute Tree</guilabel> will load it.
</para>

<para>
To delete a tag, we will use the <guilabel>Attribute Tree</guilabel>. Have
you noticed the two little red crosses at the top-right corner? The first one
deletes only the currently selected tag and, if the &HTML;/&XHTML;
specification does not allow some children of the deleted tag to be children of
the parent tag of the tag set to be deleted, then they are also deleted,
and so on. The second cross will delete the selected tag as well as all of
its children, so be careful!
</para>

</sect3>
</sect2>
</sect1>
</chapter>