modules/computed_field/README.txt

------------------The Computed Field Drupal Module----------------------------

Computed Field is a cck module which lets you add a computed field to custom
content types. You can choose whether to store your computed field in the
database. You can also choose whether to display the field, and how to format
it. The value of the field is set using php code, so it can draw on anything
available to drupal, including other fields, the current user, database
tables, etc. The drawback of this is of course that you need to know some php
to use it.

Computed Field requires the content module (cck).

-------------------------Update-------------------------------

As of 2006-8-11 the 'display format' setting has changed. You'll need to
update any existing computed fields: If your display format was 'This is the
value: %value', then change it to '$display = "This is the value: " .
$node_field_item['value'];'


-------------------------Usage--------------------------------

----------Getting Started-----------------------------------

Before you can use Computed Field, you'll need to get CCK and enable (at the
very least) the 'content' module. You will probably also want to enable the
other cck modules, such as 'text', 'number', 'date', etc.

To add a computed field to a content type, go to administer > content >
content types, select the content type you want to add to, and click on the
'add field' tab. One of the field types available should be 'Computed', and it
should have one bullet point under it, also labelled 'Computed'. If you select
this, give your field a name, and submit the form, you will get to the
configuration page for your new computed field.


--------Configuration---------------------------------------

A Computed Field can be configured with the usual cck field options, as well
as the following extra options:

Computed Code -- This is the code that will assign a value to your computed
field. It should be valid php without the <?php ?> tags.

Display this field -- Check this box to have this field appear on your node
view pages. You will usually want this unless you want your field to be a
hidden value.

Display Format -- This is also php code which should assign a string to the
$display variable. It has '$node_field_item['value']' available, which is the
value of the computed field. It also has '$field' available, and you can call
any drupal functions you want to display your field.

Store using the database settings below -- If this is checked then the field
is computed on node save and stored. If it isn't stored then it will be
recomputed every time you view a node containing this field.

Database Storage Settings
	Data Type -- This is the sql data type to use to store the field. Let us
	know if you need any other storage types, or if you would like an 'other'
	option :).

	Data Length -- This value will simply be passed on to sql. For storing up
	to 10 digit ints, enter 10. For storing currency as a float, use 10,2
	(unless you'll store larger than 10 figure amounts!).  For storing
	usernames or other short text with a varchar field, 64 may be appropriate.

	Default Value -- Leave this blank if you don't want the database to store
	a default value if your computed field's value isn't set.

	Not NULL -- Leave unchecked if you want to allow NULL values in the
	database field.

	Sortable  -- Used in Views to allow sorting a column of this field.


--------Examples------------------------------------------

Here are some usage examples to get you started with Computed
Field. 

-----Make a node link to itself-----------------

This example isn't very useful, but it demonstrates how to get
hold of the nid.

In your computed field's configuration:

- Computed Code:
// ensure the node has an id by saving it if it is new.
if (!$node->nid) node_save($node);
// store the nid in our computed field
$node_field[0]['value'] = $node->nid;

- Check 'Display this field'

- Display Format:
$display = l('A link to this node', 'node/'.$node_field_item['value']);

- Uncheck 'Store using the database settings below'. You could store this if
  you wanted to, but it's not costly to compute this field and is already
  stored in the node table. One reason why you may want to store it is if you
  want the value available to Views.

When you display a node of the content type containing this field it should
now have a link to itself.

-----Adding two other fields----------------------
Imagine you have two existing number fields, called field_product_price and
field_postage_price. You want to create a computed field field_total_cost
which adds these two fields. Create a new computed field with the name 'Total
Cost', and in your computed field's configuration set the following:

- Computed Code:
$node_field[0]['value'] =
$node->field_product_price[0]['value'] +
$node->field_postage_price[0]['value'];

- Check 'Display this field'

- Display Format:
$display = '$' . $node_field_item['value'];

- Check 'Store using the database settings below'

- Data Type: float

- Data Length: 10,2

- Default Value: 0.00

- Check 'Not NULL'

- Check 'Sortable'


-----Calculating a Duration given a start and end time-----

This example uses KarenS' date module (http://drupal.org/project/date) to
create two date fields field_start_time and field_end_time which record hours
and minutes. We then create a new computed field to work out the duration as a
decimal number of hours (so 1.5 is 1hour, 30minutes).

Computed field settings:

- Computed Code:
$start = $node->field_start_time[0]['value'];
$end = $node->field_end_time[0]['value'];
$start_decimal = $start['hours'] + ($start['minutes'] / 60);
$end_decimal = $end['hours'] + ($end['minutes'] / 60);
$node_field[0]['value'] = $end_decimal - $start_decimal;

- Check 'Display this field'</li>

- Display Format:</b><code>
$display = $node_field_item['value'] . " hours";

- Check 'Store using the database settings below

- Data Type:</b> float

- Data Length:</b> 3,2

- Check 'Sortable'

Now if you set the start time field to 9am and the end time to 11:30am, your
computed field will store the value '2.5' and display '2.5 hours'.


-----Send more examples!---------------------------------

If you have another useful (or instructive) example send it to me
(http://drupal.org/user/59132/contact) and I'll add it here for the benefit of
humankind.

-----------------------About Computed Field-----------------------------------
Computed Field was created by Agileware (http://www.agileware.net).

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 this field -- Check this box to have this field appear on your node
46	view pages. You will usually want this unless you want your field to be a
47	hidden value.
48
49	Display Format -- This is also php code which should assign a string to the
50	$display variable. It has '$node_field_item['value']' available, which is the
51	value of the computed field. It also has '$field' available, and you can call
52	any drupal functions you want to display your field.
53
54	Store using the database settings below -- If this is checked then the field
55	is computed on node save and stored. If it isn't stored then it will be
56	recomputed every time you view a node containing this field.
57
58	Database Storage Settings
59	Data Type -- This is the sql data type to use to store the field. Let us
60	know if you need any other storage types, or if you would like an 'other'
61	option :).
62
63	Data Length -- This value will simply be passed on to sql. For storing up
64	to 10 digit ints, enter 10. For storing currency as a float, use 10,2
65	(unless you'll store larger than 10 figure amounts!). For storing
66	usernames or other short text with a varchar field, 64 may be appropriate.
67
68	Default Value -- Leave this blank if you don't want the database to store
69	a default value if your computed field's value isn't set.
70
71	Not NULL -- Leave unchecked if you want to allow NULL values in the
72	database field.
73
74	Sortable -- Used in Views to allow sorting a column of this field.
75
76
77	--------Examples------------------------------------------
78
79	Here are some usage examples to get you started with Computed
80	Field.
81
82	-----Make a node link to itself-----------------
83
84	This example isn't very useful, but it demonstrates how to get
85	hold of the nid.
86
87	In your computed field's configuration:
88
89	- Computed Code:
90	// ensure the node has an id by saving it if it is new.
91	if (!$node->nid) node_save($node);
92	// store the nid in our computed field
93	$node_field[0]['value'] = $node->nid;
94
95	- Check 'Display this field'
96
97	- Display Format:
98	$display = l('A link to this node', 'node/'.$node_field_item['value']);
99
100	- Uncheck 'Store using the database settings below'. You could store this if
101	you wanted to, but it's not costly to compute this field and is already
102	stored in the node table. One reason why you may want to store it is if you
103	want the value available to Views.
104
105	When you display a node of the content type containing this field it should
106	now have a link to itself.
107
108	-----Adding two other fields----------------------
109	Imagine you have two existing number fields, called field_product_price and
110	field_postage_price. You want to create a computed field field_total_cost
111	which adds these two fields. Create a new computed field with the name 'Total
112	Cost', and in your computed field's configuration set the following:
113
114	- Computed Code:
115	$node_field[0]['value'] =
116	$node->field_product_price[0]['value'] +
117	$node->field_postage_price[0]['value'];
118
119	- Check 'Display this field'
120
121	- Display Format:
122	$display = '$' . $node_field_item['value'];
123
124	- Check 'Store using the database settings below'
125
126	- Data Type: float
127
128	- Data Length: 10,2
129
130	- Default Value: 0.00
131
132	- Check 'Not NULL'
133
134	- Check 'Sortable'
135
136
137	-----Calculating a Duration given a start and end time-----
138
139	This example uses KarenS' date module (http://drupal.org/project/date) to
140	create two date fields field_start_time and field_end_time which record hours
141	and minutes. We then create a new computed field to work out the duration as a
142	decimal number of hours (so 1.5 is 1hour, 30minutes).
143
144	Computed field settings:
145
146	- Computed Code:
147	$start = $node->field_start_time[0]['value'];
148	$end = $node->field_end_time[0]['value'];
149	$start_decimal = $start['hours'] + ($start['minutes'] / 60);
150	$end_decimal = $end['hours'] + ($end['minutes'] / 60);
151	$node_field[0]['value'] = $end_decimal - $start_decimal;
152
153	- Check 'Display this field'</li>
154
155	- Display Format:</b><code>
156	$display = $node_field_item['value'] . " hours";
157
158	- Check 'Store using the database settings below
159
160	- Data Type:</b> float
161
162	- Data Length:</b> 3,2
163
164	- Check 'Sortable'
165
166	Now if you set the start time field to 9am and the end time to 11:30am, your
167	computed field will store the value '2.5' and display '2.5 hours'.
168
169
170	-----Send more examples!---------------------------------
171
172	If you have another useful (or instructive) example send it to me
173	(http://drupal.org/user/59132/contact) and I'll add it here for the benefit of
174	humankind.
175
176	-----------------------About Computed Field-----------------------------------
177	Computed Field was created by Agileware (http://www.agileware.net).
178