SilverStripe

Document Management System Module

Posted by Julian Seidenberg on 21 November 2012

I have the pleasure of introducing a new module that we created here at the SilverStripe HQ - The Document Management System (DMS) module. 

History

A few years ago, community member Aaron Calino (UncleCheese) created the Data Object Manager module for SilverStripe 2. This module was packed with features that allowed users to manage DataObjects related to pages. However, as Aaron has stated in this forum post, the new GridField class in SilverStripe 3 does much of what Data Object Manager did in SS2, so he won't be making a version of Data Object Manager for SS3.

We found ourselves needing something similar to the old Data Object Manager module in one of our recent SS3 projects. We took this opportunity to create a great new open source module, a module built in the same spirit as the Data Object Manager, built on SS3 from the ground up, and built to serve as the basis for sophisticated Document Management with SilverStripe now and in the future.

Design goals

We had several goals in mind when designing the DMS module:

• Painless association of files with pages
• Simple, clear and reliable file storage system
• Extensible and customisable architecture
• Easy UI for uploading, replacing, and linking files

The first item in the list needs some explanation. Traditionally, SilverStripe has a "Files and Images" section where you upload files, then add these files to your page when you need them. This has the advantage that you can easily reuse a single file on multiple pages. However, more often than not, you will only ever need a file uploaded to a single page, and having to separately upload the file into "Files and Images" unnecessarily complicates the process. Additionally, if you want to replace a file with a new version, finding the underlying file from a reference on a page can quickly become tedious.

Our solution is to directly associate files with the pages, skipping the "Files and Images" section completely. We then polish the process for doing so to make it as smooth, reliable, and painless as possible.

The files themselves are stored in a folder structure under a new "dms-assets" folder. We intentionally preserve the filename of each file (as opposed to hashing names) to make it easier to find your file again in case something goes wrong. We do, however, add the database ID number to each filename, so that the link to the database record is obvious and extremely fault-tolerant. We use a number of folders for the files, so that all the files don't just end up in one gigantic folder. You can configure how many files go into each folder to suit your deployment.

In case you're wondering about the scaleability of the DMS module. We are currently using the DMS in production with tens of thousands of documents and it doesn't even break a sweat.

Feature walkthrough

Here is a walk-through of some features of the DMS module:

When you first install the DMS module, every page in the CMS gets a new "documents" tab. On that tab you can click the "Add Documents" button, which takes you to the screen above.

Uploading is really easy. You just drag and drop (in modern browsers), and/or select files with a dialog box. Immediately after you upload files, you get the opportunity to either edit each file's metadata, or just click "Done" to go back to the page you were on.

You can also link documents from other pages. You do this either by typing in an autocomplete search field (referencing files by name and/or ID), or by clicking the "Browser by page" button to get a TreeDropDown view of the page structure. The linked document appears on the current page, as well as the page where it was originally uploaded.

You can link any document in the DMS to any page. A document does not "belong" to a specific page. For example, if you upload a document to Page-A, then link it to Page-B, then delete the document from Page-A, the document will stay on Page-B, as if nothing had happened. Reference counting keeps track of everything.

Here is the DMS grid (powered by the SS3 GridField). It allows you to do a quick download, go to the detailed edit view, and delete or unlink the current file (if a file is only attached to a single page, then you get a "delete" button; otherwise, if the same file is attached to multiple pages, you get an "unlink" button). You can filter/search the grid by clicking on the "magnifying glass" button in the top-right corner.

You can also sort the list of files in the grid with drag-and-drop if you drop in this SortableGridField module. Similarly, the "Show all" button on the footer appears if you install this GridFieldPaginator module. Both are nice demos for how you can easily extend the functionality of the DMS with add-on modules.

The Detailed Editor view gives you the ability to view and edit a document's metadata. The DMS also has embargo and expiry built into it. So you can schedule documents to appear or disappear at a specific date. You can replace a document using drag-and-drop. "Find usage" shows other pages where the current document has been linked. "Find references" shows you pages where the current document has been referenced in the HTML content (more on that later). Finally, "Delete" deletes the document from this page and all other pages where it is used, giving you a warning pop-up before proceeding.

This feature of the DMS allows you to insert a link to a DMS document into the HTML content of a page. The DMS adds a new option to the CMS link editor. You can use the combined auto-complete-search/PageTree-browse view to find the document you want to link to and insert the link. Again, reference tracking keeps track of each link you add and allows you to view where each document is linked in the Detail View.

Finally, there has to be a way to display the documents in the website front-end, right? Of course there is. That requires a small change to your Page.ss template. Just add <% include Documents %> to the template wherever you want the documents to appear. That will give you a document listing similar to the one in the screenshot above.

Start using the DMS and contribute

We hope you like the new DMS module. Please try it out. Like all of SilverStripe, it is open-sourced using a BSD license. Click to download the Document Management System module.

We are keen to hear your feedback. If you have an idea for improving the module, please discuss it in the forum, or send us a github pull-request. Here are some ideas we have thought of already:

• You can add a search box to your site that searches through the full-text of all documents using the fulltext-search module.
• We are currently working on a simple method of versioning the files in the DMS. So, if you replace a document, the previous versions of that document are kept for archival purposes. This is coming soon.
• A new feature we are thinking about adding is a view that shows you all the documents in the DMS in a single view, a view you can use to conveniently search and edit all documents in the system. However, it might take a while until we get to doing this.