Subversion Repositories php_library

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
1 rodolico 1 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"
2 
>
3 
<html>
4 
  <head>
5 
    <title>library.php Manual</title>
6 
    <meta name="GENERATOR" content="Quanta Plus">
7 
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
8 
  </head>
9 
  <body>
10 
 
11 
    <h3>
12 
       Administrative Interface
13 
    </h3>
14 
    <p>
15 
       The administrative interface allows you to do a "quick and dirty" admin interface to allow users to administer their site
16 
    </p>
17 
    <p>
18 
       The basics of creating an administrative interface is to do the following:
19 
    </p>
20 
    <ul>
21 
      <LI>
22 
         Create a database definition file (see sql2admin_hash.pl documentation)
23 
      </LI>
24 
      <li>
25 
         In an html file (say, admin.html), have the following two PHP commands execute
26 
      <ul>
27 
        <li>
28 
          <em>include_once &#039;library.php&#039;&#059;</em>
29 
        </li>
30 
        <LI>
31 
          <em>doAdmin()&#059;</em>
32 
        </LI>
33 
      </ul>
34 
      </li>
35 
    </ul>
36 
    <p>
37 
       A database definition file requires one global variable, <em>$DATABASE_DEFINITION</em>, and can also have four contstants defined. The constants are <em>MAX_INPUT_FIELD_DISPLAY</em>,<em>IMAGE_DIRECTORY</em>,<em>EDIT_IMAGE_HEIGHT</em>, and <em>MAX_UPLOAD_FILE_SIZE</em>, which are defined in the table below
38 
    </p>
39 
    <table border="1">
40 
      <caption>
41 
         Constants
42 
      </caption>
43 
      <thead>
44 
        <tr>
45 
          <th>
46 
             Constant
47 
          </th>
48 
          <th>
49 
             Type
50 
          </th>
51 
          <th>
52 
             Use
53 
          </th>
54 
          <th>
55 
             Example
56 
          </th>
57 
        </tr>
58 
      </thead>
59 
      <tbody>
60 
        <tr>
61 
          <td>
62 
             MAX_INPUT_FIELD_DISPLAY
63 
          </td>
64 
          <td>
65 
             Integer
66 
          </td>
67 
          <td>
68 
             Determines the display width of text entry fields
69 
          </td>
70 
          <td>
71 
             define ( MAX_INPUT_FIELD_DISPLAY, 80 );
72 
          </td>
73 
        </tr>
74 
        <tr>
75 
          <td>
76 
             MAX_TEXTAREA_HEIGHT
77 
          </td>
78 
          <td>
79 
             Integer
80 
          </td>
81 
          <td>
82 
             Determines the number of columns for Text fields
83 
          </td>
84 
          <td>
85 
             define ( DEFAULT_TEXTAREA_HEIGHT, 5 );
86 
          </td>
87 
        </tr>
88 
        <tr>
89 
          <td>
90 
             IMAGE_DIRECTORY
91 
          </td>
92 
          <td>
93 
             Text
94 
          </td>
95 
          <td>
96 
             Relative URL to images whose links are stored in database
97 
          </td>
98 
          <td>
99 
             define ( IMAGE_DIRECTORY, '/pictures/' );
100 
          </td>
101 
        </tr>
102 
        <tr>
103 
          <td>
104 
             EDIT_IMAGE_HEIGHT
105 
          </td>
106 
          <td>
107 
             Integer
108 
          </td>
109 
          <td>
110 
             Height (in pixels) of thumbnails in edit area
111 
          </td>
112 
          <td>
113 
             define ( EDIT_IMAGE_HEIGHT, 100 );
114 
          </td>
115 
        </tr>
116 
        <tr>
117 
          <td>
118 
             MAX_UPLOAD_FILE_SIZE
119 
          </td>
120 
          <td>
121 
             Integer
122 
          </td>
123 
          <td>
124 
             Maximum size of upload file allowed
125 
          </td>
126 
          <td>
127 
             define ( MAX_UPLOAD_FILE_SIZE, 1024*1024*10 );
128 
          </td>
129 
        </tr>
18 rodolico 130 
        <tr>
131 
          <td>
132 
             CHILD_KEY_INSERT_TAG
133 
          </td>
134 
          <td>
135 
             String
136 
          </td>
137 
          <td>
138 
             This value is used to indicate an insert from an edit of a child table. See note in "children" for a fuller explaination.
139 
          </td>
140 
          <td>
141 
             define ( CHILD_KEY_INSERT_TAG, 'new');
142 
          </td>
143 
        </tr>
144 
        <tr>
145 
          <td>
146 
             CHILD_KEY_DELIMITER
147 
          </td>
148 
          <td>
149 
             String
150 
          </td>
151 
          <td>
152 
             This value is used to separate components of INPUT names in an edit of a child table. See note in "children" for a fuller explaination.
153 
          </td>
154 
          <td>
155 
             define ( CHILD_KEY_DELIMITER, '-' );
156 
          </td>
157 
        </tr>
158 
        <tr>
159 
          <td>
160 
             CHILD_KEY_TAG
161 
          </td>
162 
          <td>
163 
             String
164 
          </td>
165 
          <td>
166 
             This value is used to indicate an update from an edit of a child table. See note in "children" for a fuller explaination.
167 
          </td>
168 
          <td>
169 
             define ( CHILD_KEY_TAG, 'child_table' );
170 
          </td>
171 
        </tr>
1 rodolico 172 
      </tbody>
173 
    </table>
174 
    <p>
175 
      <em>$DATABASE_DEFINITION</em> is a multi-level hash and must be defined as global. Since it is multi-level, this document will work on a per-layer basis
176 
    </p>
177 
    <p>
178 
       At the top level, <em>$DATABASE_DEFINITION</em> is a hash of table definitions within the database. Each table to be directly edited must have a separat entry. Thus, if we are insterested in the tables table1, table2 and table3, our <em>$DATABASE_DEFINITION</em> definition would like like this
179 
    </p>
180 
    <pre> global $DATABASE_DEFINITION;
181 
$DATABASE_DEFINITION = array(
182 
         'table1' => array( <span style="font-style : oblique;">table1 definition here</span>),
183 
         'table2' => array( <span style="font-style : oblique;">table2 definition here</span>),
184 
         'table3' => array( <span style="font-style : oblique;">table3 definition here</span>)
185 
                            );
186 
    </pre>
187 
    <p>
188 
       Each table definition is, as noted above, an addition hash. The table definition hash consists of the following keys
189 
    </p>
190 
    <table border="1">
191 
      <caption>
192 
         Table Definition Hash Keys
193 
      </caption>
194 
      <thead>
195 
        <tr>
196 
          <th>
197 
             Key
198 
          </th>
199 
          <th>
200 
             Type
201 
          </th>
202 
          <th>
203 
             Use
204 
          </th>
205 
          <th>
206 
             Example
207 
          </th>
208 
        </tr>
209 
      </thead>
210 
      <tbody>
211 
        <tr>
212 
          <td>
213 
             table name
214 
          </td>
215 
          <td>
216 
             String
217 
          </td>
218 
          <td>
219 
             Name of current table
220 
          </td>
221 
          <td>
222 
             'table name' => '_global'
223 
          </td>
224 
        </tr>
225 
        <tr>
226 
          <td>
227 
             display name
228 
          </td>
229 
          <td>
230 
             String
231 
          </td>
232 
          <td>
233 
             Alternate text to display for table name
234 
          </td>
235 
          <td>
236 
             'display name' => 'Global'
237 
          </td>
238 
        </tr>
239 
        <tr>
240 
          <td>
241 
             key field
242 
          </td>
243 
          <td>
244 
             Text or Array of Text
245 
          </td>
246 
          <td>
247 
             List of key fields for table
248 
          </td>
249 
          <td>
250 
             'key field' => 'description',
251 
          </td>
252 
        </tr>
253 
        <tr>
254 
          <td>
255 
             display columns
256 
          </td>
257 
          <td>
258 
             Array of Text
259 
          </td>
260 
          <td>
261 
             List of columns to be displayed when selecting record to edit
262 
          </td>
263 
          <td>
264 
             'display columns' => array('value','description')
265 
          </td>
266 
        </tr>
267 
        <tr>
268 
          <td>
269 
             display query
270 
          </td>
271 
          <td>
272 
             SQL Query Sting
273 
          </td>
274 
          <td>
275 
             Query to be executed to display list when multiple rows of a table are displayed. Basis for 'display columns' above. <strong>Must include the keyfield</strong>
276 
          </td>
277 
          <td>
278 
             'display query' => 'select value,description from _global'
279 
          </td>
280 
        </tr>
18 rodolico 281 
       <tr>
282 
          <td>
283 
             new record indicator
284 
          </td>
285 
          <td>
286 
             array of columns
287 
          </td>
288 
          <td>
289 
             Array of columns, any one of which would indicate that a new record template had data entered into it. This should be one or more of the required fields, and is used as an indicator in function updateData when processing child tables that the single row used for adding a new entry had been updated and should be processed.
290 
          </td>
291 
          <td>
292 
             'new record indicator' => array('value')
293 
          </td>
294 
        </tr>
1 rodolico 295 
        <tr>
296 
          <td>
297 
             field info
298 
          </td>
299 
          <td>
300 
             Hash
301 
          </td>
302 
          <td>
303 
             Hash of Column Definitions for Table
304 
          </td>
305 
          <td>
306 
             'field info' => array(<em>Field Definition List</em>)
307 
          </td>
308 
        </tr>
309 
        <tr>
310 
          <td>
311 
             complex join
312 
          </td>
313 
          <td>
314 
             Hash
315 
          </td>
316 
          <td>
317 
             Hash of one or more 'complex join' relationship definitions. See the limited definition below
318 
          </td>
319 
          <td>
320 
             'complex join' => array(<em>complex join Definitions</em>)
321 
          </td>
322 
        </tr>
323 
      </tbody>
324 
    </table>
325 
    <p>
326 
       The term <em>complex join</em> is not used in the standard way here. It is simply the way I use to describe the layout where two tables are related via an intermediate table. This intermediate table stores a key field for each table being joined, so it should be a many-to-many relationship, but I was having a bad night when I wrote this. So, until I go through and change all the code, it is called complex join
327 
    </p>
328 
    <p>
329 
       The 'field info' hash contains information about each column or field in the table. Each field is signified by its name (the key to the hash), followed by its attributes as in:
330 
      <br>
331 
      <em>'fieldname' => array('attribute' => value, 'attribute' => value)</em>
332 
      <br>
333 
       See the following table
334 
    </p>
335 
    <table border="1">
336 
      <caption>
337 
         Field Definition Attributes
338 
      </caption>
339 
      <thead>
340 
        <tr>
341 
          <th>
342 
             Attribute
343 
          </th>
344 
          <th>
345 
             Type
346 
          </th>
347 
          <th>
348 
             Use
349 
          </th>
350 
          <th>
351 
             Example
352 
          </th>
353 
        </tr>
354 
      </thead>
355 
      <tbody>
356 
        <tr>
357 
          <td>
358 
             type
359 
          </td>
360 
          <td>
361 
             String
362 
          </td>
363 
          <td>
364 
             Type of This column. Valid Types are shown in following table
365 
          </td>
366 
          <td>
367 
             'type' => 'string'
368 
          </td>
369 
        </tr>
370 
        <tr>
371 
          <td>
372 
             display name
373 
          </td>
374 
          <td>
375 
             String
376 
          </td>
377 
          <td>
378 
             In most cases, if this exists it will be displayed on edit screens instead of the actual column name
379 
          </td>
380 
          <td>
381 
             'display name' => 'Nice Label'
382 
          </td>
383 
        </tr>
384 
        <tr>
385 
          <td>
386 
             width
387 
          </td>
388 
          <td>
389 
             Integer
390 
          </td>
391 
          <td>
392 
             Maximum Width of Text Field, or number of columns for textarea
393 
          </td>
394 
          <td>
395 
             'width' => 64
396 
          </td>
397 
        </tr>
398 
        <tr>
399 
          <td>
400 
             height
401 
          </td>
402 
          <td>
403 
             Integer
404 
          </td>
405 
          <td>
406 
             Number of rows for textarea (<em>'type'=>'text'</em>)
407 
          </td>
408 
          <td>
409 
             'height' => 64
410 
          </td>
411 
        </tr>
412 
        <tr>
413 
          <td>
414 
             required
415 
          </td>
416 
          <td>
417 
             Boolean
418 
          </td>
419 
          <td>
420 
             If non-zero (or true), form is not processed unless this field has a value unless <em>default</em> below is defined
421 
          </td>
422 
          <td>
423 
             'required' => true
424 
          </td>
425 
        </tr>
426 
        <tr>
427 
          <td>
428 
             default
429 
          </td>
430 
          <td>
431 
             String
432 
          </td>
433 
          <td>
434 
             Default value for field if is is null or empty
435 
          </td>
436 
          <td>
437 
             'default' => 'No Entry Made'
438 
          </td>
439 
        </tr>
440 
        <tr>
441 
          <td>
442 
             keyfield
443 
          </td>
444 
          <td>
445 
             Boolean
446 
          </td>
447 
          <td>
448 
             If set to non-zero or true, this is a key field
449 
          </td>
450 
          <td>
451 
             'keyfield' => true
452 
          </td>
453 
        </tr>
454 
        <tr>
455 
          <td>
456 
             height
457 
          </td>
458 
          <td>
459 
             Integer
460 
          </td>
461 
          <td>
462 
             Height of textarea box, in lines.
463 
          </td>
464 
          <td>
465 
             'height' => 5
466 
          </td>
467 
        </tr>
468 
        <tr>
469 
          <td>
470 
             filetype
471 
          </td>
472 
          <td>
473 
             String
474 
          </td>
475 
          <td>
476 
             For use in File type only, defines the file type to be a picture
477 
          </td>
478 
          <td>
479 
             'filetype' => 'picture'
480 
          </td>
481 
        </tr>
482 
      </tbody>
483 
    </table>
484 
    <table border="1">
485 
      <caption>
486 
         Valid Data Types
487 
      </caption>
488 
      <thead>
489 
        <tr>
490 
          <th>
491 
             Data Type
492 
          </th>
493 
          <th>
494 
             Database Types
495 
          </th>
496 
          <th>
497 
             Use
498 
          </th>
499 
          <th>
500 
             Notes
501 
          </th>
502 
        </tr>
503 
      </thead>
504 
      <tbody>
505 
        <tr>
506 
          <td>
507 
             string
508 
          </td>
509 
          <td>
510 
             varchar or char
511 
          </td>
512 
          <td>
513 
             Holds up to <em>'width'</em> characters of Data
514 
          </td>
515 
          <td>
516 
             'type' => 'string'
517 
          </td>
518 
        </tr>
519 
        <tr>
520 
          <td>
521 
             text
522 
          </td>
523 
          <td>
524 
             text or blob type 1
525 
          </td>
526 
          <td>
527 
             Holds unlimited text, with line returns, etc...
528 
          </td>
529 
          <td>
530 
          </td>
531 
        </tr>
532 
        <tr>
533 
          <td>
534 
             file
535 
          </td>
536 
          <td>
537 
             blob
538 
          </td>
539 
          <td>
540 
             Stores result of a file input field into the column
541 
          </td>
542 
          <td>
543 
          </td>
544 
        </tr>
545 
        <tr>
546 
          <td>
547 
             bool
548 
          </td>
549 
          <td>
550 
             char
551 
          </td>
552 
          <td>
553 
             On data entry, stores 1 or 0. Any non-zero value assumed to be true
554 
          </td>
555 
          <td>
556 
          </td>
557 
        </tr>
558 
        <tr>
559 
          <td>
560 
             int
561 
          </td>
562 
          <td>
563 
             int
564 
          </td>
565 
          <td>
566 
             Standard Integer
567 
          </td>
568 
          <td>
569 
          </td>
570 
        </tr>
571 
        <tr>
572 
          <td>
573 
             float
574 
          </td>
575 
          <td>
576 
             decimal
577 
          </td>
578 
          <td>
579 
             Floating Point Number
580 
          </td>
581 
          <td>
582 
          </td>
583 
        </tr>
584 
        <tr>
585 
          <td>
586 
             lookup
587 
          </td>
588 
          <td>
589 
             Integer
590 
          </td>
591 
          <td>
592 
             Field is an integer which is a foreign key into a different table.
593 
          </td>
594 
          <td>
595 
          </td>
596 
        </tr>
597 
      </tbody>
598 
    </table>
599 
    <p>
600 
       Foreign Keys have their own set of attributes. A lookup field type is assumed to be a 1:1 key into a separate table. As such, the following attributes are defined only for lookup data types, and these are the only locations these attributes are found.
601 
    </p>
602 
    <p>
603 
       Foreign Keys are displayed as Select boxes, with the value being the keyfield of the foreign table and the displayed value determined by the field definition (see table)
604 
    </p>
605 
    <table border="1">
606 
      <caption>
607 
         Foreign Key Attributes
608 
      </caption>
609 
      <thead>
610 
        <tr>
611 
          <th>
612 
             Attribute
613 
          </th>
614 
          <th>
615 
             Type
616 
          </th>
617 
          <th>
618 
             Use
619 
          </th>
620 
          <th>
621 
             Example
622 
          </th>
623 
        </tr>
624 
      </thead>
625 
      <tbody>
626 
        <tr>
627 
          <td>
628 
             table
629 
          </td>
630 
          <td>
631 
             String
632 
          </td>
633 
          <td>
634 
             Target table of join
635 
          </td>
636 
          <td>
637 
             'table' => 'category'
638 
          </td>
639 
        </tr>
640 
        <tr>
641 
          <td>
642 
             keyfield
643 
          </td>
644 
          <td>
645 
             String
646 
          </td>
647 
          <td>
648 
             Column name of keyfield in remote table
649 
          </td>
650 
          <td>
651 
             'keyfield' => 'category_id'
652 
          </td>
653 
        </tr>
654 
        <tr>
655 
          <td>
656 
             display_field
657 
          </td>
658 
          <td>
659 
             text
660 
          </td>
661 
          <td>
662 
             Column Name whose value is displayed to user for selection
663 
          </td>
664 
          <td>
665 
             'display_field' => 'description'
666 
          </td>
667 
        </tr>
668 
      </tbody>
669 
    </table>
670 
    <p>
671 
       Many To Many Relationships (name here is one-to-many) are a special attribute of a table. In this case, the user may select many items for the current record to be related to. 'complex join' definitions must have the following underlying table structure
672 
    </p>
673 
    <ul>
674 
      <LI>
675 
         Foreign Table with single Primary Key Entry of type int
676 
      </LI>
677 
      <li>
678 
         Intermediary Table must contain a single int column relating to current table
679 
      </li>
680 
      <li>
681 
         Intermediary Table must contain a single int column relating to foreign table
682 
      </li>
683 
      <li>
684 
         Primary Key for intermediary table must consist solely of the two columns above
685 
      </li>
686 
    </ul>
687 
    <p>
688 
       The <em>complex join</em> entry is itself a hash, consisting of one or more separate relationships. The Key of the hash is the display name on the editing screens.
689 
    </p>
690 
    <pre> 'complex join' => array(
691 
                    'Targets' => array(<span style="font-style : oblique;">Targets Definition</span>),
692 
                    'Other' => array(<span style="font-style : oblique;">Other Definition</span>)
693 
                 )
694 
    </pre>
695 
    <p>
696 
       Each definition contains three attributes in their hash; <em>null field</em>, and two hashes <em>values table</em> and a <em>join table</em>. The following table shows each attribute and its sub-attributes.
697 
    </p>
698 
    <table border='1'>
699 
      <caption>
700 
         'complex join' entry Attributes
701 
      </caption>
702 
      <thead>
703 
        <tr>
704 
          <th>
705 
             Parent Attribute
706 
          </th>
707 
          <th>
708 
             Attribute
709 
          </th>
710 
          <th>
711 
             Type
712 
          </th>
713 
          <th>
714 
             Description
715 
          </th>
716 
          <th>
717 
             Notes
718 
          </th>
719 
        </tr>
720 
      </thead>
721 
      <tbody>
722 
        <tr>
723 
          <td>
724 
             null field
725 
          </td>
726 
          <td>
727 
          </td>
728 
          <td>
729 
             String
730 
          </td>
731 
          <td>
732 
             Unknown what this function is at this time
733 
          </td>
734 
          <td>
735 
          </td>
736 
        </tr>
737 
        <tr>
738 
          <td>
739 
             values table
740 
          </td>
741 
          <td>
742 
             table name
743 
          </td>
744 
          <td>
745 
             string
746 
          </td>
747 
          <td>
748 
             name of table that holds values to be displayed
749 
          </td>
750 
          <td>
751 
          </td>
752 
        </tr>
753 
        <tr>
754 
          <td>
755 
             values table
756 
          </td>
757 
          <td>
758 
             join condition
759 
          </td>
760 
          <td>
761 
             string
762 
          </td>
763 
          <td>
764 
             Not currently used
765 
          </td>
766 
          <td>
767 
             This was originally used to define the join from the intermediary table to the target table, but is no longer implemented
768 
          </td>
769 
        </tr>
770 
        <tr>
771 
          <td>
772 
             values table
773 
          </td>
774 
          <td>
775 
             display field
776 
          </td>
777 
          <td>
778 
             string
779 
          </td>
780 
          <td>
781 
             name of field to be displayed on edit
782 
          </td>
783 
          <td>
784 
             Do Not include the table name, ie do not use tablename.columnname here
785 
          </td>
786 
        </tr>
787 
        <tr>
788 
          <td>
789 
             values table
790 
          </td>
791 
          <td>
792 
             key field
793 
          </td>
794 
          <td>
795 
             string
796 
          </td>
797 
          <td>
798 
             Name of key field which is used to join to intermediary table
799 
          </td>
800 
          <td>
801 
             Do Not include the table name, ie do not use tablename.columnname here
802 
          </td>
803 
        </tr>
804 
        <tr>
805 
          <td>
806 
             join table
807 
          </td>
808 
          <td>
809 
             table name
810 
          </td>
811 
          <td>
812 
             String
813 
          </td>
814 
          <td>
815 
             Name of table used to join current table to values table
816 
          </td>
817 
          <td>
818 
             Note: This is the intermediary Table name
819 
          </td>
820 
        </tr>
821 
        <tr>
822 
          <td>
823 
             join table
824 
          </td>
825 
          <td>
826 
             values link
827 
          </td>
828 
          <td>
829 
             String
830 
          </td>
831 
          <td>
7 rodolico 832 
             Name of column in intermediate table (join table) that links to other table (values table)
1 rodolico 833 
          </td>
834 
          <td>
835 
             Do Not include the table name, ie do not use tablename.columnname here
836 
          </td>
837 
        </tr>
838 
        <tr>
839 
          <td>
840 
             join table
841 
          </td>
842 
          <td>
843 
             my link
844 
          </td>
845 
          <td>
846 
             String
847 
          </td>
848 
          <td>
7 rodolico 849 
             Name of column in intermediate table (join table) that links to this column in this table
1 rodolico 850 
          </td>
851 
          <td>
852 
             Do Not include the table name, ie do not use tablename.columnname here
853 
          </td>
854 
        </tr>
855 
        <tr>
856 
          <td>
857 
             join table
858 
          </td>
859 
          <td>
860 
             join condition
861 
          </td>
862 
          <td>
863 
             string
864 
          </td>
865 
          <td>
866 
             Not currently used
867 
          </td>
868 
          <td>
869 
             This was originally used to define the join from the intermediary table to the target table, but is no longer implemented
870 
          </td>
871 
        </tr>
872 
      </tbody>
873 
    </table>
16 rodolico 874 
    <h3>children</h3>
18 rodolico 875 
    <p>children is the way to define one or more child tables. A child table is similar to a lookup table, but it is more complex in that it may have multiple display columns, may be joined to other tables, etc... However, a child table is a direct descendant of the current table, ie it will not join to another row in the current table.</p>
16 rodolico 876 
    <p>children only has two values; the name of the table which is a child, and the column in the child table that is used for the join. If the latter is missing, it is assumed to be the same as the primary key of the current table.</p>
18 rodolico 877 
    <p>During edit, all rows in the child table belonging to the current table are displayed in tabular form, using the 'display query' defined in that table. This can cause a more complex setup as we have multiple rows in an HTML table containing data on the same column, but each HTML &lt;INPUT&gt; should have a unique name in order to be processed.</p>
878 
    <p>To fix this, the library will give a unique name to each item, based on the column name, a constant (global constant CHILD_KEY_TAG), the table name from which the data is drawn, and the unique row-id (ie, a 'key field' entry) for the row being edited. These values are separated by a delimiter (global constant CHILD_KEY_DELIMITER).</p>
879 
    <p>Additionally, a "blank" row is created in these circumstances to allow the user to enter a new record if they desire. This will take the same form as the previous paragraph, except that the row-id is replaced by a special indicator (global constant CHILD_KEY_INSERT_TAG)</p>
880 
    <p>The name of the edit for an existing key is therefore calculated as:<br>
881 
       <em>fieldname</em> . CHILD_KEY_DELIMITER . CHILD_KEY_TAG . CHILD_KEY_DELIMITER . <em>tablename</em> . CHILD_KEY_DELIMITER . <em>primary_key_value_of_row</em> <br>
882 
      and the name for the single "blank" record is calculated as:<br>
883 
      <em>fieldname</em> . CHILD_KEY_DELIMITER . CHILD_KEY_TAG . CHILD_KEY_DELIMITER . <em>tablename</em> . CHILD_KEY_DELIMITER . CHILD_KEY_INSERT_TAG
884 
    </p>
885 
    <p>
886 
       This gives rise to entries on the HTML form as follows, the first being an edit of the username field of a child table <em>login</em> whose row id is 5, and the second being a blank record to add a new row.
887 
    </p>
888 
<ul><LI>       &lt;td&gt;&lt;input type='text' name='<em>username</em>-child_table-<em>login</em>-<em>5</em>' value='jane@example.com'&gt;</li><li>
889 
       &lt;td&gt;&lt;input type='text' name='<em>username</em>-child_table-<em>login</em>-<em>new</em>' value=''&gt;
890 
</LI></ul>
891 
<p>The above example assumes the following definitions in yoru database definition file</p>
892 
<pre>
893 
   define ( CHILD_KEY_INSERT_TAG, 'new');
894 
   define ( CHILD_KEY_DELIMITER, '-' );
895 
   define ( CHILD_KEY_TAG, 'child_table' );
896 
</pre>
897 
<p><strong>Note:</strong> You are responsible for ensuring the CHILD_KEY_DELIMITER is not found within field or table names. If you tend to use underscores in your field or table names (like I do), you can not use them as the delimiter. This needs to be a delimiter which is legitimate as the name of an HTML entity and is not  found in the table name, column name or key field value</p>
898 
 
1 rodolico 899 
    <h3>Example</h3>
18 rodolico 900 
    <p>Following example is based upon a real life application that stores knowledge Computer Asset Management Program. This program is set up to have multiple sites per client, with each site having multiple pieces of equipment (devices). Each device can have multiple attributes.</p>
1 rodolico 901 
    <pre>
18 rodolico 902 
   define ( MAX_INPUT_FIELD_DISPLAY, 40 ); // this is the maximum input field size
1 rodolico 903 
   define ( IMAGE_DIRECTORY, '/pictures/' );  // relative URL where pictures are stored
18 rodolico 904 
   define ( EDIT_IMAGE_HEIGHT, 100 );         // height for thumbnail of pictures
1 rodolico 905 
   define ( MAX_UPLOAD_FILE_SIZE, 1024*1024*10 ); // 10 meg
18 rodolico 906 
   define ( CHILD_KEY_INSERT_TAG, 'new');
907 
   define ( CHILD_KEY_DELIMITER, '-' );
908 
   define ( CHILD_KEY_TAG, 'child_table' );
909 
   define ( DEFAULT_TEXTAREA_HEIGHT, 5 ); // number of rows a textarea will default to
910 
   define ( DEFAULT_TABLE, 'client');     // the table that will show up in doAdmin by default
1 rodolico 911 
 
912 
    global $DATABASE_DEFINITION;
913 
    $DATABASE_DEFINITION = array(
18 rodolico 914 
      'client' => array(
915 
              'table name' => 'client',
916 
              'key field' => 'client_id',
917 
              'display columns' => array('client_id','name'),
918 
              'display query' => 'select client_id,name from client',
1 rodolico 919 
              'field info' => array(
18 rodolico 920 
                      'client_id' => array('keyfield' => 1 , 'required' => true , 'readonly' => true , 'type' => 'int' , 'width' => 10),
921 
                      'name' => array('type' => 'string' , 'width' => 64),
922 
                      'notes' => array('type' => 'text', 'width'=> 80 ),
923 
                      'internal_notes' => array('type' => 'text', 'width'=> 80 ),
924 
                      'added_date' => array('type' => 'date', 'default' => date('Y-m-d H:i:s')),
925 
                      'removed_date' => array('type' => 'date', 'default' => 'null')
926 
              )
1 rodolico 927 
      ),
18 rodolico 928 
      'site' => array(
929 
              'table name' => 'site',
930 
              'key field' => 'site_id',
931 
              'display columns' => array('site_id','name'),
932 
              'display query' => 'select site_id,name from site',
1 rodolico 933 
              'field info' => array(
18 rodolico 934 
                      'site_id' => array('keyfield' => 1 , 'required' => true , 'readonly' => true , 'type' => 'int' , 'width' => 10),
935 
                      'client_id' => array( 'type' => 'lookup',   // this is the field type, and must be ints
936 
                                            'table' => 'client',    // remote table name
937 
                                            'keyfield' => 'client_id',  // keyfield in remote table, ie category.category_id
938 
                                            'display_field' => 'name' // this is the column displayed to the user
939 
                                          ),
940 
                      'name' => array('type' => 'string' , 'width' => 64),
941 
                      'notes' => array('type' => 'text', 'width'=> 80 ),
942 
                      'added_date' => array('type' => 'date', 'default' => date('Y-m-d H:i:s') ),
943 
                      'removed_date' => array('type' => 'date', 'default' => 'null' )
1 rodolico 944 
              )
945 
      ),
18 rodolico 946 
      'device' => array(
947 
              'table name' => 'device',
948 
              'key field' => 'device_id',
1 rodolico 949 
              'display columns' => array('name'),
18 rodolico 950 
              'display query' => 'select device_id,name from device',
1 rodolico 951 
              'field info' => array(
18 rodolico 952 
                      'device_id' => array('keyfield' => 1 , 'required' => true , 'readonly' => true , 'type' => 'int' , 'width' => 10),
953 
                      'name' => array('required' => true , 'default' => '' , 'type' => 'string' , 'width' => 255),
954 
                      'part_of' => array( 'type' => 'lookup',   // this is the field type, and must be ints
955 
                                            'table' => 'device',    // remote table name
956 
                                            'keyfield' => 'device_id',  // keyfield in remote table, ie category.category_id
957 
                                            'display_field' => 'name', // this is the column displayed to the user
958 
                                            'null_ok' => true
959 
                                          ),
960 
                      'device_type_id' => array( 'type' => 'lookup',   // this is the field type, and must be ints
961 
                                            'table' => 'device_type',    // remote table name
962 
                                            'keyfield' => 'device_type_id',  // keyfield in remote table, ie category.category_id
1 rodolico 963 
                                            'display_field' => 'name' // this is the column displayed to the user
964 
                                          ),
18 rodolico 965 
 
966 
                      'site_id' =>  array( 'type' => 'lookup',   // this is the field type, and must be ints
967 
                                            'query' => "select site_id,concat(client.name, ' - ', site.name) from site join client on site.client_id = client.client_id order by client.name,site.name",
968 
                                            'table' => 'site',    // remote table name
969 
                                            'keyfield' => 'site_id',  // keyfield in remote table, ie category.category_id
970 
                                            'display_field' => 'name' // this is the column displayed to the user
971 
                                          ),
972 
                      'notes' => array('type' => 'text', 'width'=> 80 ),
973 
                      'name' => array('required' => true , 'default' => '' , 'type' => 'string' , 'width' => 64),
974 
                      'added_date' => array('type' => 'date', 'default' => date('Y-m-d H:i:s')),
975 
                      'removed_date' => array('type' => 'date', 'default' => 'null')
976 
              ),
977 
       'child tables' => array (
978 
             'device_attrib' => array( 'table name' => 'device_attrib' )
979 
       )
980 
    ),
981 
      'device_attrib' => array(
982 
              'display name' => 'Device Attributes',
983 
              'table name' => 'device_attrib',
984 
              'key field' => 'device_attrib_id',
985 
              'new record indicator' => array('value'),
986 
              'display columns' => array('name'),
987 
              'display query' => 'select device_attrib_id,attrib.name, device_attrib.value from device_attrib join attrib using (attrib_id)',
988 
              'field info' => array(
989 
                      'device_attrib_id' => array('keyfield' => 1 ,
990 
                                                  'required' => true ,
991 
                                                  'readonly' => true ,
992 
                                                  'type' => 'int' ,
993 
                                                  'width' => 10,
994 
                                                  'display name' => 'ID'
995 
                                                  ),
996 
                      'device_id' => array ( 'type' => 'lookup',   // this is the field type, and must be ints
997 
                                            'table' => 'device',    // remote table name
998 
                                            'keyfield' => 'device_id',  // keyfield in remote table, ie category.category_id
999 
                                            'display_field' => 'name', // this is the column displayed to the user
1000 
                                            'null_ok' => false,
1001 
                                            'display name' => 'Device'),
1002 
                      'attrib_id' => array( 'type' => 'lookup',   // this is the field type, and must be ints
1003 
                                            'table' => 'attrib',    // remote table name
1004 
                                            'keyfield' => 'attrib_id',  // keyfield in remote table, ie category.category_id
1005 
                                            'display_field' => 'name', // this is the column displayed to the user
1006 
                                            'null_ok' => false,
1007 
                                            'display name' => 'Attribute'
1008 
                                          ),
1009 
                      'value' => array('type' => 'text', 'required' => true, 'width'=> 40, 'height' => 1, 'display name' => 'Value' ),
1010 
                      'added_date' => array('type' => 'date', 'default' => date('Y-m-d H:i:s'), 'display name' => 'Date Added'),
1011 
                      'removed_date' => array('type' => 'date', 'default' => 'null', 'display name' => 'Date Removed')
1012 
              )
1013 
       )
1 rodolico 1014 
    );
1015 
    </pre>
1016 
    <p>Modification required for update to new naming convention. In old source code, do the following search and replaces:</p>
1017 
    <ul><LI>s/foreignkey/lookup/</li>
1018 
<li>s/one to many/complex join/
1019 
</LI></ul>
1020 
  </body>
1021 
</html>
1022 
 
1023