Manual
Installation
Please see the "Installation" posting for more information on the installation process. The installation of XODA should be pretty straight forward: unpacking the file xoda-[VERSION].tar.bz2 file creates a directory called xoda-[VERSION].
You may want to move the files to another directory, e.g. the one where you would like your site to access your brand new Document Management System (DMS), say 'example.net/xoda' or 'documents.example.net'.Default username: admin
Assuming you did it the suggested way, let's move on.
Clicking the "Transfer" Button opens a simple form for transferring files from the Web. This is useful if you would like to transfer a file found somewhere on the Web without downloading it to your machine and then having to upload it to XODA. The form contains a field for the URL and a (optional) field for the name you would like the filed to be stored under. If you don't set this name, the name of the file would be used. Please have in mind that some files (even pictures) might be generated by a script and, at least in these cases, you should use a custom name, since "index.php?generate=great_pic" is not really a good filename. The file will be transferred to the current directory.
Filters are enabled by default but are optional. This is thought to be a very powerful feature. You can set as many filters and subfilters as you like. If non existent they will be created. If you delete a previously set filter - and there is no other file/directory having this filter - it will be deleted automatically.
Once the "Allow additional filters" option is enabled in the Preferences, a button "Filters" is displayed on the navigation bar after the first (set of) filter(s) is set on a file/directory. This button opens a list tree of all filters which is by default collapsed. For better understanding, I have included here a screenshot with completely uncollapsed tree of the filters which I currently used to show the example.As of version 0.1.3, this list is sorted alphabetically.
You may have noticed the check boxes next to the filenames. You can select one or multiple files for:
For "copy" and "move" a single input field is shown after clicking one of them. The slash preceding the input field indicates the Root Directory. If you leave the input field blank, the file(s) will be copied/moved to the Root Directory (set as ROOT_DIR in the file "config.php", default is "files/").
The settings menu appears in a box after clicking "settings" in the right upper corner, above the navigation bar. There are several different settings which can be set over the browser. They are grouped in different categories reflected by the tabs of the window.
The link "Add new user" toggles a simple form for creating for new username and a password (with the obligatory confirmation) and a checkbox for optional granting root privileges to the new user.
Default username: admin
Default password: xoda
Upgrade (since 0.4.0)
Open your 'config.php' and change the lines "'root' => '1';" to "'privileges' => '1'" for all of the users with administrator (root) privileges. Then go to the "Settings" panel and do the management of the users from there.
Upgrade (since 0.1.5)
Open 'config.sample.php' and set your username (instead of 'admin'). You could also copy the md5 string (the long one with the numbers and letters set for the password, e.g. 'password' => 'a68e142815fdda868de0551fc6675e65') to preserve your password. Otherwise you would have to set it again over the browser. Please consider copying things like '$_top_content' or '$_colors' if you have made significant changes there. You can also change the values of any of the constants according to your needs and your original 'config.php' file.
Then rename 'config.sample.php' to 'config.php'.
You can also just rename 'config.sample.php' to 'config.php' without changing anything (but the username!) in 'config.sample.php'. In this case you should redo the complete configuration on the browser.
First Steps
Since version 0.1.5 the configuration file is 'config.sample.php' and is included just as a sample file which you should rename to 'config.php' before starting using XODA.
When you point your browser to the URL with the new installation, the script will be executed for the first time, creating the root directory (defined as ROOT_DIR in the file 'config.php', default is 'files/') and the directory storing the meta information (defined as META_DIR in the file 'config.php', default is '.xoda/') if they don't exist already as well as the '.htaccess' file for setting redirecting rules.
Security adviceYou should set a directory outside your web directory to be ROOT_DIR!A lot of people think like: "Oh, I put it in a location where you have to know the URL, so it must be secure."It is not! Again, it is not secure to put the directory with your (not anybody else's but yours!) files in a place directly accessible by the web server and therefore by any browser!Should you still (against any reasonable advice!) decide to keep ROOT_DIR in your web directory, you should at least let the Apache web server protect it by .htaccess/.htpasswd files. Please take a look at the excellent DreamHost Wiki how to do this the best way!
Having said this, my suggestion would be to set in 'config.php' something like:
define('ROOT_DIR', '/home/[USERNAME]/xoda/files/');
define('META_DIR', '/home/[USERNAME]/xoda/.xoda/');
Please note the trailing slash (the '/' at the end of the path) for both ROOT_DIR and META_DIR. This is a requirement for XODA to work properly!
Please note also that none of these directories should be within the other one!
If there are no files in the root directory at this point, XODA would look like:
At this moment you should add another user (with root privileges) and then delete "admin" or at least change the password of "admin"! Do not underestimate the importance of this step!
Navigation bar
The "Reload" button should be self explaining and is present on every directory. You can reload always with the browser, of course. I found it handy to have it there though.
"Current directory" shows which directory you are currently in. Like in the Unix(-like) filesystems, it starts with '/' (called "root directory").
On the right side of the navigation bar are 3 more buttons: "Upload", "Transfer" and "Create". Since "Upload" and "Create" are obvious in what they do (esp. when you click on them), I would like to focus here on the function of the "Transfer" button, since I have not seen its functionality in any other file manager or DMS.
Clicking the "Transfer" Button opens a simple form for transferring files from the Web. This is useful if you would like to transfer a file found somewhere on the Web without downloading it to your machine and then having to upload it to XODA. The form contains a field for the URL and a (optional) field for the name you would like the filed to be stored under. If you don't set this name, the name of the file would be used. Please have in mind that some files (even pictures) might be generated by a script and, at least in these cases, you should use a custom name, since "index.php?generate=great_pic" is not really a good filename. The file will be transferred to the current directory.File list
For the purpose of having a file list, I have created a directory "Doodles" and have transferred some of the Google Doodles there.
Once a subdirectory is entered ("/Doodles" in this example), a "⇑ (up)" button appears next to the "Reload" button allowing navigation to the parent directory.
The files/directories are presented in a table. "Type" and "Filename" can not be removed, since I couldn't find any sense in implementing that option. The other information can be selected among:
- Description of the file/directory,
- Creation time,
- Last modification,
- Last access,
- Size of the file/directory.
The description, modification time and the size are enabled in the above example (and also by default).
XODA uses "sorttable" which is a great JavaScript library developed by Stuart Langridge. It allows sorting table rows by criteria listed in the columns.
Clicking on any of the column titles ("Type", "Filename" etc.) will sort the table according to this criteria.
File/directory information
The icons in the first column are default icons for a file or directory. They are links to more information about a file or directory though!
Let's see an example:
In this case I clicked on the file icon next to the filename "rosa_parks.jpg". Preview is shown for pictures and text files.
"Location" is the directory where the file is stored.
For Determining the "Type", XODA uses the UNIX command line tool `file` which is way more accurate than the file extension.
The "Size" is shown in a human readable format.
"Created" shows the time of creation ("ctime") as returned by the file system.
Note the "⊕", meaning that this is editable! I set editing the modification time as an additional tool for sorting files.
Filters are enabled by default but are optional. This is thought to be a very powerful feature. You can set as many filters and subfilters as you like. If non existent they will be created. If you delete a previously set filter - and there is no other file/directory having this filter - it will be deleted automatically.Setting subfilters is like setting subdirectories: limited by slash ("/"), e.g. "Filter/Subfilter1/Subfilter2".
In the case of the exemplary file "rosa_parks.jpg", you might want to set the following filters:
Index/RFile Type/JPGArt/Doodles/Personalities/Civil Rights ActivistsHistory/USA/Racism...etc.
Please have in mind that every filter should be set on a new line!
Once the "Allow additional filters" option is enabled in the Preferences, a button "Filters" is displayed on the navigation bar after the first (set of) filter(s) is set on a file/directory. This button opens a list tree of all filters which is by default collapsed. For better understanding, I have included here a screenshot with completely uncollapsed tree of the filters which I currently used to show the example.Clicking on the name of a file will either prompt a download or load the file in the browser if possible. There is one exception: pictures. I implemented previewing pictures in a iBox window like in the following example.
Options for selected multiple files/directories
You may have noticed the check boxes next to the filenames. You can select one or multiple files for:- Copy,
- Move,
- Delete,
- Setting description and filters.
These options will appear, once a selection is made.
For "copy" and "move" a single input field is shown after clicking one of them. The slash preceding the input field indicates the Root Directory. If you leave the input field blank, the file(s) will be copied/moved to the Root Directory (set as ROOT_DIR in the file "config.php", default is "files/").Please note that, for security reasons, parent directories, given by "../", are disabled!
Please note that selecting file/directory is a necessary step in copying, moving or deleting them even if it is only one, you would like to process!
Even though a description and the filters can be set over the info box of a file/directory, sometimes it might be desired to do this on a bunch of them.
Please note that all previously set descriptions of any files/directories will be replaced by the new one, being set here!
You can set here "filters" for multiple files/directories also. Filters and subfilters are set one per line.
"Set filters" will replace all previously defined filters of all of the selected files/directories. Use this with caution since you would lose the filters you have set on these files in the past, if you use this option!
"Add filters" will just add the new filters to any preexisting ones.
Settings
The settings menu appears in a box after clicking "settings" in the right upper corner, above the navigation bar. There are several different settings which can be set over the browser. They are grouped in different categories reflected by the tabs of the window.
- "Title" is the HTML-title of the index, default is "XODA".
- "Date format" is used to display the date and time in the desired format. Please refer to http://php.net/date for the format parameters in setting the date format.
- "Editable files" should be generally only text files. XODA uses the file extension to check whether a file should be considered editable. Common text file extensions are set by default but you should edit this list to correspond with your needs. Please use single space (" ") for separating the allowed extensions!
- "Image preview width" is the value in pixels used for preview of the images in the info box.
- "Show hidden" is an option for displaying "hidden" files and directories. "Hidden" is considered to be any file/directory which name starts with a DOT (e.g. ".xoda/").
- "Show total size" refers to the information displayed in the bottom part of the table with files/directories. Since the number of files and directories as well as the total size is calculated on every call, it might be useful to disable this once you collect bigger volume of information and the CPU of the server starts lagging this information. You still have access to this information in the info box of a particular directory.
- "Columns to be displayed": these are the optional columns of the table table with files/directories and their names should be self explanatory. I'd consider one tip though: you might want to uncheck "Size of the file/directory" since it is calculated on every call of the script and you would experience a lag if you have high volume directories.
- "Allow additional filters" toggles the opportunity to use filters as described above. Once this option is checked and a filter is set, a button "Filters" will appear on the navigation bar.
I admit, the plural here is not correct. It is a remnant from previous days, when I experimented with additional layers and did not change it because I (or you?) might still experiment with it. This option allows currently setting the "Top layer" only. This is the layer with the nice "XODA" on top of everything. As you see, is accepts HTML, so you might want to set a picture reminding you, how nice it is not to have all the paper around you.
This is just a web frontend for editing the style, saved by default as "style.css". Please do not hesitate to send me any new styles you may have developed!
I know you guys can make XODA look much prettier than I did. :)
By default XODA comes with the default user "admin" and the password "xoda". Adding new users is not only possible but also a good practice and changing the password is crucial!
In the example of the screenshot a second user with the name "tester" was created without root privileges. Since the logged user is "admin", the option for deleting "tester" is displayed. "admin" has the option also to give "tester" root privileges by selecting the checkbox.
Users with root privileges are administrators of the system. They can do everything, the system is programmed to do, incl. but not limited to creating, editing, moving, deleting, transferring files/directories, setting their descriptions and filters and have full access to the settings. Root users can add and delete other users incl. deleting other root user accounts.
Users without root privileges have only access to the files/directories but can not perform any modifications on any of the files/directories, their descriptions or filters. The regular users can (and should!) change their password and have no access to any of the other settings options.
Changing the password of the current user is the single most important factor to protect your files!
Please do this now unless you have done it already!
It is simple and not quite uncommon: enter your current password ("xoda" if left by default for the user "admin"), then enter the new password and confirm it. Pressing the "change" button will do the magic trick for you.
Enjoy you new Document Management System! :)
Please do not try monetary contributions to this project! Save your money and send them to Wikipedia or another Wiki*, you might think it would need support these days.
Try to contribute to any other open source projects if you can in another way! Sending patches, any feedback or even just suggestions is sometimes more appreciated than money. There are numerous open source projects out there which could make the change if they would get more support.
The world will be a better one with open source software despite the claims of evil software companies!
I'm testeng xoda (0.2.2) right now. I read that it is possible for a anonymous login, but i can't find that anywhere. What i want is that viewers can view the files without having to login. Thanks Bart
Hi Bart, you should use the current (svc) version of XODA for this option as it is not officially released yet. You can use the following command to download the current development version:
Please use the forum (http://forum.xoda.org) for future requests as this is the main support platform!Thank you and good luck! :)
Can users be allowed to see documents in a directory specifically created for them? I don't want user A to see documents for user B.
Andrew, please refer to the discussion (http://forum.xoda.org/discussion/5/per-user-root-dir.) in the forum (http://forum.xoda.org) about this.
Hey Betso, Excellent software and I am surprised by your "no donations" policy, are you certain? I have installed and gotten xODA working quickly and easily. I have a problem and a suggestion. Problem: When adding a user I continually get an error "ERROR: the specified home directory "/test" does not exist or is not a directory!" I have tried "test" and the full path to the location "/home/user/domain/xoda/test" all without success. Any thoughts about what could be wrong? Feedback: I suggest that in the config.sample.php you put a comment with the default password "xoda" in cleartext. I hadn't found a reference to it anywhere, couldn't log in and ended up pasting my own hashed password in. I know that this is the ultimate aim anyway, but it meant I couldn't even get started.
Hi Steve, You have to create the directory first as administrator before assigning it as a home directory for a user. The default password is in the README as well as in this Manual but it is maybe a good idea to list it as a comment as you suggest. Thanks for your comment! :)
Hi Betso, can I change the maximum file size to upload? does it depend on server setting? (I'm using Dreamhost)
Hi tomoyama!
The maximum file size for upload is a server setting and XODA is providing just information about this limit. Please refer to the official DreamHost Wiki about using a custom php.ini file (http://wiki.dreamhost.com/PHP.ini). Good luck! :)
I would like to use the opportunity and announce that all comments seeking support here will be deleted.
We have a forum (http://forum.xoda.org) which is the primary support platform and this was announced long time ago and I referred to this multiple times in comments, so there is no need to use the website for support questions.
Hello, Is there any support for laocalize Xoda? I try to find something like that no success. If apply I like suggest you to put an eye on this site: https://www.transifex.net/projects/ Regards,
Hi pertuk!
Unfortunately it is not easy to translate XODA as the output is integrated into the code for now. Recoding for pulling out the text output into an external array structure would require some time which I don't have at present.
I'm really sorry to disappoint you and to turn down a real help but this is the reality for now.
Best of luck and happy Holidays! :)