-- First the javascript
"pcsexplorer.js.php" must be
included in the HTML header :
<html>
<head>
<title>PcsExplorer Sample File</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script language="javascript" src="/pcsexplorer/pcsexplorer.js.php"></script>
</head>
<body>
[...]
</body>
</html>
|
-- Then PcsExplorer
need to be associated with a client action,
like clicking on a "browse ..."
button. The javascript function "PcjsExplorer()"
is used to open the PcsExplorer window,
and to give it the parameters of the "file/folder
selection" action.
<html>
<head>
<title>PcsExplorer Sample File</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script language="javascript" src="/pcsexplorer/pcsexplorer.js.php"></script>
</head>
<body>
<FORM name="formulaire" method="POST">
File : <INPUT TYPE="TEXT" SIZE="80" ID="input_text">
<INPUT TYPE="button" NAME="button" VALUE="Browse ..."
onClick='PcjsExplorer("target_type=value",
"target=input_text",
"select_type=file",
"select_extensions=php,txt",
"result_ref_dir_from_root=from_here/",
"start_dir_from_root=test/")'
>
</FORM>
</body>
</html>
|
2 - Configuring
PcsExplorer
PcsExplorer window
is configured by the arguments given to
the "PcsjExplorer()" function.
These arguments are :
target_type=
value | url | js_line | js_function
The "target_type"
parameter will indicate what action
PcsExplorer will do when the selection
of a file or a folder is made by the
user.
- value
:
PcsExplorer will set the selected
file or folder name in the value field
of an INPUT TEXT object. The target
INPUT TEXT object ID must be set in
the parameter "target".
- url
:
PcsExplorer will reload the parent
window (calling window) with the URL
set in the parameter "target".
Before calling the URL, PcsExplorer
will replace the keyword $$RESULT$$
by the selected selected file or folder
name.
- js_line
:
PcsExplorer will run, in the popup
window, the javascript code line set
in the parameter "target".
Before running the javascript code
line, PcsExplorer will replace the
keyword $$RESULT$$ by the selected
selected file or folder name.
- js_function
:
PcsExplorer will run, in the parent
window, the javascript function set
in the parameter "target".
The function must be defined in the
parent window by the user. PcsExplorer
will give the selected selected file
or folder name as the function parameter.
The default
value of this parameter is "value".
target=<target_value>
The "target"
parameter value depend of the "target_type"
value.
- When
"target_type" is "value"
:
"target" parameter must
contain the javascript ID of the input
text object.
(for "<INPUT ID="file_selection"
TYPE="TEXT" size=80>"
the parameter will be "target=file_selection")
- When
"target_type" is "url"
:
"target" parameter will
identify an URL that will be called
after the selection. The value should
contain the keyword $$RESULT$$ that
will be replaced by the selected result
before the call.
(Example : "target=do_it.php?result=$$RESULT$$")
- When
"target_type" is "js_line"
:
"target" parameter will
be a javascript code line. The value
should contain the keyword $$RESULT$$
that will be replaced by the selected
result before run the line.
(Example : "target=alert('result
is $$RESULT$$')").
- When
"target_type" is "js_function"
:
"target" parameter will
be a javascript function name. The
javascript function must be defined
in the parent window. The function
will be called with the selected result
as argument.
(Example : if "target=do_it",
then if the selection is "test/index.php",
PcsExplorer will call "do_it('test/index.php');"
in the parent window).
target_encoding=
none | url
It can be usefull
to have the result send back as an url-encoded
string (specially for target_type=url).
This parameter gives the ability to
do that. By deafult the value is 'none'.
select_type=
file | dir
This indicates
if the user will select a file or a
folder.
Optional attribute. By default "file".
select_extensions=<ext1>,<ext2>,...,<extn>
Only the files
that have the extensions given in the
coma separated list are displayed.
Optional attribute. By default all files
are displayed.
root_dir=<folder_path>
This is the path
to the root folder of the web site.
Typically this will correspond to $_SERVER['DOCUMENT_ROOT'].
It is used as default reference for
other folder path attributes.
Optional attribute. By default set to
$_SERVER['DOCUMENT_ROOT'].
result_ref_dir=<folder_path>
result_ref_dir_from_root=<folder_path>
result_ref_dir_from_fs=<folder_path>
This is the reference
folder path from where the result is
returned. Typically it will be the current
path of the calling PHP script. Setting
the result reference folder will allow
PcsExplorer to manage all the path reduction
and calculate a relative path, in order
to return a usable path for the calling
script.
When using "result_ref_dir"
or "result_ref_dir_from_root",
the path folder indicated is relative
to the "root_dir" attribute.
When using "result_ref_dir_from_fs",
the path folder indicated is relative
to the filesystem.
Optional attribute. By default the returned
value will be relative to the "root_dir"
attribute.
Example :
If you root_dir is '/usr/www',
PcsExplorer will be able to navigate
in this folder tree. If you want that
the resulting filename or folder path
send back by PcsExplorer be relative
to /usr/www/my_files/, then use "result_ref_dir_from_root=my_files/"
or "result_ref_dir_from_fs=/usr/www/my_files/".
If the selected file is /usr/www/upload/sample.txt,
the result returned by PcsExplorer
will be '../upload/sample.txt'.
start_dir_from_root=<folder_path>
start_dir_from_result=<folder_path>
start_dir_from_fs=<folder_path>
The directory
where the PcsExplorer will be opened.
This gives the ability to open a window
on a specific folder and not necessarilly
starting at the root or the result reference
dir.
The start directory can be relative
to the root, the result path or the
filesystem.
Optional attribute. By default the start
dir will be the "root_dir".
base_dir=<folder_path>
The base directory
from where PcsExplorer can work. The
concept is the same as the "base_dir"
in php.ini. The user can not navigate
outside this base_dir restriction. Each
returned result is checked to this restriction.
Optional attribute. By default set to
$_SERVER['DOCUMENT_ROOT'].
Limitations
& Prerequisits
PcsExplorer
is using the session feature of PHP. Make
sure your PHP installation all the sessions.
Security
Concerns
Because PcsExplorer
may give access to the full filesystem
of a web server, it must be used with
caution.
Using PHP and web server embedded security
features (like .htaccess files, open base
dir restrictions in php.ini file, ...)
is a good way of proceeding.
License
& Copyrights
PcsExplorer is
released by Vincent Blavet (vincent@phpconcept.net)
under GNU GPL License. So you can use
it at no cost.
HOWEVER, if you
release a script, an application, a library
or any kind of code including PcsExplorer,
YOU MUST :
- Release your work under GNU/GPL license
(free software),
- You must indicate in the documentation
(or a readme file), that your work include
PcsExplorer script, and make a reference
to the author and the web site http://www.phpconcept.net
I will also appreciate
that you send me an email (vincent@phpconcept.net),
just to be aware that someone is using
PcsExplorer somewhere in the world.
For more information
on GNU/GPL licensing : http://www.gnu.org
Warnings
This application
and the associated files are non commercial,
non professional work.
It should not have unexpected results.
However if any damage is caused by this
software the author can not be responsible.
This program is
distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without
even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.
The use of this software is at the risk
of the user.