Smart tip: This handbook is also designed to be printed... set your printer's page orientation to landscape format, so there is enough space to place hand-written notes on the left and right margin easily.
 

In a common environment, we recommend to create a new sub-directory within the existing "cgi-bin" folder to separate the software from other already installed products.

Required "template.en" directory:

Inside the directory you desired for installation, please create a new sub-directory called "template.en". It's used to hold the content of "template.en" directory delivered with your software package.

Adjust path to Perl:

Open all program files (*.pl and *.cgi) in a text editor and change the first line "#!/usr/bin/perl" that it reflects the correct path to Perl 5 (or higher version) on your system. This is required to let your server know where the Perl interpreter is located.

Usage note: On most systems, /usr/bin/perl is already the default path to Perl and so no modifications are required.
 

Detailed file table: Scheme: [filename | suggested place to upload (short description); file permission]:
 

Filename...	Description...	Filename...	Description...
*	cgi-bin (program & data files); 755	template.en/*	template.en (templates); 666

Important notes: Please double-check file permissions and transfer mode, otherwise the software may not work as intended. Depending upon the server configuration, different file permissions than the ones stated above may be necessary.

Smart tip: Our installation helper install.cgi makes it easier... just call it from your web browsing software (requires correct installation of this script) and it automatically checks your entire installation, adjusts permissions and fixes typical errors.
 

Before you proceed, it is highly recommended to set an administration password. After this is done, access to the admin panel is granted only by using "admin" as login together with the chosen password.

Now click on the button "Edit system parameters" and configure the shown parameters according your needs.

Usage note: Since all parameters are automatically filled with correct values, modifications on your side may not be required.

Directories and files:
 

Name of parameter to set...	Description...
CGI files directory Example: /usr/www/cgi-bin/ed	Absolute path to the location of EasyData on your server.
"data" directory Example: /usr/www/cgi-bin/ed/data	Absolute path to the location that holds databases and related files.
"binarydata" directory * Example: /usr/www/cgi-bin/ed/bindata	Absolute path to the location that holds binary database content.
"templates" directory Example: /usr/www/cgi-bin/ed/template.en	Absolute path to the location of web and mail templates.
"auth" directory Example: /usr/www/cgi-bin/ed/auth	Absolute path to the location of session info files (e.g. passwords).

* Technical note: The software tries to create this directory at a web-accessible place (certain cgi-bin locations doesn't allow to deliver multimedia content). If you experience problems in content delivery, please move it manually to a suited location.

Platform specific settings:
 

Name of parameter to set...	Description...
Mailing program (for Unix only) Example: /usr/bin/sendmail	Absolute path to Sendmail (or compatible) application on your server.
SMTP server Example: smtp.sunnyscript.com	SMTP server for handling mails; when left blank, default mail application is used. This setting is required for non-Unix systems, otherwise optional.
Don't use flock Example: Unchecked	"flock" is normally supported directly by the operating system; should it be unavailable for any reason (e.g. on Win9x, WinMe), mark this checkbox.
Admin e-mail address Example: admin@sunnycript.com	E-mail address of the system administrator (e.g. webmaster).

URLs:
 

Name of parameter to set...	Description...
Binary directory URL Example: http://www.sunnyscript.com/cgi-bin/ed/bindata	URL to the location that holds binary database content.
URL of CGI files directory Example: http://www.sunnyscript.com/cgi-bin/ed	URL to the location of EasyData on your server.
URL of user's help document (optional) Example: http://www.sunnyscript.com/myhelp.htm	URL to an optional help document (not included); may also consist of an e-mail link (e.g. "mailto:support@sunnyscript.com").

Various parameters:
 

Name of parameter to set...	Description...
Authentication time (in seconds) Example: 10800	Time frame keeping user authentications active (after expiration, people must log in again); recommended range: 1 to 12 hours.
Default records per page Example: 25	Maximum number of records (unless specified exactly) appearing on one page; recommended range: 5 to 30 records.
Max. number of links Example: 10	Max. number of selectable links on a page flicker when displaying search results; recommended range: 5 to 30 links.
Default table (optional) Example: firsttable	Standard table used when no specific table is called.

After you have verified all settings carefully, click on the button "Save parameters" to take over modifications to the system. It is also possible to bring back previous values with the "Let the script restore defaults" button.
 

Write down all fields required for your database on a piece of paper to ensure having a consistent and logical data structure. For example, a database containing business contacts has other field demands than a product catalogue.

If you're very unsure which fields are needed, just think about the content you want to store in the database and create some sample records based upon this. Have still problems ? Don't worry, you can add, modify and delete fields later at any time.

2. Assign field types, edit controls and verification parameters:

Field types describe the content of the concerned fields closer. By default, EasyData uses the type "text" which accepts any input - but it can be wiser to be a bit more specific (e.g. a field like "Birthday" should be set to the type "date").

Edit controls determine how particular fields are displayed. By default, EasyData uses a single input line. But it is possible to work with any edit control supported by HTML (like text boxes, radiobuttons, drop-down lists, checkboxes, ...).

Verification parameters are intended to ensure that only correct data is entered for a particular field. EasyData offers many pre-set verifications for date formats, e-mail addresses and value ranges but also allows custom settings.

Please take some time to work out suited field parameters. Especially when having different people working on one database, meaningful settings will increase data consistency dramatically - and so, this makes also search operations easier.

Helpful hint: Confused about all this stuff ? Don't worry, the correct usage will be explained later. At this stage, you should just have a basic understanding of the database structure and your desired application.

3. Check all of your planning steps:

Last but not least you should go carefully through your planning and check it. It's a matter of course, that you can do changes to existing databases at any time, but it will save some time and trouble to start right away from the beginning.

Has your planning matched the application your database is intended to ? Try to perform some search operations on the sample records you invented previously and see how users are able to access particular records.

Furthermore you may think about some extras, like desired sorting, scheduled record availability, user permissions and other stuff. But for now, don't care about this too much. It will all be explained later step by step in this handbook.
 

Accesses to your databases are handled very efficiently, so also high traffic websites are generally managed fine by EasyData. Our special database backend provides you with SQL-like performance, but neither with the need to have a SQL software server installed nor to deal with SQL's complexity and typical hang-ups.

In a common system environment, you don't have to take care about this issue. However if you have more specific questions regarding this topic, please contact SunnyScript's customer service department for personal assistance.
 

How to access your databases:

Please refer to the chapter "Web-frontend and template management" for detailed information about web integration.
 

The top menu line provides additional selections (depending on the current system status):
 

After this is done, just click on the "Create new table" button in order to create the new database.

By the way: You can add and remove system fields manually later at any time; so if you are unsure about an optional setting described above, just leave it empty and read more about below in this manual.

* What exactly is a record owner ?

Each record can have an assigned e-mail address as well as a password (optional). In this way, people are able to modify their owned records. Additionally, the mailing utility allows sending of e-mails to all registered record owners.

Why is there an ID field in each table ?

This field is required for some internal functions of EasyData (mainly used to distinguish records); so you can commonly ignore it. If you like, you may also rename its label, hide it when showing records or even make it editable by users.

Technical note: Since each record must have a unique ID field value, this field is of autoincrement type by default.
 

Go to "New field name", type in the desired name and select the data type. In order to finish action, click on "Create new field".

There are also various system fields available, required for advanced features. Type in the field names exactly as they appear in the following list to enable the concerned feature (refer to following chapters for details):
 

After a field was created successfully, the screen "Field properties" appears (see next part of this chapter).
 

How to delete a field:

Look for the field you wish to remove from the table and click on "Delete". However, please note that once a field is removed, all related content will get lost and cannot be recovered.

By the way: All table parameters are automatically updated and the concerned field becomes removed from these settings.

How to change sorting of fields:

Look for the field you wish to move around and click on either "move up" or "move down" to change the field's position.

Technical note: Sorting of fields takes effect only to various admin panel screens. Use "Table parameters and layout" settings to change the default field order for the web-frontend.

How to edit a field:

Look for the field you wish to modify and click either on "Edit" or the field name. Now the screen "Field properties" appears. Depending of the selected field, you can modify these options:
 

Important notes: If you edit a system field, some of the settings above may be not available for selection. Don't touch pre-filled settings for system fields; you may negatively affect their behavior.
 

From admin panel, select the desired table and choose "Edit table categories". Alternatively you can click on "Categories" in the upper right corner of the screen.

How to create a new category:

Type in a category name and short description (optional; can be displayed when browsing by categories).

Now click either on the button "Add new top-level category" to create a new main category or "Add new category inside current category" to add a sub-category within the currently selected category.

How to edit a category:

Click on the ID of the category you wish to modify:
 

In order to take over the changes to the system, click on the button "Save".

Helpful hint: Since categories are sorted alphabetically by their IDs (category codes), changing their displayed default order is very easy by altering the concerned category codes according your desired arrangement.

How to delete a category:

Select the ID of the category you wish to remove and then click on the appropriate deletion button to remove the concerned category from the table (please be careful when doing so; once deleted, categories cannot be recovered).

Important note: Records related to removed categories are re-assigned to the concerned upper level category.

Category trees - overview:

EasyData comes with a feature allowing website developers to implement an interactive JavaScript-powered category tree to websites in just a few minutes. Ideally suited for easy database navigation on category-based tables.

Each tree is built with graphical elements and can be individualized to allow highest flexibility. It is also based upon an own template (treeview.htm), so even surrounding HTML elements are possible.

Category trees - website implementation:

Call treeview.cgi to display a table's tree:
 

Implementation by using SSI-tags:

Example: <!--#include virtual="/cgi-bin/ed/treeview.cgi?tbl=TABLE"-->
Description: Replace "TABLE" with the concerned table's name.

Technical note: Remove all HTML initializing tags from template treeview.htm (mainly <HTML> and <HEAD>) to avoid display errors caused when inserting the category tree codes into an existing webpage via SSI.

Important note: In order to use category trees, at least the permission "Search" is required for anonymous users.

Category trees - available settings:

Choose the desired table and select "Restructure table". Alternatively click on "Restructure" in the upper right corner of the screen. If you just created a table, this screen appears automatically. Now click on the button "Edit treeview parameters".

Layout options:
 

Drawing icons:
 

Folder/leaf icons:
 

Root category:
 

Important note: It is strongly recommended to enable this feature, if you allow people adding their own records. Otherwise you have no control about the database content.

Enable moderation mode:

Check fields "Make additions moderated" and/or "Make modifications moderated" during table creation or go to "Change table parameters and layout" and modify "Permissions" according your needs.
 

Usage note: For more details about permissions and user groups, please take a look at the next chapter.

How to moderate actions:

From admin panel (you must be logged in as admin), select the desired table and choose "Moderate table". Alternatively you can click on "Moderate" in the upper right corner of the screen.

Now you see a list containing all queued requests. Each request can be approved or declined by selecting the concerned radio button. Select "Hold" and the concerned record will be still kept in moderation queue.

After you moderated all requests, click on the button at the end of this screen to take over your decisions to the system.

How to edit records in moderation queue:

If you wish to modify records that are currently in moderation queue, mark the button "Remind to update" when approving the concerned records. Now the moderation result screen allows you to edit them right away (new browser window opens).
 

How to remove a table (be very careful):

Go to "Delete table" and then click on "Delete files". You can either remove parts of this table or the entire database structure.

How to clear selected table files (be very careful):

Go to "Empty table", select the appropriate files you wish to clear and then click on "Clear data" to carry out this action.

How to rename a table:

Go to "Rename table" and specify the new name. Click on "Rename" to take over the changes to the system.
 

On the following screen, you may browse through all categories, search for records, add new ones, remove, update or clone existing records and do all other database administration tasks (see menu on the upper right corner of the screen).

Technical note 1: When updating records (admin only), all fields are shown regardless of the "Visible fields" settings at the "Table parameters" screen for convenience reasons (however other screens in admin panel consider these preferences).

Technical note 2: Cloning a record means to take over all field values from an existing record to a new one showing the "Add record" screen. It is not possible to clone fields of type "image", "binary" and "uploadmemo".
 

You can use these statistics for various marketing and performance analysis (e.g. most popular search queries, behavior of the users when doing search operations) or just for your personal interest.

How to enable search requests logging ?

Go to the screen "Table layout parameters", "Search requests logging":
 

Sending of statistics via e-mail: See also "Table layout parameters" screen, but now part "Table automatic maintenance":
 

How to access the statistics ?

Click on "Search stats" available in the upper left corner of the screen to access the statistics of the currently active table.

Search requests statistics form:
 

Smart tip 1: The generated reports can be printed easily: Depending upon the used paper size, you may need to set the printer's page orientation to landscape format. In this case, there is also space for placing hand-written notes at the margins.

Smart tip 2: Since EasyData doesn't use image files to create bar graphs, you can simply copy the report to a disk and carry it to other computers, still keeping the layout (reports are generated in HTML language).
 

As mentioned in the previous chapter, users can be assigned to records they added to a table. By using this feature, record owners are able to modify or delete their owned records online and even prolong the life of them (if expiration feature is active).

In order to enable managed records, just ensure that you have the system field _email (e-mail address) within your table. Higher security will be achieved by adding another system field called _pwd, which contains a user determinable password.

Registered users are required to log in by using the login screen of EasyData providing their e-mail address and password.

Usage note: Alternatively to _email, also the field _login can be used. While _email needs to contain an e-mail address, the _login field may hold any content (e.g. alphanumerical values). If both fields are available, _login has a higher priority.

Configure the password reminder utility:

If a record owner forgot the password, it can be re-send automatically by the system at request. In order to configure this utility, please go to the "Table parameters" screen:
 

Important note: Since the admin password is saved encrypted for higher security, it cannot be restored. See chapter "Helpful hints and technical reference" about information on how to reset the admin password.

Technical note: For this feature, the system field _email is required.
 

Anonymous users are not logged in and just work with the system (e.g. searching or browsing a database).
Registered users refers to record owners logged in with their e-mail address (or login ID) and password.

Set permissions for anonymous users:
 

Set permissions for registered users (record owners):
 

Set permissions for (registered users') owned records:
 

Enable moderation for record comments:
 

Enable "flood" prevention (anonymous and registered users):
 

Add system field _rating to the table to allow user ratings. Optionally add system field _votes to count number of ratings.
Add system field _comments_data to the table to allow comments. Optionally add system field _comments to count them.

Helpful hint: During table creation, mark "Include user feedback fields" to allow rating as well as comments; so you don't have to add the system fields above manually.

Voting and comments settings:

Select the desired table and choose "Change table parameters and layout" from admin panel. Go to the part "Voting and comment parameters".
 

Technical note:  Admin can remove unwanted comments by editing the field _comments_data of the concerned record.

Helpful hint: It is also possible to make comments moderated. Please refer to "Set user permissions and limitations" above.

Voting and comments web-frontend:

Please refer to the chapter "Web-frontend and template management" for more details.

Technical note: The default maximum size for _rating field is five characters. Since it is in float data type, digits are chopped off if field size exceeds the maximum size (however admin can adjust field properties).
 

EasyData provides the ability to schedule the appearance and disappearance of records. In case of removements, notification messages may be sent before and records are able to be prolonged by their concerned owners.

There are several ways to set appearance dates, expiration dates and periods (e.g. based upon record creation date or last record update, for the entire table or unique for each record).

Pre-requisites for automatic record expiration:

1. Maintenance interval: Ensure that a maintenance interval is specified. See screen "Table parameters", "Table automatic maintenance". Recommended range: 3600 to 43200 seconds (1 to 12 hours).

2. Record owner: If you wish to allow record owners to prolong the life of their assigned record(s), the system fields _email (alternatively _login) and _pwd are required (password field is optional).

Technical note: Record appearance tasks are automatically handled when accessing the concerned table.

Appearance... table-wide appearance date (valid for all new records):

Add system field _effective_since and type in the following string as "Default value" setting at "Field properties" screen:

Appears in <x> days

<x>: Number of days counted from record creation till appearance.

Usage note: This string is a special command, only valid for the above particular application.

Technical note: Until appearance date, the record exists but is not allowed being shown when searching or browsing the table. While for the admin such records are always visible, registered users can update them only by using a direct link.

Appearance... individual appearance date for each unique record - absolute date:

Add the system field _effective_since which contains the date of first desired appearance (format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS). It must be filled during record addition; leave field empty to make the record available immediately.

Appearance... individual appearance date for each unique record - relative date:

Same procedure as done for a table-wide appearance date, but don't set a default value for _effective_since, just use "Appears in <x> days" individually for each created record as field value.

Expiration... table-wide expiration date (valid for all records):

Ensure that either the system field _add_datetime or _update_datetime is present for the concerned table - based upon these date/time stamps, the expiration dates are calculated:
 

_add_datetime contains the date/time stamp of record creation. _update_datetime contains the date/time stamp of last record update.

Helpful hint: _update_datetime should be used, if you wish to allow record owners to prolong life of their records.

At "Table automatic maintenance" (see "Table parameters" screen), you'll find the record expiration settings:
 

If you activated the setting "Allow record life be prolonged", notification mails are sent out to record owners with instructions on how to prolong the life of concerned record:
 

If you wish to notify the record owner as soon as a record is removed, fill out also these settings:
 

Expiration... individual expiration of each unique record - absolute date:

Add the system field _expires which contains the date of expiration (format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS). This field must be filled during record addition; leave it empty to disable expiration for a particular record.

Important note: Setting an expiration time (see above) is required also here to determine a maximum applicable time frame; you may wish to set the expiration time parameter to a high value, like 3650 days (about ten years).

Helpful hint: If you allow record owners to prolong the life of their assigned records, ensure that the system field _expires is accessible for updates (see "Table parameters", "Record update mode - visible fields").

Expiration... individual expiration of each unique record - relative date:

Alternatively to the date input described before, simply type in this as "Default value" setting for the field _expires:

Expires in <x> days

<x>: Number of days counted from record creation till expiration.

Usage note: This string is a special command, only valid for the above particular application.

Expiration... combination of table wide and individual expiration dates:

If _expires and one date/time stamp as well as an expiration time exists, then the expiration date in _expires applies.
If both date/time stamps and an expiration time exists, then _update_datetime is used for calculating the expiration time.

General priority of date/time stamps and expiration field: _expires, _update_datetime, _add_datetime.

Expiration... Templates (warning / notification mails):

Please refer to the chapter "Web-frontend and template management" for more details.
 

By using the parameter "Max. size" at "Field properties", you can specify the maximum file size in bytes allowed for uploads. Setting a file size limitation is strongly recommended, if you want to enable public record additions or modifications.

Important note: It is not possible to perform search operations upon these fields' content.
 

How to block a record:

Search for the concerned record to block, click on "Update" (can be found in the upper right corner of the screen) and then just check the appropriate button (edit control of the field _blocked).

How to unblock a record:

Search for the concerned record to unblock, click on "Update" (can be found in the upper right corner of the screen) and then just uncheck the appropriate button (edit control of the field _blocked).
 

You can send out mailings either to all record owners of a selected table (recipients filter set to "Send to all") or just mail such people who have allowed you to do so (recipients filter set to "Send to subscribed users only").

Mark "Do not send duplicate e-mails" in order to send only one single mail, even a particular address is found multiple times.

Custom recipients filter:

You can specify a search query that filters only recipients matching particular criteria. It is possible to use any field available in the table this mailing is intended for. Click on "view filter results" to get a listing of all selected records.

For example: income>=3000 AND education="high"
Only recipients will receive this mailing which have an income of more than 3000 currency units and a "high" education level.

Usage note: For more details about how to perform search operations, please refer to "Searching of databases (tables)" below.

Personalized mailings:

Personalized mailings contain an individual "To:" field for each recipient. In addition, you can include fields from the concerned table  (format: <!--$FIELDNAME-->) which are replaced by appropriate content.
 

Sample personalized mailing: