Dialogs Framework Basic Concepts

Add a new List by clicking the Add List button from the Lists tabular view (Setup menu). The following fields are the minimum needed to create a new list.

• Name the List alphanumerically, avoiding spaces and using only "-" or "_" punctuation if desired. Developers tend to prefix Lists they create so they sort together in the Lists tabular view. While internal lists used by Dialogs are prefixed with "KD_", developers often prefix lists created for the client site with "C_" (for Client). Examples of common lists used in Dialogs websites are "C_billboards", "C_news", and "C_web_contacts". As you fill this value in, you will see Display Name and Item Table also fill in.
• Display Name is the name that will be used when the system builds out the page for accessing this list, used for the menu display field and title of the page for this list, and can be used in dropdowns for selecting lists. This probably auto-filled when you typed in the Name for the list, but you can edit it. For example, if you named your list "C_news", then "C News" was entered as the Display Name, and you may want to change that to "News".
• Item Table defines the table name in the MySQL database that contains the List data. This also auto-filled, and is usually left as the same value as the Name field.

Click "Save" to create the list.

• Display Name is the user friendly value used in some situations when referencing the list.
• Item Table defines the table name in the MySQL database that contains the List data.
• Content Activation when checked, presents fields on the List content entry view to manage activation and deactivation on specified future dates.
• Always post Changes... will repost data to the database when a List Item is saved, even if you haven't made changes to the data. This is not usually needed, and can be left unchecked in most situations.
• Save Stats when checked, saves statistics about how many times the list item was viewed.
• Keep revisions when checked, stores each post to a list item for potential restore or roll-back.
• Use edit file when checked will create an Item Template file (<list name>.edit.inc.php) which will be used when editing items for the list, instead of the usual way of automatically generating the edit view for list items based on dynamic fields.
• Rename Attachments when checked, adds a random string to each uploaded file to avoid potential name collisions.
• Allow snapshots determines if the list will appear as available for snapshots.
• Searchable defines whether or not the List should be included in Dialogs automatic search indexing.
• Allow viewing from KDpg_item_view.html determines if a read-only view of a list entry can be viewed using KDpg_item_view.html.
• Default Sort Column defines the sort column used if one is not specified in the List Template.
• Page for editing the List defines the page used to edit the list.
• Attachment File Directory defines the directory where uploaded files will be stored. If the directory does not exist, Dialogs will create it.
• POST script filename defines a script to be run AFTER each post to the list.
• File types allowed for Upload restricts uploaded files by extension.
• Custom Javascript holds any javascript to be added to the item edit form.
• Read Access / Write Access define the READ and WRITE permissions that will be automatically assigned to newly created List items. By default, new lists are created with READ access set to Everyone, and WRITE access set to Admin and Public Content Editor.
• Save and Set Item Permissions is used to reset READ and WRITE permissions for all existing items on the List to those shown.

You may add as many fields as needed to each list (up to the maximum fields MySQL will permit). Add a new field by clicking the Add Fields button; edit an existing field by clicking the edit icon of a particular field in the list of fields.

• Field Setup
  • Type is a drodown select to choose which type of field you are defining.
  • Name the field (No spaces or punctuation other than "-" or "_")
  • Label defines the field label seen to the left of fields in the Detail View and as a column header in Tabular View.
  • Form Position (Row) parameter defines the sort order of fields in the List Detail View.
  • Table Position (Column) parameter defines the sort order of fields in the List Tabular View.
  • Drawer Position (optional) parameter defines the sort order of fields in the Drawer on the Tabular View of the list.
  • Default Value (optional) sets a default value for the field for newly created items on a List.
• Field Settings
  • Hints (optional) provides a place to put data entry hints to be displayed on the Detail View.
  • Width sets the width of a text edit box.
  • Extra Attribute applies to the input or select HTML element on the form.
  • Index adds an index to the table for speed. Not usually needed.
  • Unique adds a UNIQUE index to the table. The user will also be warned about duplicates before saving.

Fields may be defined as one of the following Types:

• Single line text standard form input.
• Multi-line text text area. For this type of field, an additional setting will appear:
  • Height
• Multi-line text WYSIWYG text area with rich text editor if tinyMCE or other plugin has been installed and configured. For this type of field, an additional setting will appear:
  • Height
• Checkbox Y/N binary alpha data store (configure the value of Checked and Unchecked states). Additional settings for this field type are:
  • Checkbox Checked Value
  • Checkbox Unchecked Value
• Checkbox 1/0 binary numeric data store (configure the value of Checked and Unchecked states). Additional settings for this field type are:
  • Checkbox Checked Value
  • Checkbox Unchecked Value
• Integer Numbers whole integer number
• Money floating point number with 2 decimal places
• Date saves as mm-dd-yyyy
• Time saves as hh:mm:ss
• Timestamp unix timestamp
• Single Character any single character
• Pull-Down for numbers select alpha data store (configure the List to be used to populate the select). For pull-down type list fields, additional settings appear:
  • Which Table allows you to set the database table (Dialogs List) which will be used to populate the pull-down.
  • Field to Display is usually item_name, but can be any field or combination of fields, comma delimited.
  • Field to Save is usually item_name or item_id.
  • Field to Sort by is usually list_sort or item_name.
  • Top Blank Entry Text allows you to set the text that shows in the pull-down before a selection is made.
  • SQL WHERE Clause Filter lets you filter which entries to the list show up in the pull-down.
  • Allow new values when checked adds a text field so the user can enter a new value which will be added to the list defined for the pull-down.
• Pull-Down for text select alpha data store (configure the List to be used to populate the select). For pull-down type list fields, additional settings appear:
  • Which Table allows you to set the database table (Dialogs List) which will be used to populate the pull-down.
  • Field to Display is usually item_name, but can be any field or combination of fields, comma delimited.
  • Field to Save is usually item_name or item_id.
  • Field to Sort by is usually list_sort or item_name.
  • Top Blank Entry Text allows you to set the text that shows in the pull-down before a selection is made.
  • SQL WHERE Clause Filter lets you filter which entries to the list show up in the pull-down.
  • Allow new values when checked adds a text field so the user can enter a new value which will be added to the list defined for the pull-down.
• Pull-Down for (static values) allows for the quick creation of a pull-down select field for a list, where values are not likely to change, and where the data doesn't need to be set up as its own list.
  • Static Values for Select Menu is where you enter the name|value pairs that should appear in the pull-down. These are entered one per line, pipe (|) separated. You can create a no-value entry to appear before a selection is made by adding a name without a value as the first line.
• LRP (Left-Right-Picker) multi-select alpha data store (configure the List to be used to populate the select). Data for this field is stored in a string, with piped values indicating which items are "selected" out of the "available" set. For example:

  |3|,|5|,|17|,|32|

  This has 4 items "selected".
  Additional settings for this field type are:
  • Which Table allows you to set the database table (Dialogs List) which will be used to populate the pull-down.
  • Field to Display is usually item_name, but can be any field or combination of fields, comma delimited.
  • Field to Save is usually item_name or item_id.
  • Field to Sort by is usually list_sort or item_name.
  • Top Blank Entry Text allows you to set the text that shows in the pull-down before a selection is made.
  • SQL WHERE Clause Filter lets you filter which entries to the list show up in the pull-down.
• Bit-encoded LRP (64 max) Same as above, but data for this field is stored in the bits of the largest possible integer on a server (typically 64 bit), with individual bits turned on indicating which items are "selected" out of the "available" set.  For example:

  001000010...

  (number presented in binary)
  This has 2 items "selected": the 3rd bit and the 7th bit.
• Image/Attachment File will automatically set the Name, incrementing for each additional image field added to a list.
• Editable Text File will create a field where the content entered is saved as a file on the server (in the Attachment File Directory defined in the List Settings).
• Extra Hint lets you add some additional information or instructions about content management into the form.
• Hidden a hidden field on the form. Usage note: if you want to also add a field to the database first create the field as some type other than hidden, then change it to hidden AND SET THE DEFAULT VALUE TO $[ROW]FIELD_NAME where FIELD_NAME is the name you assigned to the field.  This will enable you to programmatically manage content in a List field that is hidden to the user (but is passed back to Dialogs with each form post).
• Field Group is a way of organizing a lot of fields on the edit form. You can see it in action in many parts of Dialogs v.8, including the page where you create new list fields, where items are grouped in a "panel", with a title at the top of the panel. The Name you assign will appear at the top of the group panel. If using Field Groups on your list, you assign the Field Group a Form Position (for example, "A"), and all fields that sort out after that Field Group, but before the next Field Group assigned, will appear in the preceding Group. In order to keep things easier to make adjustments to, we recommend assigning "nested" Form Position values to the fields you want to appear within a group. So if a Field Group has a Form Position of "A", then you would assign the fields within that group Form Positions of "A.01", "A.02", etc. You can assign some instructions or additional information about a group using the Default Value or Hints settings for the group.