# Using &quanta;

## Introduction

While striving to become the best HTML editor, the developers of &quanta; began to kick about a rather intruiging idea. What if &quanta; was a generic, extensible, markup language editor?

Well, this is the start of the answer. No longer bound to HTML, &quanta; is now well on its way to becoming DTD agnostic. Essentially, if you can define it in XML or SGML, &quanta; should be able to serve as an IDE for it.

Now, that said, it must be noted that &quanta; is an outgrowth of the outstanding efforts that have been put forth by the entire KDE development community. &quanta;, in celebration of open source uses the model of Why rewrite something somebody already did and maintains already?

&quanta; provides web developers with an intuitive and powerful multiple document interface MDI that can dramatically increase your effectiveness as a web developer. Through the use of custom actions, scripting and toolbar creation you can automate almost any task. With the use of Kaptain, you can extend &quanta;, so that you never have to remember scripting command syntax again (More on that in the Advanced Features section.).

### The &quanta; workspace

&quanta; divides workspace files into three areas; Global, Local and Project. These distinctions affect the scope or visibility of the various components in the &quanta; IDE.

Global

  Global items are available to anyone who uses &quanta;. From toolbars to actions, everything marked as global is stored in the common &quanta; directory structure. This has the effect of allowing a group of admins to save certain toolbars, actions and templates in the global tree that can then be used to keep a multi-user installation of &quanta; common to everyone on the system.

Local

  Local items are items that are part of an individual users collection of resources. These are stored in the individual users home directory tree as part of the kde environment information. This exposes all of the items stored as Local for use in any editing that the individual user wishes to work on. This allows you to save your most useful templates and toolbars into your home directory and use them on any documents.

Project

  Project items are those items that are of use only to a particular project. These could be anything from a CSS template to a toolbar with a custom action that performs a special magic trick on this project's files. Simply put, this is the most limited scope. All of the items saved in the project workspace be saved in the project's directory tree.

## &quanta;'s MDI Interface

&quanta; editing this document!!

The &quanta; MDI editing this document

&quanta;'s MDI is broken down to three main parts: the editor window, the tree view window and the toolbar.

## The &quanta; Editor Window

Zoom in on the editor window

&quanta;'s editor window

&quanta;'s editor window allows for multiple files to be opened at the same time. When just one file is open, the document fills the entire editor window. As soon as a second document is opened, a small amount of space is taken from the bottom of the editory window to allow for tabs to be displayed with the filenames and a status icon (this picture doesn't show it, but there is a blue floppy icon that shows up to the left of the filename when a file has been altered indicating that a save is necessary).

At the top of the editor window is the editor toolbar set. Currently, &quanta; has a default set of toolbars that are loaded. These are Standard, Fonts, Tables, Lists, Forms, Other. These are the original toolbars that have been a part of &quanta; for some time now. These toolbars are strictly HTML and will continue to be a part of &quanta; but will eventually be loaded only on demand and not by default.

Toolbar usage is pretty straight forward. If you're looking for a basic tag (like <u>), you click on that tag and it is inserted into your document. You then insert your information betrween (if there's a closing tag) the tags and call it good. If you're looking to insert something that takes more information than just you're text (like a <a href...>) then you'll get a dialog box with the various fields you can fill in. A dialog for creating an HTML anchor

HTML toolbar anchor dialog

## The &quanta; Tree View Window

&quanta;'s tree view window

The tree view is the place where you will navigate and gather information in &quanta;. It's tabbed format presents you with a Files, Project, Template, Document Structure and Documentation Tree.

### Tabs in the tree view

  Files Tree: This is where you can browse your entire filesystem in tree format. You are presented with two perspectives on the filesystem. The first is based on your home directory and the second is the root of the file system. Use this to find existing files on your machine that you'd like to edit or add to an active project. Right clicking on a file in this view gives you several options for managing the selected file and also allows you to insert the file into the active project (if any), or toggle the view between tree and list. Check it out!

  Project Tree: Hopefully, if you use &quanta;, you'll use projects. Project management is the single most powerful tool that &quanta; offers. This view gives you direct access to what that structure looks like and allows you to manage the files in the project through right-click access. Add, remove or upload individual files or delete them entirely from the disk. All with a right-mouse click.

  Template Tree: One of the new features in &quanta; 3 is templates. Templates can be just about anything that you wish from images to code snippets to an entire web page that you change the heading on. Templates are sorted into three categories based on their scope, or visibility, in the current context. These are Global, Local and Project. As you may have guessed, Global templates are visible all the time. Local tamplates are visible to the user who created them and project templates are visible for a single project only. More on templates here.

  Structure Tree: This handy little view gives you a look at how the parser sees your document. It's pretty straight forward and can really help with those sticky required closing tags we always seem to neglect.

  Documentation Tree: Listed here is all of the documentation available for you to browse inside of &quanta;. You can download pre-packaged docs for &quanta; at http://quanta.sourceforge.net/docs.html or you can create your own documentation for &quanta;.

## &quanta; Toolbars

A major portion of &quanta;'s push to be DTD agnostic is dependent upon ease of use for each separate DTD. To that end, the toolbars in &quanta; have been extended a great deal. Toolbars are easy enough to understand. You click onthe button and you get an associated action from that button. The really cool part here is that you can define your own actions in &quanta;.

Using toolbars in &quanta; is incredibly simple. Selecting the &Alt;l Toolbars menu item reveals options to load, save, add and email toolbars.

Loading and saving toolbars is pretty straight forward. When you choose to load a toolbar, you may choose from one of the three workspaces in &quanta;.

One of the most exciting new features of &quanta; toolbars is that you can email them directly from &quanta;. When you do so, &quanta; bundles all of the actions and the toolbar information into a zipped tar archive then pushes it out via &kmail;. Once you receive a toolbar in email, you can save it anywhere and load it into &quanta; like any other toolbar!

### How to use toolbars in &quanta;

As previously mentioned, toolbars in &quanta; are primarily maanged through the Toolbars menu item. Usability and creation are somewhat different. Creation is deferred to an as there is more involved there. Usability will be discussed now.

Using toolbars is quite simple. You click on the icon of the desired tag or and one of three possibilities occur: the tag is inserted (optionally with a closing tag) (e.g. the bold HTML tag), a tag dialog is activated letting you fill in the multiple tag features in a dialog box (e.g. the anchor HTML tag), and lastly, an action is activated that does something nifty for your current file/project/whatever. For the first, I'll give no example as it is easy enough to understand. As to the second and third, read on...

Tag dialogs are defined in XML and stored in a tags subdirectory under your .kde subdirectory or with the &quanta; distribution wherever you put that. I bring this up only to note that, if you find yourself doing tedious and redundant typing for a particular tag that isn't in &quanta;, you can add it. Anyway, a tag dialog looks just like this:

This happens to be the anchor tag referenced above. If you know anything about HTML, you'll notice that that's just about all the attributes you can have for an anchor. Notice the tabs above for i18n and Events. Now all you do is fill in the blanks for those items you want in your anchor, click ok and, voila!, you have a well formed anchor set down at the current cursor position.

As for scripting actions, if you create two files in your home directory with the following contents, you'll have a fun surprise.

dt.actions

    <!DOCTYPE actionsconfig>
    <actions>
    <action icon=mini-book1.png type=script name=usr_1 \
    	text=Shell > <script output=message error=message \
    	input=none >xterm</script>
    </action>
    </actions>

dt.toolbar

    <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
    <kpartgui name="quanta" version="2">
      <ToolBar tabname="My1stToolbar" name="dt" >
       <text>My1stToolbar</text>
       <Action name="usr_1" />
      </Toolbar>
    </kpartgui>

Now click on Toolbars Load Toolbars Load Local Toolbar , browse to the dt.toolbar file in your home directory (remember to change the file mask to * from *.toolbar.gz) and the action that you created is now loaded on a toolbar called My1stToolbar which is to the right of the others. Clicking on the action on the toolbar will give you an xterm window.

&quanta-menus; &quanta-projects;

## &quanta; Templates

Templates are basically skeleton documents, code snippets and files to link to. &quanta; uses templates fundementally 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 Quanta templates as having roughly the limitations to your imagination that your file system has.

Templates exist in nested directories. There is no limit to how deep you can nest them however within any given directory Quanta expects a consistent action for the base template type described below. Additionally templates allow for pre and post text to be concatonated 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.

Our goal with templates is to extend them to include multi file "concept" 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 help wanted page.

Some of the templates that ship with &quanta; have conditions for their usage. Please read carefully the usage statement of conditions at the top of each template before you use it.

### Template types

Currently templates are limited to being one of the following types of objects:

- Document
- Text to insert in a document
- A file to link to form a document

Documents can be any type of document. Generally you would want to nest more specific or diverse documents in subdirectories. 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 effiency. Text insertion could be anything from a snippet of code to a script or whatever you might wish to use. This overlaps the ability to insert text blocks as an action which can be triggered from the toolbar. Linked files can be binary, PHP class libraries or whatever.

### Template scope

Templates are accessible based upon their established workspace in &quanta;

### Creating templates

Create a document structure that you love (XML, HTML, DocBook, etc.) and click on File Save as Template Save as Local/Project Template .

Once this is done, you'll notice that (even if it's saved as a Project template) the template does NOT show in the project tab view. Look into the templates view to find your template under the Project templates tab.

Additinoally if you look at your options with the Right Mouse Button (RMB) you will see complete file management tools for creatind directories or copying and pasting templates from one location to another.

### Using templates with Projects

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.

When creating a project you can opt to copy over all 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 Quanta does not track this so you will need to change links. This is a good task for kfilereplace which we are setting up to plug in as a kpart.

### Managing Template Behavior

Template structure on the template tab is based on the files found in `$`KDEDIR`/share/apps/quanta/templates` and `$`HOME`/.kde/share/apps/quanta/templates`. Each of these directories is specified as one of three types of container:

files/all

  binaries and such things that get inserted by their url (ie images as an <img src=/src/url>

text/all

  text that you can insert into the current quanta document. stuff like repetitive blocks etc

template/all

  document templates which you can create new documents from. these open a new window in quanta.

To set the behavior of each directory, righ-click in the template view on the directory and choose proerties. The folowing dialog will come up:

Type

  Drop down box with the three types discussed prefiously; files, text, template. This box will be grayed out if you have the inheret parent attribute box checked.

Inherit parent attribute (<blah>)

  This is checked by default and is fine for all but the top level directories in your templates tree. If the top level directory has this checked, it will basically deactivate templates for that directory and all that aren't explicitly set below it. If this is not a top level directory, then the <blah> will say something like text/all. If it says nothing, then chances are that you're on a top level directory.

Use pre/post text

  Enables pre and post text for templates in this directory. This could be a common header/footer for all of your templates for a given project and then you copy content templates into that directory and have a complete page with the custom header/footer as a starting point.

Pre-text

  The actual text to insert before your templates content.

Post-text

  The actual text to insert after your templates content.