MO References: Main Page
1.4
Summary
Introduction to the MO References module
The MO References module was created by Made to Order Software Corporation.
- Back to Summary
Requirements
MO References has no special needs from other Drupal modules. It requires you to have the following Unix tools to create the references, but it does not itself use those tools:
- tar, to create tarballs from your reference files
- gzip, to compress your reference tarballs
Note that modern Linux and other Unices support the -z flag on the tar command. It can be used to compress the documents without having to use gzip. Remember that a better compression will save you some space.
To create a valid tarball for this module to work, you must follow the following steps:
Put your documents in a folder named "foo", then create the tarball named foo.tar.gz like this:
tar czf foo.tar.gz foo
If your tar tool does not support the z flag, then do this:
tar cf foo.tar foo gzip -f9 foo.tar
The -f forces the compression to occur even if foo.tar.gz already exists (it will be overwritten.) The -9 asks gzip to compress with the highest level of compression available.
Note that the naming convention is important. If your tarball is named foo.tar.gz, then it must include the references under a folder named foo. Also, by default the system shows the index.html file found in that folder. If you do not have a file named index.html, you may setup the default index file by editing the settings of that reference. Go to /mo_references_view and click on the [edit] link of the reference to update. The [edit] link may be hidden, in which case you want to go to your administrative screen and turn that link back on.
The MO Reference is 100% compatible with the output of Doxygen, although it works with any static website that's compressed in a tarball. However, a very large tarball will very much slow your server down. I suggest you use a cache system such as Boost to prevent an incredible slow down of your server.
Note that the breadcrumbs are limited to: home, the reference list, and a reference main page.
The system is capable of going in the HTML code and extracting the first H1 tag to use as the title of your Drupal pages when displaying on of those static pages.
- Back to Summary
Installation
In order to install this module:
- Extract the tarball under sites/all/modules
- On your server, feel free to delete the doc sub-folder (it is safe since it is just and only static HTML)
- Go to admin/build/modules and select MO References
Once the module was installed, make sure to visit the module administrative area. This includes a path to your references. Without that path, the module will not operate (page not found errors will be generated.)
You want to have at least one reference in your reference folder. You can see that reference by going to /mo_reference_view which actually gives you a list of all your references. Here you can click on one of the references to review the contents of that reference. The body tag of HTML files is extracted and presented in place of the contents of your page (where the contents of a node would otherwise appear.)
- Back to Summary
Security with this module.
The module was built primarily to display free Doxygen documents to our customers. If you have private documents, please, test and make sure that they stay private.
The documents are accessed via mo_references_view. That path can be followed by the name of the document and the path and name of the files inside the document. There is no other way to load the content of one of your document.
The users are given permissions via the standard permission screen. You can assign one of the 3 permissions to your different roles. The available permissions are:
- access references -- Whether a user can view the content of a document
- administer references -- Whether a user has access to the global administration screen of MO References
- edit references -- Whether a user has access to the forms used to manage the different documents available
Note that administration and edit rights must only be given to trustworthy people. The edit feature let your users select the filter to be used on a documentation. Selecting the wrong filter can cause harm.
The documents that you trust can make use of the Full HTML filter. Others should make use of your Default filter or some similar filter that includes the HTML validate filter.
- Back to Summary
Errors generated by this module.
The module will not function, and give you an error, until you specify a path to your documents. The path can point anywhere on your server as long as your Web server can access the data in the folder in read mode.
Users may get an Access Denied error until you give them permission to view the content of your documents. By default, the permissions are turned off for security reasons. Permissions can be granted on a per role basis as usual.
Users attempting to view a page inside your documents that does not exist will generate a Page not Found error. Adding a missing file or fixing a link will prevent the error.
The module recognizes HTML pages that have the .html or .htm extension. Any other page is sent as is. This can be a security issue if you have files that can cause harm on someone's system.
- Back to Summary
Changes between versions
- Version 1.2
* Fixed the home folder of each reference by forcing the '/' at the end of the path. Without that '/' it would generate the wrong links. * Added proper breadcrumb so one can navigate using those. * Added a link to the .tar.gz file of references. * Added a link to Ping.fm * Removed the link to the main page of a reference when on that very page. * Added a 'download references' permission so .tar.gz files may only be downloaded by authorized users. * Redirect users who hit unknown pages with a 301 instead of a 404, sending them to the main page of that reference.
- Version 1.1
* Fixed the default format that was not properly selected.
- Back to Summary
Copyright (c) 2009-2011 Made to Order Software Corp.
http://www.m2osw.com/mo_references contact@m2osw.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- Back to Summary
on Sat Mar 12 16:05:37 2011