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:

adding documents

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.

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

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

dms edit

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.

dms edit

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.

dms front-end

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.

 

Post your comment

Note: Comments are moderated and won't show until they are approved

Comments

  • Looking forward to using this on future projects. Thanks a lot SS team.

    Posted by Ryan M, 1 year ago @mclryan

  • This looks really nice - to bad my current project is on 2.4.8 - this module is just what i need.

    Posted by Nobrainer Web, 1 year ago @nobrainerweb

  • Wow, this sounds awesome. Looking forward to try it out.

    Posted by Joel Grøndrup, 1 year ago

  • Hey Julian,

    awesome work !! Your module fills a gap. I had my own module for this, but for future projects I will definitely use DMS.

    Greets from Hamburg

    Andy

    Posted by Andy Piening, 1 year ago

  • This looks great, I've made some learning websites before where they've had requirements for documents to be available on a week-by-week basis.

    One query, I've noticed this is not yet enabled to be installed using Composer.

    Posted by Matty Balaam, 1 year ago @matthewbalaam

  • Nice module! Do you plan to implement some sort of optional file permission, maybe inherited from the page where the file belong?

    Posted by g4b0, 1 year ago @gabotheoriginal

  • Hi Julian,
    thank you very much for this article and the module. This looks like a great improvement to document handling in the Silverstripe 3 backend and I will try it in some of my current projects.
    Respects!
    Hendrik

    Posted by Hendrik Schaper, 1 year ago

  • This looks like a great module, and something that was sorely missed from the DOM setup with GridField - so awesome work SS team!

    One suggestion I have is that you don't add the DMS UI to every page by default. My general usage for the file manager in DOM was that I would add it to certain pages that required document management. I understand that I could simply remove the code from the module that's adding it to every page, but that would require 'hacking' the module which would disappear on upgrades. I could also remove that field in my page class - but IMO it would make sense to be the other way, the field only appears where I explicitly tell it to. My 2c anyway.

    Again though, awesome work! It's great to see the flexibility of GridField like this.

    Posted by Adam, 1 year ago

RSS feed for comments on this page | RSS feed for all comments

Want to know more about the company that brought you SilverStripe? Then check out SilverStripe.com

Comments on this website? Please give feedback.