Open Source

Posted by David Cramer on Nov 5, 2010

Minimum Version for this Tutorial: 0.1.7

Sometimes you will want to have a report list of all entries and and a separate capture form. in this case you would have 2 interfaces, the report and the form.

We will learn about Passback Values, Redirection and Form Layouts. We will take Tutorial from Day 1 and split it into two interfaces that achieve this. So lets get started.

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

Duplicating the Interfaces

Since we’re going to be interfacing the same table twice (the report and the capture) there is a quick way of getting this done. In the DB Toolkit Menu group, click on “Interfaces”. This will take us to the complete list of interfaces we’ve created. In this list you’ll see the group “Contacts” we created in Day 1, in that group is the interface “Contact Manager”. Mouse over this entry and you’ll see the Sub Menu with the options “Edit, View, Duplicate and Delete”. Simply click on Duplicate to create a copy of the interface. Directly below it you’ll see a new entry. this is our new interface that we will turn into our Capture Form.

Mouse over the duplicate entry and click on the sub menu item Edit.

Making the Form

New setting for capture form

Lets set the new interface as the image to the left.

Title: Add Contact

Interface Description: Capture a New Contact

Set as Dashboard Item: leave unchecked

Menu Group: Leave it as Contacts

Effective Permission: Administrator

This will essentially give our new interface a unique name. Now its time to give it different function.

Click on the “Form Layout” Tab, we are able to overide this default form and create our own form layout using a grid based model. So lets start by clicking on the

Form Layout

By default, DB Toolkit generates the input form according to the FieldType selection in the order of the fields from the field setup tab. In this section I’ll be using terminology explained in Form Layout Tab, so read that up to get familiar with it, or just wing it.

The form layout tab

The First thing we want to do is click on the Sync Fields button, this will fetch our fields that we can use in our form. Once we have our fields we want to add a Row to our form, so click on the Insert Row button.

We’re going to have a 2 column form here, the text based details to the left and an image to the right. So On the Row Editing Options, Click on the Add Button to divide the Row into 2 columns. Lets off balance the form a little by making the left column wider than the right, click on the Row Config button in the Row Editing Options, and set the balance in the dialog to 60% and 40% and click save. Great!

Now lets get rid of the fields we don’t want. We are not going to need to capture ContactID, DateAdded and AddedBy as they are auto fields and as such don’t have an input, so click the little X on those Fields to remove them. (this is not really necessary since leaving a field in the available field box effectively ignores them as well, but its cleaner to remove them as its less complicated.) Now we can start building our form, this is done via Drag and Drop so its fairly simple. Drag and drop the fields Firsname, Lastname, PhoneNumber and EmailAddress to the Right Column and Drag and Drop the Photo Field to the Left. And that’s the building of the form part. Now there are 2 more steps to do and that’s set the interface into Form Mode ans setup the redirects.

Settings Tab

in the Settings Tab

Redirect interface

Head on to the Settings Tab, I’m not going to get into much detail here. Simply check the Form Mode Checkbox in the General Settings Panel. This sets the interface render mode to Form. To the right is a panel called Redirects with 2 tabs Public and Admin. Click on the Admin tab in this panel we should see 2 interfaces there , Contacts Manager which we created in Day 1 and the Duplicate (which is highlighted as its the one we’re editing), Select the Original Contacts Manager.

What we have done here is tell the form to redirect to the Contacts Manager interface on submit. This way we will see the new entry in the report list after submission. Indecently, Setting no redirect would have the form create the entry and load it up in the same form for editing.

Now hit the Save button at the bottom of the page as we are done!

At the tom of the Interfaces page you should see “Interface Add Contact Updated”. Click the Add Contact link to view your capture form. You will also see that in your Contacts Menu to the right, you now have a new link “Add Contact” Now go and test your capture form and play.

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.

Remove Field: This only removes the field from the config screen. this is useful if interfacing a large table but only interfacing a small number of fields. you can safely remove the unused fields from the config without needing to configure them. the removed fields are simply ignored within the interface created. they will however be back when you re-edit the interface in case you require a field at a later stage.

Field Behavior Settings Panel: this will open a panel with additional field settings:

Title: The displayed title of the field for reports and forms
Caption: A caption for the field in the form
Width: the width of the field column in report. (not effected in template report)
Justify: Alignment of the field column in report.( not effected in template report)
XAxis: sets field as the X axis when in chart mode
Chart item: sets the field as a chart item (Y Axis) when in chart mode
Chart Type: type of chart when in chart mode

Field Name: The desplay name of the field that will be shown in the interface.

FieldType: This is the field data handler. It controls the way all the data for that field is handled. It also defines how the form input for that field looks and works. A text FieldType for example, will have a simple single line text box, but a date type will have a date picker or an image upload will have a file upload box with an image preview. Clicking on the fieldtype button opens the fieldtype selector panel for you to choose the desired fieldtype you want to use.

All fieldtypes available are listed here

Field View and Index Settings: This controls how the field is viewed in a report. there are 4 options in this selector:

1. Shown Indexed: the field is shown and has shows a filter setting in the filters box (fieldtype specific).
2. Shown Not-Indexed: the field is shown but doesn’t show a filter option and is not effected by filtering.
3. Hidden Indexed: the field is not shown but shows a filter setting in the filters box (fieldtype specific).
4. Hidden Not-Indexed: the field is not shown and doesn’t show a filter option and is not effected by filtering.

Field Control Settings: These 3 icons do special stuff!

1. Unique: This ensures that the value entered into the form does not exist in the database.
2. Required: Validates that the field is filled in.
3. Sortable: Makes the field column sortable in both directions (not in template mode)

FieldType Settings: Each field type can have its own configuration. An image field for example, may require a setting for image thumbnail sizes, or a date field may require date format settings and so forth. Some fields however don’t have any settings and therefore this button may not always be present.

GPS Coordinates FieldType config panel example which intergrates Google Maps

Form Builder Element Buttons: These buttons control certain aspecs of how the form looks. they are

Sync Fields: Fetch fields for the table and place them in the Available Fields Holder Box
Insert Row: Creates a new Row at the bottom of the row list
Add Section Break: Adds a section Break Field Element. These are useful for grouping fields on large forms
Add Tab: Makes parts of the form into a tabbed form (Experimental)

Width of Dialog Box: this is the pixel with of the dialog that holds the form. (only used in report/add new combination)

Dialog Modes: These are how the dialog box is handled. Modal sets the dialog to a modal type box and the Ajax form, sets the form to be handled via ajax so there’s no page reloads. (Experimental)

Disabled Notice: Lets you know if the form is running in default or not.

Columns: The columns where Fields can be dropped. an infinite number of columns can be added, however to many will really be a bad idea.

Row: The row in which Fields exist.

Row Editing Options: Rows are devided into columns. by default a row has 1 column. these options allows us to minipulate this. the options are:

Config: this sets the column widths in a ratio.
Add Column: Adds a new Column.
Remove Column: removes a column. Fields in the column move to the left.
Remove Row: Removes  the row. Must be empty.

Usable Fields Holder Box: Holds the fields that the form can use. Any fields left in here on save, are ignored.

Usable Fields: The fields that are dropped into columns. The X on to left of the field removes the field from the form and that field will be ignored.

[interface id=”dt_intfc52361c02bff59″ filter=”language” by=”English”]

where “filter” is the field you want to filter with and “by” is the value of the filter.