|
Name: cd2browse - create browsable menus out of directory structures
Version: 1.05
Synopsis: index -p <path to index> [-n -m -t -s -i -x -r -q -v]
Description: cd2browse is a command line tool, to create html menues out of directory trees mostly used on CDs and DVDs it also indexes all files and provides a java script search engine for full text search.
Preperation: befor you start to process a directory, you should consider the following.
cd2browse creates several files and subdirectories inside the document root - means in the directory you start processing. All subdirectories in the tree will be scanned by cd2browse and the html results are written to the document root directory and special subdirectories. All files, necessary to use the html menues are written to the document root directory (given by the -p option). Files in the root directory itself are not indexed and processed. Just sub- folders are recognised from the root. Above root also ordinary files are read and indexed.
For each file in the file tree a line in the belonging html menu(s) will be written. There are three possibilities to create the title of a file: The highest priority has the .htaccess file in each directory. The .htaccess file is a standard on apache web server and cd2browse uses the same syntax. If a line in the .htaccess file refers to a file in the directory, this title has priority and will therefore be taken for the menu. Example:
AddDescription "The description of how to use cd2browse" cd2browse_use.txt
The above line in .htaccess will show a longer description than just cd2browse_use.txt The second priority has a title tag of whether a pdf or a html file. cd2browse scans each pdf or html file for a title tag and takes this as the title in the menu line. If none of both, a .htaccess entry or a title tag exists, cd2browse takes the file name.
If cd2browse finds a Image in the file tree, it calculates a thumb nail image, a preview page and image of this image. So that automatically a image gallery is built. If you dont want to process images, for example beause images are linked inside html files, you may add a line in the .htaccess file with "IndexIgnore <list of extensions>" to the directory you don't want to index images.
How to start processing on the command line:
perl index.pl -p <path to index> [-n -m -t -s -i -x -r -q -v]
where options -n , -m , -t ,-s -i -x -r -q and -v are optional
How to start the GUI for window based interface:
perl CD2Browse.pl
The GUI is mostly self explaining - if you need help, go to Help -> Help, or read the file CD2Browse.hlp
Example:
perl c:\perl\own\index.pl -p "c:\Own Files\CD project" ( use the double quotes for files or path with spaces )
The above line will index all sub directories in "c:\Own Files\CD project" and writes the result into c:\Own Files\CD project
After calculation, point your browser to index.html in the directory and enjoy.
Options: -n (re) calculate no images to save cpu time This is especially interesting to re-calculate the indexes and omitting re-calculation of images, because this may save a lot of time. -m maxwidh of the preview image (default=800) You can define the maximum with of the preview images with this option the size is in pixels. If the files are smaller, the image gets the previous size. -s size of the thumbnails (default=90x90) The size of the thumbnails in the menu. The aspect ratio of the image is kept, but the resulting maximum is according to the setting width or height, depending on which exceeds first. -t title The title of the menu pages. -i do not index images If -i exists, no images will be indexed at all - for example if all images belong to html files. -x do not extract title from pdf file If -x exists, the indexing process will not extract the title from the pdf file. Instead, the file name is used. This is helpful, when the pdf files do not contain senseful title tags -r do not create several output pages for sorting. When applied, only one result page per directory is created. This does not allow sorting on the other hand. A different page.tpl template is recommended, because if the sort template is used, clicking onto the sort links lead to a error message of the browser - missing page. If the option is not present, 8 pages per directory will be created, for offline sorting. -q quiet - do not output progress information on the console window. -v Do not create folder navigation in the page section of the main view. If you use this option, no links for sub folders will be created in the main views (page_xxx.html) So subfolders are not visible in the page section. This forces the User to use the tree section for folder navigation.
.htaccess functions: Since the command line options influence the behaviour of cd2browse in general, there is a need to define the behaviour on a per directory base. Similiar to the apache directives, it is possible to influence the indexing process by setting directives inside .htaccess files.
if a .htaccess file exists in a scanned directory, it will be opened and parsed. The following directives are recognized in .htaccess files:
IndexIgnore IndexOptions SuppressDescription AddDescription
IndexIgnore takes Arguments like in apache.cnf: Like in Apache, the settings are valid also for all sub directories.
IndexIgnore *.gif *.css *.jpg *.png thumbs.db
The above line for examle does not index gif,jpeg and png images and also no css files and thumbs.db files. One or more lines with this directive may be used in the .htaccess file.
IndexOptions SuppressDescription Like in Apache, the settings are valid also for all sub directories.
The above line prevents the indexing process to extract the pdf title from pdf files - this is a per directory setting similiar to the -x command line option, which works globally. One line with this directive may be used in the .htaccess file.
AddDescription "Description of the file" filename Other than in Apache, the File description is not used in sub directories. This is a feature, since Apache annoys with repeating descriptions in sub directories, when the same file name appears.
The above line adds a description for a particular file. - see also the hints further up in this document.
note: if you want to have a mix of images in a directory you want to index and images you dont want to be indexed because they belong to a html file, you may create a directory with a leading dot like for example .resource and put the images for html pages inside this directory and link it inside the html accordingly. Directories with a leading dot will not be indexed at all.
Customizing cd2browse:
To customize the look and feel of cd2browse results, you may read the following:
Files are copied from the resourcesource directory of cd2browse - usually /var/opt/cd2browse/repository (unix/Linux) or c:\strawberry_operate\opt\cd2browse\repository (Windows) - to the target directory "<dir to index>/.repository"
CD2Browse checks before copying the files. If the files to copy already exist, cd2browse does not copy, but takes the settings from the target. So you may change just the files in your particular target directory instead of changing the source. Each further run of index.pl will take the settings from the target. This means you can customize the output on a project base this way. On the other hand this means, that if once a target directory has been changed, it will be never overwritten again, until you delete all files in the .repository directory on the target manually.
Files:
\var\opt\cd2browse\repository\head.html - the upper frame (search form and head line)content \var\opt\cd2browse\repository\index.html - the frame set itself \var\opt\cd2browse\repository\result.html - do not edit - will be overwritten - change \var\cd2browse\repository\menu\templatespage.tpl and list.tpl instead \var\opt\cd2browse\repository\welcome.html - the first page shown in the main frame \var\opt\cd2browse\repository\start.exe - used together with autorun.inf to autostart the browser when on cd and cd is inserted \var\opt\cd2browse\repository\autorun.inf - used together with start.exe to autostart the browser when on cd and cd is inserted \var\opt\cd2browse\repository\cd.ico - shown in explorer as the drive icon \var\opt\cd2browse\repository\resources - file type icons for the use in the menu \var\opt\cd2browse\repository\empty_dir.html -page shown if the user clicks onto a empty directory if the folder navigation is not in use \var\opt\cd2browse\repository\image_end.html -page shown if the last image of the gallery is reached \var\opt\cd2browse\resources\templates\image.tpl - template for the image gallery html \var\opt\cd2browse\repository\templates\page.tpl - template for the menu pages \var\opt\cd2browse\repository\menu\templates\list.tpl - template for each menu page list line \var\opt\cd2browse\repository\menu\templates\tree.tpl - template for the file tree menu \var\var\opt\cd2browse\repository\menu\templates\treeitem1-1.tpl - template for the root folders of the tree menu - this is the opening tag. Together with treeitem1-2.tpl it contains the code for this folder level menu structure ...\treeitem1-2.tpl - Closing tag - works together with treeitem1-1.tpl ...\treeitem2-1.tpl - This is the end fragment for the folder hirarchy i.e. used for a folder wich has no sub-folders. ...\treeitem2-2.tpl - Contains the closing tag - works together with treeitem2-1.tpl ...\treeitem2-1a.tpl - Used for folders in between the root and the end folder ...\treeitem2-2a.tpl - Contains the closing tag - works together with treeitem2-1a.tpl
After running cd2browse once sucessfully, a similar structure exists in your target file tree, because the above files and folders will be copied to your document root. These files will be copied only if the don't exist before. This means customizing them allows you a project based look and feel
<target directory>\index.html <target directory>\.repository\head.html <target directory>\.repository\result.html <target directory>\.repository\welcome.html <target directory>start.exe <target directory>autorun.inf <target directory>cd.ico <target directory>\.repository\resources <all copied from \var\opt\cd2browse\repository\resources> <target directory>\.repository\menu\ <all copied from \var\opt\cd2browse\repository\menu> <target directory>\.repository\teplates\ <all copied from \var\opt\cd2browse\repository\templates>
How to use different Tree menus: To use a different tree menu, you can rename one of the additional sample repository directories "\var\opt\cd2browse\repository_xxxxx" into "repository" Please read also the README files in the different repository_xxx directories.
A template set for the tree menu consists of four levels as shown below and is the base for the resulting tree.html. During run time of index.pl, the templates will be filled with data and linked together to form the resulting tree.html
------------------- | | | -------------------- | | treeitem1-1.tpl | | ---------------------------- | | treeitem2-1a.tpl | | --------------------- | ..... | ---------------------- | | treeitem2-1a.tpl | | ------------------------------- | | treeitem2-1.tpl | | tree.tpl ----------------------- | | treeitem2-1.tpl | | ------------------------------- | | treeitem2-2a.tpl | | ---------------------- | ..... | --------------------- | | treeitem2-2a.tpl | | ---------------------------- | | treeitem1-2.tpl | | -------------------- | | treeitem1-1.tpl | | -------------------- | ..... | -------------------- | | treeitem1-2.tpl | | -------------------- | | ------------------- Remember: After running once index.pl on a particular directory tree, you need to delete the .resources directory in the target file tree if you want to try a different tree menu for the same directory. Otherwise you will see no change !
|  |
* |
|