Day 1 – Building a report based capture in DB-Toolkit

Posted by David Cramer on Nov 3, 2010

Minimum Version for this Tutorial: 0.1.7

In the first of our db-toolkit tutorials, I’ll show you how to build a Contacts Book which consists of a report with an add item button.

This will be fairly straight forward and wont show you all the settings and all that since it uses manly the defaults, but it will show you basic concepts on how to configure a table to be a form and report. So without hesitation lets jump in.

The interface we’re going to build: contact manager.

The Table

Select the query below and use it to create the table for this tutorial. In this case its a simple contact book, nothing special. Note that it does not need the prefix as the plugin finds all tables in the database not just prefixed tables. This is to allow us the freedom to use any table.

CREATE TABLE `tutorials_contacts` (
  `ContactID` int(11) NOT NULL AUTO_INCREMENT,
  `Firstname` varchar(45) NOT NULL,
  `Lastname` varchar(45) NOT NULL,
  `Photo` varchar(255) NOT NULL,
  `PhoneNumber` varchar(25) NOT NULL,
  `EmailAddress` varchar(100) NOT NULL,
  `DateAdded` date NOT NULL,
  `AddedBy` int(11) NOT NULL,
  PRIMARY KEY (`ContactID`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=1001 ;

Creating The Interface.

Add New Option

First thing to do is make sure DB-Toolkit is installed an up-to-date. Now click on the “Add New” option in the DB Toolkit panel at the bottom of the toolbar. This will take you to a new interface creation page.

Don’t be alarmed at all the settings and optiona available, we’ll go over them over the course of these tutorials soon enough.

Setup for new interface

Interface Title
This is the title of the interface. Lets call this Contacts Manager

Interface Description
This gives us a better idea of what the interface does, it also is the page name for the interface. Lets call this one Manage Company Contacts

Set as Dashboard Item
By checking this it will allow the interface to be usable on the Dashboard. lets leave that off for now.

Menu Group
Interfaces can be accessible as menu items in WP admin. Lets call this menu group Contacts.

Effective Permission
This sets what kind of user has access to this interface. in this case its for administrators.

The next step is to select the table you want to interface. in the table selection dropdown select the table you created from the above SQL “tutorials_contacts” once you select the table name you’ll see all the fields load up in the Report Setup panel below.

Report Setup: Configuring the Fields.

This is perhaps the most important step. a FieldType is more than a setting each field type is a mini plugin all on its own. it has the power to manipulate the report query, has its own headers, function library, footers and javascript files. They are very powerful. I’m going to use terminology found in the Field Panel documentation for this so check there for reference. should be pretty easy if you want to wing it.

Field Config Panel

Field Settings:

ContactID: Lets keep the FieldType as Auto. This will allow for the auto-increment to work. set the Field View as Hidden Not-Index the panel should fade out indicating it is hidden.

Firstname: Lets set this to Single Text Input Click on the fieldtype button, in the panel below, click on Text Input > Single Text Input the panel should fade away and the FieldType button should reflect the new type. Set the Field View as Shown Indexed and click the Required flag. Leave the FieldType config panel as is, click the setup button to minimize it.

Lastname: Set this the same as Firstname only click the Sortable button as well.

Photo: Set the FieldType to File > Image Upload. Set the Field View to Shown Not-Indexed. Now in the FieldType Config Panel set the Icon Size to 25 check the square crop , the View size to 85 and the full view to 150 and minimize the panel.

PhoneNumber: Lets set this to the same as Firstname. (We are working on a phone number FieldType but use single line input for now).

EmailAddress: Lets set this to the same as Firstname. (We are working on an Email Address FieldType but use single line input for now).

DateAdded: Set the FieldType to Date Input > Auto Timestamp, Set the Field View to Shown Indexed and you can ignore the FieldType Config for now by minimizing the panel.

AddedBy: Set this to Auto Values > User ID, Shown Indexed and ignore the FieldType Config.

Organise your Report

Now lets re-arrange the fields to be more logical for a report. Click on the Photo Field Name and drag it above Firstname All field types can be arranged for report view this way.

The next panel is Totals Lets ignore this for now and go on to Passback Field this is the field that is passed to and from interfaces. its commonly the primary field. in this case its the ContactID. lets leave it as it is for now  as this should be the default. You can add multiple return fields.

In the Sort Field Panel, this is the default sort field in the report. lets choose Lastname and set it to Asending so we can sort the Contact alphabetically by their lastname in ascending order.

Now click Save to create your first interface.

And thats it! you now have created your very first contact manager.
In your Interfaces list, you can see your new interface grouped under Contacts put your mouse over the Contacts Manager entry and click View so view your Interface.

Using your Interface

Now lets go and add a new Contact. You’ll notice after a page load that there is now a new menu group just below the Comments Group called Contacts. This is your new interface Group that you defined earlier when setting up the interface.

adding an entry

View your Interface and click on the Add Entry button on your interface toolbar. In the dialog window you get all the fields that you setup earlier with validation.

Fill in the Form with your own details to get the feel of how it works.

Play!

Go try out all the features in your new interface. (Export is buggy I know!) look at how to edit and view and entry as well as deleting.