Various fixes and additional settings for database field storage. Fixes "not NULL...
[project/computed_field.git] / README.txt
1 ------------------The Computed Field Drupal Module----------------------------
2
3 Computed Field is a cck module which lets you add a computed field to custom
4 content types. You can choose whether to store your computed field in the
5 database. You can also choose whether to display the field, and how to format
6 it. The value of the field is set using php code, so it can draw on anything
7 available to drupal, including other fields, the current user, database
8 tables, etc. The drawback of this is of course that you need to know some php
9 to use it.
10
11 Computed Field requires the content module (cck).
12
13 -------------------------Update-------------------------------
14
15 As of 2006-8-11 the 'display format' setting has changed. You'll need to
16 update any existing computed fields: If your display format was 'This is the
17 value: %value', then change it to '$display = "This is the value: " .
18 $node_field_item['value'];'
19
20
21 -------------------------Usage--------------------------------
22
23 ----------Getting Started-----------------------------------
24
25 Before you can use Computed Field, you'll need to get CCK and enable (at the
26 very least) the 'content' module. You will probably also want to enable the
27 other cck modules, such as 'text', 'number', 'date', etc.
28
29 To add a computed field to a content type, go to administer > content >
30 content types, select the content type you want to add to, and click on the
31 'add field' tab. One of the field types available should be 'Computed', and it
32 should have one bullet point under it, also labelled 'Computed'. If you select
33 this, give your field a name, and submit the form, you will get to the
34 configuration page for your new computed field.
35
36
37 --------Configuration---------------------------------------
38
39 A Computed Field can be configured with the usual cck field options, as well
40 as the following extra options:
41
42 Computed Code -- This is the code that will assign a value to your computed
43 field. It should be valid php without the <?php ?> tags.
44
45 Display Format -- This is also php code which should assign a string to the
46 $display variable. It has '$node_field_item['value']' available, which is the
47 value of the computed field. It also has '$field' available, and you can call
48 any drupal functions you want to display your field.
49
50 Store using the database settings below -- If this is checked then the field
51 is computed on node save and stored. If it isn't stored then it will be
52 recomputed every time you view a node containing this field.
53
54 Database Storage Settings
55         Data Type -- This is the sql data type to use to store the field. Let us
56         know if you need any other storage types, or if you would like an 'other'
57         option :).
58
59         Data Length (varchar/text) -- The length of the field in the database. For 
60         storing usernames or other short text with a varchar field, 32 may be 
61         appropriate. Only valid for varchar or text fields.
62         
63         Data Size (int/float) -- The size of the field stored in the database.
64         Only valid for int or float fields.
65         
66         Data Precision (decimal) -- The total number of digits to store in the 
67         database, including those to the right of the decimal. Only valid for 
68         decimal fields. 
69         
70         Data Scale (decimal) -- The number of digits to the right of the decimal.
71         Only valid for decimal fields. 
72
73         Default Value -- Leave this blank if you don't want the database to store
74         a default value if your computed field's value isn't set.
75
76         Not NULL -- Leave unchecked if you want to allow NULL values in the
77         database field.
78
79         Sortable  -- Used in Views to allow sorting a column of this field.
80
81
82 --------Examples------------------------------------------
83
84 Here are some usage examples to get you started with Computed
85 Field. 
86
87 -----Make a node link to itself-----------------
88
89 This example isn't very useful, but it demonstrates how to get
90 hold of the nid.
91
92 In your computed field's configuration:
93
94 - Computed Code:
95 // store the nid in our computed field
96 $node_field[0]['value'] = $node->nid;
97
98 - Check 'Display this field'
99
100 - Display Format:
101 $display = l('A link to this node', 'node/'.$node_field_item['value']);
102
103 - Uncheck 'Store using the database settings below'. You could store this if
104   you wanted to, but it's not costly to compute this field and is already
105   stored in the node table. One reason why you may want to store it is if you
106   want the value available to Views.
107
108 When you display a node of the content type containing this field it should
109 now have a link to itself.
110
111 -----Adding two other fields----------------------
112 Imagine you have two existing number fields, called field_product_price and
113 field_postage_price. You want to create a computed field field_total_cost
114 which adds these two fields. Create a new computed field with the name 'Total
115 Cost', and in your computed field's configuration set the following:
116
117 - Computed Code:
118 $node_field[0]['value'] =
119 $node->field_product_price[0]['value'] +
120 $node->field_postage_price[0]['value'];
121
122 - Check 'Display this field'
123
124 - Display Format:
125 $display = '$' . $node_field_item['value'];
126
127 - Check 'Store using the database settings below'
128
129 - Data Type: decimal
130
131 - Decimal Precision: 10
132
133 - Decimal Scale: 2
134
135 - Default Value: 0.00
136
137 - Check 'Not NULL'
138
139 - Check 'Sortable'
140
141
142 -----Calculating a Duration given a start and end time-----
143
144 This example uses KarenS' date module (http://drupal.org/project/date) to
145 create two date fields field_start_time and field_end_time which record hours
146 and minutes. We then create a new computed field to work out the duration as a
147 decimal number of hours (so 1.5 is 1hour, 30minutes).
148
149 Computed field settings:
150
151 - Computed Code:
152 $start = $node->field_start_time[0]['value'];
153 $end = $node->field_end_time[0]['value'];
154 $start_decimal = $start['hours'] + ($start['minutes'] / 60);
155 $end_decimal = $end['hours'] + ($end['minutes'] / 60);
156 $node_field[0]['value'] = $end_decimal - $start_decimal;
157
158 - Check 'Display this field'</li>
159
160 - Display Format:</b><code>
161 $display = $node_field_item['value'] . " hours";
162
163 - Check 'Store using the database settings below
164
165 - Data Type:</b> float
166
167 - Data Size:</b> normal
168
169 - Check 'Sortable'
170
171 Now if you set the start time field to 9am and the end time to 11:30am, your
172 computed field will store the value '2.5' and display '2.5 hours'.
173
174
175 -----Send more examples!---------------------------------
176
177 If you have another useful (or instructive) example send it to me
178 (http://drupal.org/user/59132/contact) and I'll add it here for the benefit of
179 humankind.
180
181 -----------------------About Computed Field-----------------------------------
182 Computed Field was created by Agileware (http://www.agileware.net).
183