PcsExplorer 1.0 - User Manual

 
 

Introduction

PcsExplorer is a PHP and Javascript script that manage a remote "file selection" popup window.

PcsExplorer can be used by PHP scripts hosted in web servers, in order to enable the selection of a file or a folder located in this web server, from a client web browser.

The selection made by the client can then be dynamically set in the value field of an input text in a form, or be used to start aspecific action (like calling a specific URL with the selected file as an argument).

PcsExplorer can control which folders can be accessed or not, which files extensions are displayed and has other powerfull features.

Using PcsExplorer

1 - Quick start

All PcsExplorer components are in a folder named "pcsexplorer". This folder can be anywhere in the web server filesystem, but it must be accessible by the client browser. In the following documentation, it is supposed that the "pcsexplorer" folder is in the DOCUMENT_ROOT path of the web site.

PcsExplorer is called directly from a PHP script, by calling a javascript function. The result of the client selection can be used in the following manner :

    • PcsExplorer can send back the result in the value field of an INPUT TEXT form object of the calling window,
    • PcsExplorer can reload the parent window with a user-configured URL containing the result,
    • PcsExplorer can call a javascript line of code to initiate an action, with the result as parameter,
    • PcsExplorer can call a javascript function defined in the parent window with the result as parameter.

Bellow is described how PcsExplorer need to be called in a PHP script :

-- 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.

 

 

 

Copyright 2005 - www.PhpConcept.com