modules/prepopulate/USAGE.txt

$Id: USAGE.txt,v 1.4 2009/10/08 02:29:14 brauerranch Exp $

See README.txt for a description of this module.
See this documentation online at http://drupal.org/node/228167.

USING PREPOPULATE MODULE
========================

Simple Usage
------------

Prepopulate the title field on a node creation form:
  http://www.example.com/node/add/content?edit[title]=This is the title
With 'non-clean' urls:
  http://www.example.com?q=node/add/content&edit[title]=This is the title


POST Requests
-------------
Since Prepopulate uses the $_REQUEST variable, you have access to prepopulate
form values from either GET request in the URL, or the form POST requests. In
the below example, we prepopulate a node form's title based on a POST Request:

<html><body>
  <form method="post" action="http://example.com/node/add/story">
    Title: <input type="text" size="12" maxlength="12" name="edit[title]">
    <input type="submit">
  </form>
</body></html>


POST Requests
-------------
Since Prepopulate uses the $_REQUEST variable, you have access to prepopulate
form values from either GET request in the URL, or the form POST requests. In
the below example, we prepopulate a node form's title based on a POST Request:

<html><body>
  <form method="post" action="http://example.com/node/add/story">
    Title: <input type="text" size="12" maxlength="12" name="edit[title]">
    <input type="submit">
  </form>
</body></html>


How to find what variable to set
--------------------------------

This can be tricky, but there are a few things to keep in mind that
should help.

Prepopulate.module is quite simple. It looks through the form, looking
for a variable that matches the name given on the URL, and puts the
value in when it finds a match. Drupal keeps HTML form entities in an
edit[] array structure. All your variables will be contained within the
edit[] array.

A good starting point is to look at the HTML code of a rendered Drupal
form. Once you find the appropriate <input /> (or <textarea>...</textarea>
tag, use the value of the name attribute in your URL, contained in the
edit array. For example, if the <input /> tag looks like this:

  <input id="edit-title" class="form-text required" type="text" value=""
  size="60" name="title" maxlength="128"/>

then try this URL:

  http://www.example.com/node/add/content?edit[title]=Automatic filled in title

CCK fields are a bit more complicated:

  <input id="edit-field-office-0-node-name" class="form-text
  form-autocomplete" type="text" value="" size="60"
  name="field_office[0][node_name]" maxlength="128" autocomplete="OFF"/>

The key is to put this in the edit[] array nested, like this:

  http://www.example.com/node/add/content?edit[field_office][0][node_name]=AL-235

Another example:

  <textarea id="edit-field-content-0-value" class="form-textarea
  resizable processed" name="field_content[0][value]" rows="10"
  cols="60"/>

would be:

  http://www.example.com/node/add/content?edit[field_content][0][value]=A long text string

and, again, for non-clean URLs, it's:

  http://www.example.com?q=node/add/content&edit[field_content][0][value]=A long text string


Body fields
-----------

Body fields are different. Though their HTML entity looks like this:
  <textarea id="edit-body" class="form-textarea resizable processed"
  name="body" rows="20" cols="60"/>

You can't just take the name "body," throw it into a edit[body] and
expect it to work. Drupal wraps the body field into a "body_field"
array when it gets processed. So, for body fields, a URL like:

  http://www.example.com/node/add/content?edit[body_field][body]=This is the body

ought to do the trick.


Multiple fields
---------------

Prepopulate can handle pre-filling multiple fields from one URL. Just
separate the edit variables with an ampersand:

  http://www.example.com/node/add/content?edit[title]=The title&edit[body_field][body]=The body

You're already using the ampersand with non-clean URLs:

  http://www.example.com?q=node/add/content&edit[title]=The title&edit[body_field][body]=The body


Escaping special characters
---------------------------

Some characters can't be put into URLs. Spaces, for example, work
mostly, but occasionally they'll have to be replaced with the string %20.
This is known as "percent encoding." Wikipedia has a partial list of
percent codes at:
  http://en.wikipedia.org/wiki/Percent-encoding

If you're having trouble getting content into field names, or are
getting 'page not found' errors from Drupal, you should check to ensure
that illegal characters are properly encoded.


Bookmarklets
------------

Prepopulate.module was created for bookmarklets. Here is a bookmarklet for
posting web links to a site:

javascript:u=document.location.href;t=document.title;s=window.getSelection();void(window.open(%22http://example.com/node/add/content-web-link?edit[title]=%22+escape(t)+'&edit[body_field][body]='+escape(s)+'&edit[field_url][0][value]='+escape(u),'_blank','width=1024,height=500,status=yes,resizable=yes,scrollbars=yes'));

This turns into a URL like this:

http://example.com/node/add/content-web-link?edit[title]=drupal.org%20%7C%20Community%20plumbing&edit[body_field][body]=&edit[field_url][0][value]=http%3A//drupal.org/

Selecting some text on the page first would put that text into the
body of the node.

Happy prepopulating!
1	$Id: USAGE.txt,v 1.4 2009/10/08 02:29:14 brauerranch Exp $
2
3	See README.txt for a description of this module.
4	See this documentation online at http://drupal.org/node/228167.
5
6	USING PREPOPULATE MODULE
7	========================
8
9	Simple Usage
10	------------
11
12	Prepopulate the title field on a node creation form:
13	http://www.example.com/node/add/content?edit[title]=This is the title
14	With 'non-clean' urls:
15	http://www.example.com?q=node/add/content&edit[title]=This is the title
16
17
18	POST Requests
19	-------------
20	Since Prepopulate uses the $_REQUEST variable, you have access to prepopulate
21	form values from either GET request in the URL, or the form POST requests. In
22	the below example, we prepopulate a node form's title based on a POST Request:
23
24	<html><body>
25	<form method="post" action="http://example.com/node/add/story">
26	Title: <input type="text" size="12" maxlength="12" name="edit[title]">
27	<input type="submit">
28	</form>
29	</body></html>
30
31
32	POST Requests
33	-------------
34	Since Prepopulate uses the $_REQUEST variable, you have access to prepopulate
35	form values from either GET request in the URL, or the form POST requests. In
36	the below example, we prepopulate a node form's title based on a POST Request:
37
38	<html><body>
39	<form method="post" action="http://example.com/node/add/story">
40	Title: <input type="text" size="12" maxlength="12" name="edit[title]">
41	<input type="submit">
42	</form>
43	</body></html>
44
45
46	How to find what variable to set
47	--------------------------------
48
49	This can be tricky, but there are a few things to keep in mind that
50	should help.
51
52	Prepopulate.module is quite simple. It looks through the form, looking
53	for a variable that matches the name given on the URL, and puts the
54	value in when it finds a match. Drupal keeps HTML form entities in an
55	edit[] array structure. All your variables will be contained within the
56	edit[] array.
57
58	A good starting point is to look at the HTML code of a rendered Drupal
59	form. Once you find the appropriate <input /> (or <textarea>...</textarea>
60	tag, use the value of the name attribute in your URL, contained in the
61	edit array. For example, if the <input /> tag looks like this:
62
63	<input id="edit-title" class="form-text required" type="text" value=""
64	size="60" name="title" maxlength="128"/>
65
66	then try this URL:
67
68	http://www.example.com/node/add/content?edit[title]=Automatic filled in title
69
70	CCK fields are a bit more complicated:
71
72	<input id="edit-field-office-0-node-name" class="form-text
73	form-autocomplete" type="text" value="" size="60"
74	name="field_office[0][node_name]" maxlength="128" autocomplete="OFF"/>
75
76	The key is to put this in the edit[] array nested, like this:
77
78	http://www.example.com/node/add/content?edit[field_office][0][node_name]=AL-235
79
80	Another example:
81
82	<textarea id="edit-field-content-0-value" class="form-textarea
83	resizable processed" name="field_content[0][value]" rows="10"
84	cols="60"/>
85
86	would be:
87
88	http://www.example.com/node/add/content?edit[field_content][0][value]=A long text string
89
90	and, again, for non-clean URLs, it's:
91
92	http://www.example.com?q=node/add/content&edit[field_content][0][value]=A long text string
93
94
95	Body fields
96	-----------
97
98	Body fields are different. Though their HTML entity looks like this:
99	<textarea id="edit-body" class="form-textarea resizable processed"
100	name="body" rows="20" cols="60"/>
101
102	You can't just take the name "body," throw it into a edit[body] and
103	expect it to work. Drupal wraps the body field into a "body_field"
104	array when it gets processed. So, for body fields, a URL like:
105
106	http://www.example.com/node/add/content?edit[body_field][body]=This is the body
107
108	ought to do the trick.
109
110
111	Multiple fields
112	---------------
113
114	Prepopulate can handle pre-filling multiple fields from one URL. Just
115	separate the edit variables with an ampersand:
116
117	http://www.example.com/node/add/content?edit[title]=The title&edit[body_field][body]=The body
118
119	You're already using the ampersand with non-clean URLs:
120
121	http://www.example.com?q=node/add/content&edit[title]=The title&edit[body_field][body]=The body
122
123
124	Escaping special characters
125	---------------------------
126
127	Some characters can't be put into URLs. Spaces, for example, work
128	mostly, but occasionally they'll have to be replaced with the string %20.
129	This is known as "percent encoding." Wikipedia has a partial list of
130	percent codes at:
131	http://en.wikipedia.org/wiki/Percent-encoding
132
133	If you're having trouble getting content into field names, or are
134	getting 'page not found' errors from Drupal, you should check to ensure
135	that illegal characters are properly encoded.
136
137
138	Bookmarklets
139	------------
140
141	Prepopulate.module was created for bookmarklets. Here is a bookmarklet for
142	posting web links to a site:
143
144	javascript:u=document.location.href;t=document.title;s=window.getSelection();void(window.open(%22http://example.com/node/add/content-web-link?edit[title]=%22+escape(t)+'&edit[body_field][body]='+escape(s)+'&edit[field_url][0][value]='+escape(u),'_blank','width=1024,height=500,status=yes,resizable=yes,scrollbars=yes'));
145
146	This turns into a URL like this:
147
148	http://example.com/node/add/content-web-link?edit[title]=drupal.org%20%7C%20Community%20plumbing&edit[body_field][body]=&edit[field_url][0][value]=http%3A//drupal.org/
149
150	Selecting some text on the page first would put that text into the
151	body of the node.
152
153	Happy prepopulating!