The NJX:NJXFILEUPLOAD2 control is used to upload files from the client to the
Natural server or to a designated directory on the web application server running on Windows
or Linux. Per default, the files are uploaded to the Natural server as BLOBs. For uploading
to a designated directory on the web application server (Windows or Linux), set the design
time property filestoragemode="Filesystem". The rendering is identical to the
FILEUPLOAD2 control.
When uploading to Natural you must also add an NJX:OBJECTS control to your page layout because the uploaded file
will be added to the NJX:OBJECTS data structure. Once a file is uploaded, the
Natural application can refer to the file via the CONTENTID of the uploaded
object. When uploading files to the filesystem, the generated adapter interface provides
additional parameters that control the destination of the uploaded file:
destpath (required) - Specifies the target directory on the web
application server. The path must be absolute and must already exist.
subpath (optional) - Specifies a subdirectory below destpath.
If the directory does not exist, it is created automatically. For security reasons, only
valid subdirectories are accepted; directory traversal patterns such as ../
are rejected.
The following topics are covered below:
Note
See also Documents in
Some Common Rules for all Controls.
The XML layout definition is:
<itr>
<njx:njxfileupload2 width="400" valueprop="myupload"
withsubmitbutton="true" submitbuttonname="Upload to Natural">
</njx:njxfileupload2>
</itr>
1 MYUPLOAD 2 CEXT (A) DYNAMIC 2 CNAME (A) DYNAMIC 2 CONTENTID (A) DYNAMIC 2 CPATH (A) DYNAMIC
When uploading a file, the client-side file name, extension and path are provided in the
CNAME, CEXT and CPATH fields, respectively. The
Natural application can optionally specify a CONTENTID for the
NJX:OBJECTS data structure. If CONTENTID is not specified, a
concatenation of file name and extension is automatically set as the
CONTENTID value.
1 MYUPLOAD 2 DESTNAME (A) DYNAMIC 2 DESTPATH (A) DYNAMIC 2 RESULTCODE (I4) 2 SUBPATH (A) DYNAMIC
When uploading a file, the file name is provided in DESTNAME. The
RESULTCODE field indicates the outcome of the operation.
1 - The destination path is not an absolute path.
2 - The destination path does not exist.
3 - The specified subpath is invalid.
4 - A file with the same name already exists in the destination location.
5 - An I/O error occurred while writing the file.
When you click the button in the above example,
the value-of-valueprop.onUploadFinished
event is triggered in the Natural application. When this event is triggered, either the
CNAME, CEXT, CPATH and CONTENTID
fields are filled, and the file content is provided in the data structure of the
NJX:OBJECTS control, or the DESTNAME and
RESULTCODE fields are filled, depending on whether you chose upload to
Natural or to the filesystem.
When you click the button, the corresponding
valueprop.onUploadFinished event is triggered in the Natural application.
The information returned with this event depends on the selected storage mode:
Upload to Natural - The fields CNAME,
CEXT, CPATH, and CONTENTID are populated. In
addition, the file content is made available through the data structure of the
NJX:OBJECTS control, which can be accessed using the returned
CONTENTID.
Upload to Filesystem - The fields DESTNAME and
RESULTCODE are populated. DESTNAME contains the name of
the stored file, while RESULTCODE indicates whether the upload completed
successfully or provides an error code describing the reason for a failure.
| Basic | |||
| width |
Width of the control. There are three possibilities to define the width: (A) You do not define a width at all. In this case the width of the control will either be a default width or - in case of container controls - it will follow the width that is occupied by its content. (B) Pixel sizing: just input a number value (e.g. "100"). (C) Percentage sizing: input a percentage value (e.g. "50%"). Pay attention: percentage sizing will only bring up correct results if the parent element of the control properly defines a width this control can reference. If you specify this control to have a width of 50% then the parent element (e.g. an ITR-row) may itself define a width of "100%". If the parent element does not specify a width then the rendering result may not represent what you expect. |
Optional |
100 120 140 160 180 200 50% 100% |
| withsubmitbutton |
If set to "TRUE" adds an additional button to the control to start the file upload. |
Optional |
true false |
| submitbuttonname |
The name of the submit button in case WITSUBMITBUTTON is set to "true". |
Optional | |
| submitbuttontextid |
"Textid" for the name of the submitbutton if WITHSUBMITBUTTON is set to "true". The "textid" is translated into a corresponding string at runtime. Do not specify WITHSUBMITBUTTONNAME if specifying WITHSUBMITBUTTONID. |
Optional | |
| maxfilesize |
Maximum size of the file. The unit is specified in the filesizeunit property. |
Optional |
1 2 3 int-value |
| filesizeunit |
The unit for the maxfilesize property. Default is bytes. |
Optional |
bytes KB MB GB |
| filestoragemode |
Per default the file is uploaded to your Natural program as a BLOB. Chose the value Filessystem if you prefer to upload the file to the filesystem on the web application server instead. |
Optional |
BLOB Filesystem |
| overwrite |
Applies only if filestoragemode Filesystem is set. Per default already existing files are overwritten during the upload. Set this property to false to prevent overwriting existing files. If a file with the same name already exists, the upload will fail and return an error. |
Optional |
true false |
| comment |
Comment without any effect on rendering and behaviour. The comment is shown in the layout editor's tree view. |
Optional | |
| Binding | |||
| invisiblemode |
If the visibility of the control is determined dynamically by an adapter property then there are two rendering modes if the visibility is "false": (1) "invisible": the control is not visible. (2)"cleared": the control is not visible but it still occupies space. |
Optional |
invisible disabled cleared |
| Appearance | |||
| invisiblemode | (already explained above) | ||
| rowspan |
Row spanning of control. If you use TR table rows then you may sometimes want to control the number of rows your control occupies. By default it is "1" - but you may want to define the control to span over more than one columns. The property only makes sense in table rows that are synchronized within one container (i.e. TR, STR table rows). It does not make sense in ITR rows, because these rows are explicitly not synched. |
Optional |
1 2 3 4 5 50 int-value |
| colspan |
Column spanning of control. If you use TR table rows then you may sometimes want to control the number of columns your control occupies. By default it is "1" - but you may want to define the control to span over more than one columns. The property only makes sense in table rows that are synchronized within one container (i.e. TR, STR table rows). It does not make sense in ITR rows, because these rows are explicitly not synched. |
Optional |
1 2 3 4 5 50 int-value |
| darkbackground |
Normally the background is in light colour but the CIS style sheets also have a dark(er) grey colour to be used. If DARKBACKGROUND is set to true then the darker background colour is chosen. This property typically is used to integrate light coloured controls into darker container areas. |
Optional |
true false |
| Online Help | |||
| title |
Text that is shown as tooltip for the control. Either specify the text "hard" by using this TITLE property - or use the TITLETEXTID in order to define a language dependent literal. |
Optional | |