PortaBase 1.6

- A portable database -

1)Introduction
2)File selector
3)Columns editor
4)Enum manager
5)Enum editor
6)View editor
7)Data viewer
8)Row editor
9)Row viewer
10)Note editor/viewer
11)Sorting editor
12)Filter editor
13)CSV import
14)Data export
15)Preferences dialog
16)Command line usage
17)Encryption


1)Introduction
PortaBase is a small database program for creating, browsing, and editing custom tables of data. Typical uses are media inventories, reference charts, TODO lists, shopping lists, etc. Notable features include:
2)File selector
Unless the program was launched by clicking on a PortaBase file in the Documents tab, the first screen shown will be the file selector. You may open any listed file by clicking on it (in the Zaurus version), or choose one of the following options from the "File" menu or toolbar:
3)Columns editor
Each PortaBase file contains one table of a user-defined format. The format of this table is determined by a sequence of data columns, each of which has its own name, data type, and default value. When creating a new PortaBase file, this dialog is shown so the data columns can be defined. The columns of an existing file can also be edited at any time using this dialog by selecting the "Edit Columns" item in the "File" menu of the data viewer.

The current column definitions are displayed as rows in a list, in the order in which they appear in the row editor. These column definitions are manipulated using the buttons at the bottom of the dialog:
None of the changes made to the table format are applied until the "OK" button is pressed; if the "X"/"Cancel" button is pressed instead, the changes are discarded and the file format is left as it was. If the "X"/"Cancel" button is pressed while defining the columns of a new file, the file creation is aborted; otherwise, pressing either of the dialog closing buttons takes you to the data viewer.

4)Enum manager
PortaBase supports enum column types, in which each value in the column is one of a set of possible string values. The enum manager dialog lets you create, edit, delete, and change the listing order of these enums.

Most of the dialog is occupied by a list of the currently defined enums. At the bottom is a row of buttons identical to those in the columns editor:
Click "OK" to apply any changes made to the enum listing order or "X"/"Cancel" to leave the sequence unchanged (other than any added or deleted enums).

5)Enum editor
This dialog lets you define the name and list of options for an enum column type. It has a list of the enum's options and the same set of buttons as most of the other editor dialogs:
Click "OK" to accept any changes that were made or "X"/"Cancel" to leave the options unchanged (or cancel adding a new enum).

6)View editor
Whenever you browse a database's content in the data viewer, you are looking at one "view" of the data. A view is a subset of the columns in the database, displayed in a particular order and with specified display widths. Each database has a default "All Columns" view which shows all the columns in the database in the same order as they appear in the row editor.

Views are defined using the view editor dialog. At the top of the dialog is a text box containing the name of the view; changing this renames the view. Next are droplists allowing you to pick a default sorting and/or filter that will be applied whenever you switch to this view; selecting "None" leaves the current sorting or filter unchanged. (This avoids the need to select a view, then a sorting, then a filter if there are certain combinations of these you use often.) Below those is a table showing the names of all the columns in the database, with a checkbox next to each indicating whether or not it is included in this view. Click this checkbox to include or exclude the column. At the bottom of the dialog are "Up" and "Down" buttons for moving the selected row up or down in the table, changing the order of the columns in the view. Click "OK" to accept the currently shown settings or "X"/"Cancel" to revert to the previous values (or to cancel adding a new view).

7)Data viewer
This is the main screen of the application, where you can browse the database's content and launch most of the other dialogs. The contents of this screen are:
Row display and navigation
Most of the data viewer screen is occupied by a table showing one view of a set of rows in the database. The spin box at the bottom left of the screen specifies the maximum number of rows to display at once for the current view; you can edit this to be any positive integer (setting it low enough eliminates the scrollbar on the right of the display table, giving a little more horizontal space). To the right of this "rows per page" box are the page navigation buttons. Click on one of the numbered buttons to go to that page of rows; the current page is shown pressed. Click on the arrow buttons at the ends to show the page buttons for the next or previous five pages.

Clicking on a cell in the data display and holding down for 1/2 second or longer before releasing executes special functions. If you do this on a cell in a Note column, the note viewer is displayed showing the content of that note. If you do it in any other type of column, the row editor for the row you clicked on is launched.
Double-tapping on a row or pressing enter or space while a row is selected launches the row viewer.

Column labels
The row of column labels has several features in addition to informing you of the column names. To change the widths of the columns in the current view, click on the border between two column labels (or the right edge of the last column) and drag it to the desired location. Clicking on a column label sorts all the rows by the content of that column in ascending order; clicking it again sorts in descending order. If you press a column label and hold it for half a second or more before releasing, a dialog containing summary information for that column is displayed; only rows that pass the current filter are included in the summary.

File menu
The "File" menu contains options that apply to the database file as a whole. These are:
The "Row" submenu contains the following actions:
 View menu
The "View" menu allows you to select and manage views. The top section of this menu has three options:
Below these items in the menu is a list of all the views defined for the current database, with a check next to the one currently displayed. To switch to a different view, simply select the one you want to see from the menu.

Sort menu
The "Sort" menu allows you to select and manage sorting configurations. The top section of this menu has three options:
Below these items in the menu is a list of all the sortings defined for the current database, with a check next to the one currently in use (if any). To change the way the rows are sorted, simply select the sorting configuration you want to use from the menu. If you just want to sort by a single column that is displayed in the current view, it is probably faster to use the "click on a column label to sort" feature instead.

Filter menu
The "Filter" menu contains options that let you choose which rows of data to display. The top section of this menu has four options:
Below these items in the menu is a list of all the filters defined for the current database, with a check next to the one currently in use (if any). To select a different filter, simply select the one you want to use from the menu.

Toolbar buttons
There is a toolbar of four buttons that provide quick access to commonly used operations. These are:
8)Row editor
The row editor is shown whenever a row of data is added or edited. It has one row for each column in the database; on the left is the name of the column, and on the right is its current value. When adding a new row of data, the default values are shown; when editing an existing row of data, the current values are shown. To edit the value of a date field, click the button to the left of the current value display; this launches a calendar widget which allows you to select a new date. After editing the values as desired, click "OK" to accept the currently displayed values, or "X"/"Cancel" to cancel the row addition (if adding a row) or leave the current values unchanged (if editing a row).

9)Row viewer
The row viewer is a dialog designed to conveniently see all of the data for one row at a time. Like the row editor, it has the column labels on the left and values on the right. But the values are not editable, and they wrap so you don't have to scroll horizontally to see everything. The complete content of note fields is shown as well, instead of just the first few words. Pressing the left and right arrows at the bottom of the screen or the left and right directions on the direction pad allows you to navigate between rows in the current view. Pressing the edit button at the bottom of the screen lets you launch the row editor for the current row; if you click "OK" in the row editor you will be taken back to the data viewer, otherwise you will be returned to the row viewer.

10)Note editor/viewer
The "Note" column type is for blocks of text which may contain multiple lines (as opposed to the "String" type, which is better suited for relatively short single lines of text). The larger size of the content of such columns merits its own (very simple) dialog. Both in the row editor and in the default value section of the column editor, a Note value is shown as a button containing a note icon and the beginning of the Note's content (as much as will fit). To see and/or change the full text, press this button; a full-screen text editor dialog will appear, showing the current text of the Note. Click "OK" to accept any changes you have made or "X"/"Cancel" to revert to the original content.

Note columns are treated a little specially in the data viewer also. The column label for Note columns contains a note icon indicating that it is not just a String column. The cells in the column each show as much of the Note content as will fit. If you press on one of these cells and hold for half a second or longer before releasing, a read-only version of the Note editor is shown. Click either "OK" or "X"/"Cancel" to dismiss it and return to the data viewer.

11)Sorting editor
Clicking on a column label in the data viewer is a convenient way to sort the database contents by a single column. But sometimes you may want to sort by a combination of columns; sort by the content of column A, within groups of the same value of A sort by the content of column B, etc. To do this or to sort by a column that isn't shown in the current view, you need to define a named sorting.

Sortings are defined using the sorting editor dialog, which is very similar to the view editor dialog. At the top of the dialog is a text box containing the name of the sorting; changing this renames the sorting. Below that is a table showing the names of all the columns in the database, with a checkbox next to each indicating whether or not it is to be sorted. Click this checkbox to add or remove the column from the set of ones to be sorted. The third column in the table shows either "Ascending" or "Descending" for checked rows, indicating which direction to sort in; click this indicator to change it to the opposite value. At the bottom of the dialog are "Up" and "Down" buttons for moving the selected row up or down in the table, changing the sequence in which the columns are sorted. The rows are sorted by the topmost checked column first, rows with the same value in that column are sorted by the next highest checked column, etc. Click "OK" to accept the currently shown settings or "X"/"Cancel" to revert to the previous values (or to cancel adding a new sorting).

12)Filter editor
This dialog allows you to define filters which are used to select which rows to display in the data viewer. A filter may be as simple as "count = 1" or something more complicated like "any text column contains 'java', chapters > 10, pages <= 400, and instock is checked". When you choose a filter from the "Filter" menu, the data viewer is updated to show only the rows which match the conditions you have defined.

At the top of the dialog is a text box containing the name of the filter; changing this renames the filter. Below that is a list of the conditions which make up the filter; a row must satisfy all of these conditions in order to pass the filter. "Add", "Edit", "Delete", "Up", and "Down" buttons let you edit the condition list in basically the same way as the columns editor works. But instead of the column editor dialog, a condition editor dialog is launched by the "Add" and "Edit" buttons. This dialog lets you choose the column whose value to compare, the comparison operation to use, and the constant value to compare against. For text comparisons, there is also a checkbox that lets you indicate whether the comparison should be case sensitive or not. Instead of a single column, you can choose to compare the value of "Any text column"; if the value of any String or Note column in a row satisfies such a condition, the row is considered to pass the condition. Click "OK" to accept the currently shown settings or "X"/"Cancel" to revert to the previous values (or to cancel adding a new filter).

13)CSV import
PortaBase can import rows of data from CSV (Comma-Separated Value) files. This allows you to import data exported from a spreadsheet or another database program. To do this:
  1. Open the PortaBase file you want to import the data into. If you wish to import the data into a new file, create a new file and define a column structure that matches that of the data to be imported.
  2. From the "File" menu in the data viewer, select "Import". A file selector will appear showing all the CSV files that are available; pick the one you want to import from. The CSV file must have the same number of columns as the open database file, and the values in those columns must be appropriate for the specified column types. You may specify the encoding of the text file in order to import non-ASCII characters correctly; the default is UTF-8 (which supports text in many languages), but you may also choose Latin-1 (which is used by most software configured for use primarily with Western European languages).
  3. The rows in the imported file are added to the database. Rows from other files can be added by repeating this process, or another copy of the same rows can be added by importing the same file again.
Notes:
  1. Imported text files are assumed to be encoded in UTF-8
  2. Boolean fields must have a value of either 0 or 1
  3. Date fields may be formated as YYYYMMDD, YYYY/MM/DD, YYYY-MM-DD, or YYYY.MM.DD
  4. Time fields may be formated as HH:MM:SS, HH:MM:SS AM, HH:MM, HH:MM AM, or the number of seconds past midnight. Blank or -1 values are interpreted as "None".
14)Data export
PortaBase currently supports export to two formats: CSV and XML. The inverse of data import, this allows you to move database content into a spreadsheet, text editor, other database program, etc. for further manipulation. To export the current database's contents:
  1. Select "Export" from the "File" menu in the data viewer.
  2. Choose the format you want to export to from the droplist. If you export to CSV, only the rows passing the current filter will be exported. If you export to XML, the entire database structure (including column definitions, views, filters, etc.) will be exported; note that the result may be over twice the size of the actual data file, so make sure you have enough free storage space.
  3. Enter the name of the CSV or XML file you wish to create.
  4. Click "OK" to complete the export, or the "X"/"Cancel" button to cancel the operation.
15)Preferences dialog
This dialog allows you to set your preferences for the PortaBase application. It consists of the following sections:
Font
In the "Font" section you can pick any font that is available for use, in any size it is available in. That font will then be used for all text in PortaBase (even after exiting the application and restarting it) until you pick a different one. You may pick, for example "unifont, 16" in order to display Japanese characters, or "smallsmooth, 9" in order to fit more text on the screen.

General
The "General" section contains the following options:
Date and Time
This section is present only in the PC versions of PortaBase, because on the Zaurus PortaBase uses the system date and time settings. But since there is not a good cross-platform way to retrieve this information from desktop PCs, the following must be specified:
Click "OK" to accept the shown preferences, or the "X"/"Cancel" button to leave them unchanged.

16)Command line usage
PortaBase can be used from a Linux/Zaurus terminal or DOS prompt to import or export data without needing to go through the graphical interface. This can be particularly useful if you want to write scripts that automatically generate, update, or otherwise manipulate PortaBase data files. Run "portabase -h" for usage instructions; in summary, you can do the following:
To extract data from, add rows to, or create an encrypted file, type -v password immediately after the conversion command (before the other options described below).

The following options can be used between "toxml" or "tocsv" and the PortaBase file to export from:
For more information about the PortaBase XML format and tools for doing useful things with it (like converting to HTML), see the PortaBase homepage (http://portabase.sourceforge.net).

17)Encryption
PortaBase data files can be encrypted in order to protect sensitive information like passwords. Each encrypted file is accessed by providing a password specified by the file's creator. (This password can be changed later from the File menu's "Change Password" action.) Because this password must be relatively easy to remember, this is the weakest point in the encryption scheme; therefore, it is important to choose a good password. Passwords should meet the following guidelines:

For security and implementation reasons, the entire content of encrypted files must be held in memory at once; thus encrypted files cannot scale to large sizes as well as non-encrypted files. Files of a few hundred or a few thousand rows should still perform well, but files containing many thousands of rows of data probably won't (at least on the Zaurus; desktop computers with lots of memory can handle quite large encrypted files).

For more information about encryption in PortaBase (including details on the algorithms used), see the PortaBase homepage (http://portabase.sourceforge.net).

----
Copyright 2002-2003 by Jeremy Bowman.
(jmbowman@alum.mit.edu)