CRUD! I mean, sorry, Create Read Update Delete. In Ruby on Rails these concepts are very familiar. Because a RoR controller is typically tied to a particular model, and underlying relational table (ick) each controller comes built in with a set of CRUD methods. These are not provided when you create a Roxy controller. “Wait!” I hear you cry, “Wait! MarkLogic is used to search surely. Why, oh why, would you want to create content manually in MarkLogic Server!?!”. Well, I’m glad you asked! 8o)
A great use case for MarkLogic is to re-purpose existing content in to new content which can then be re-sold as a new product. Think of a large publisher. They are sitting on papers and books about Volcanos, Glaciers, City guides, Economics, a whole wealth of information. If I were to need to write a book on the last 25 years of Iceland, its history and make up, some of the above content could well be relevant. I may want to re-use it and include it in my new publication. These means I not only need to search for existing content, but I need to create new content that links these pieces together, perhaps with my own information (preface, contents, etc.) and save it as content in its own right.
In short I need to be able to create, read, update and potentially delete content. This means a commercial MarkLogic system, or indeed any system where you may need to create investigations, reports, or some other deliverable, will need to support CRUD methods in its controllers.
As I said, Roxy doesn’t provide these out of the box. They are trivial to add manually. You just use the command line ml tool as follows:-
ml create book/main html
ml create book/new html
ml create book/create html
ml create book/show html
ml create book/edit html
ml create book/update html
ml create book/delete html
This gives you everything you need for CRUD operations. You have main to list existing content (and Roxy creates this for you so you can search over rather than just list this content – a great time saver). You also have new to act as an entry form to create new content. Create is a PUT/POST operation that creates an item, then forwards to the show method. Edit is like show but is not read only. Update accepts a POST that updates a book, then forwards to edit (or show), and delete allows deletion, and is typically accessed from the show or edit pages, and usually restricted by role.
This is a great start, but has a couple of drawbacks. Firstly, although you can easily use one form to create a relational set of related facts (columns), this is hard for an entire document structure. You may also need extra controller functions. E.g. addChapter, linkChapter, removeChapter, listChapters. You get the idea. These don’t really make sense on their own as they belong as part of the book (<book> may be the document root element in your MarkLogic database, for example), so you’ll want to add these to the same book controller. A Roxy controller can thus be more sophisticated than a basic RoR controller ever would be.
Another unique thing about a document oriented paradigm like in MarkLogic is that you’re not searching content and creating new content as two separate activities. You may be navigating search results and dragging or dropping items on a webpage. This action of dragging and dropping may be updating the book (E.g. via linkChapter) whilst you remain on the search page. Thus you may have an embedded edit view for book within a separate controller’s (perhaps) search view. It makes sense therefore to support a RESTful interaction with the above CRUD methods.
The way to do this may be to add a ‘Create new book’ link on a right hand column on the search page. This may embed a mini new.html form to allow you to enter the title, genre, author info and other basics so you can later easily find the content. Clicking on ‘create’ would invoke the create method via AJAX and replace the new form with an edit form, that has a drop zone for chapters or other content you wish to interactively link in to the new book. When navigating pages this new book edit view must persist, so you’ll want to use xdmp:set-session-field() to store the current new book you’re working on, so the edit form can be rendered via ajax on each search page. Afterall there’s no problem delaying the edit form appearing as first you need to find the content anyway. This has the added benefit of the search page appearing quicker.
Once you’re linked all the existing content you need, you may click on a ‘Manage’ link on the book mini edit form to go to the full book controller’s edit page. This may be more sophisticated, allowing new content authoring and entry of extra book data. E.g. tags, summary, contents et al. This may use AJAX methods to update parts of the book on the fly too, all within the book edit page.
ml create book/edit htf
This creates an edit.htf.xqy view, and re-uses the edit controller function. If you re-factor the edit view so that the part that just shows the edit form is generated by a helper library (E.g.s lib-book-ui.xqy’s edit($book,$brevity) ) then you can show a detailed view on the full edit.html page and a more brief form on the edit.htf view.