/
filenames.html
224 lines (205 loc) · 7.4 KB
/
filenames.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
---
layout: default
navPage: docs
heading: File Upload Field
breadcrumbs:
- Modules,/modules/
- File Upload Field,/modules/field_type_file/
- File Settings
prev: Per-field file settings,/modules/field_type_file/file_settings/
next: Adding to your forms,/modules/field_type_file/adding_to_forms/
categories: modules
tags: field_types,files
---
{% include open_section.html nav='nav_file_upload.html' selected='filenames' %}
<h3>Uploaded Filenames</h3>
<p>
{% include screenshot.html item="edit-field__filename_format.png" %}
With version 2.2.0 of this module you can now customize the filenames that are created when a user uploads a
file. To customize the filename, you'll need to edit the <b>Filename format</b> setting in the Edit field
dialog, found in the Edit Form » Fields page.
</p>
<h4>Placeholders</h4>
<p>
These are special placeholders that can be used in your <b>Filename format</b> field to control how the filename
is generated. See below for some examples on how they can be used.
</p>
<div class="row">
<div class="col-lg-4">
<code>{$clean_filename}</code>
</div>
<div class="col-lg-8">
This is the default value for uploaded files: they get created with a "clean" version of their original
filename. Form Tools whitelists specific characters that may be included in uploaded filenames, see the
<code>$g_filename_char_whitelist</code> setting in your
<a href="{{site.baseurl}}/userdoc/getting_started/config_file/">config.php</a> file for more info. Those
whitelisted characters are what's used to determine the clean filename.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$clean_filename_no_extension}</code>
</div>
<div class="col-lg-8">
The clean file string without the filename extension. Handy if you want to add a suffix to the filename.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$raw_filename}</code>
</div>
<div class="col-lg-8">
This placeholder is the original filename as uploaded by the user. Generally you should avoid this placeholder:
users could upload filenames with any characters whatsoever.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$raw_filename_no_extension}</code>
</div>
<div class="col-lg-8">
The raw file string without the filename extension.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$extension}</code>
</div>
<div class="col-lg-8">
The file extension (e.g. <b>jpg</b> in <b>filename.jpg</b>).
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$form_id}</code>
</div>
<div class="col-lg-8">
The current form ID.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$submission_id}</code>
</div>
<div class="col-lg-8">
The current submission ID.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$index}</code>
</div>
<div class="col-lg-8">
The index of the file in the set of files being uploaded for a field. For fields configured as single
file uploads (the default option), this value will always be <b>0</b>.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$field_name}</code>
</div>
<div class="col-lg-8">
The name of the form field for the file upload field.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$date}</code>
</div>
<div class="col-lg-8">
A simple placeholder containing the current date (in whatever timezone your server thinks it currently is). This
outputs the date in YYYYMMDD format, e.g. <b>20190126</b>.
</div>
</div>
<div class="row">
<div class="col-lg-4">
<code>{$unixtime}</code>
</div>
<div class="col-lg-8">
This placeholder outputs the current unixtime, but can also be used to output a date or time in any format you
want. To customize the format, you need to use the <code>date_format</code> modifier like so:
<code>{$unixtime|date_format:"M-n-Y"}</code>. The content of the double quotes are whatever formatting string
you'd like. See the <a href="http://php.net/manual/en/function.date.php">PHP date method</a> for the list of
available placeholders.
</div>
</div>
<br />
<p class="alert alert-info">
Note that in case of a filename conflict, <i>the module will rename files to ensure each filename is unique</i>.
So if you upload a file that happens to have the same name as an existing file - even after whatever custom
filename format you entered, it will still automatically rename it.
</p>
<h3>Examples</h3>
<p>
Here are a few examples to get an idea of how you can use the placeholders in the field. As you can see from
below, any characters that aren't in a placeholder get included in the filename. <b>The one exception is the
colon character</b>: that's not a valid character in filenames on Unix or Windows systems so it will always be
stripped out, even if it's part of your date formatting string.
</p>
<div>
<div>
<code>{$submission_id}-{$field_name}-{$index}.{$extension}</code>
</div>
Three png images uploaded through a multiple-field upload field, where the submission ID is <b>35</b> and the
field name is <b>filefield</b>.
<ul>
<li><b>35-filefield-0.png</b></li>
<li><b>35-filefield-1.png</b></li>
<li><b>35-filefield-2.png</b></li>
</ul>
</div>
<div>
<div>
<code>{$submission_id}-{$field_name}-{$index+1}.{$extension}</code>
</div>
Same as the last one, except it starts the numbering from <b>1</b>.
<ul>
<li><b>35-filefield-1.png</b></li>
<li><b>35-filefield-2.png</b></li>
<li><b>35-filefield-3.png</b></li>
</ul>
</div>
<div>
<div>
<code>f{$form_id}-s{$submission_id}-{$clean_filename}</code>
</div>
Tacks on the form ID and submission ID as a prefix to the clean filename. This helps to visually identify
which files in your upload folder belong to which form and submission.
<ul>
<li><b>f5-s39-infodoc.xls</b></li>
<li><b>f5-s29-happypic.jpg</b></li>
</ul>
</div>
<div>
<div>
<code>{$clean_filename_no_extension}-{$date}.{$extension}</code>
</div>
Displays the filename with the YYYYMMDD appended as a suffix to the filename.
<ul>
<li><b>greenbug-20190127.png</b></li>
<li><b>fritillarybutterfly-20190127.gif</b></li>
</ul>
</div>
<div>
<div>
<code>{$clean_filename_no_extension}-{$date}.{$extension}</code>
</div>
Displays the filename with the YYYYMMDD appended as a suffix to the filename.
<ul>
<li><b>greenbug-20190127.png</b></li>
<li><b>fritillarybutterfly-20190127.gif</b></li>
</ul>
</div>
<div>
<div>
<code>{$clean_filename_no_extension}-{$unixtime|date_format:"MjS-h-ia"}.{$extension}</code>
</div>
Displays the filename with the YYYYMMDD appended as a suffix to the filename. As mentioned above, you cannot
include colons (<b>:</b>) in the date formatting string because they are invalid filename characters on most
systems. If you do, they will be stripped out.
<ul>
<li><b>aniseswallowtail-Jan27th-05-48pm.png</b></li>
<li><b>beetle-Jan27th-05-48pm.png</b></li>
</ul>
</div>
{% include close_section.html %}