5.14.5 Document editor initialisation

5.14.5.1 Introduction

Usually users create new documents by choosing a document type on the "New document" page. Sometimes it can be useful to create documents from other places, or to have the editor initialised with certain content (e.g. a field with a value already assigned or so). Here we have a look at the various ways to launch the document editor for creation of a new document.

5.14.5.2 The basics

To open the document editor for the creation of a new document, do a HTTP POST operation to the following URL:

http://localhost:8888/daisy/<sitename>/new/edit

Of course, change the host name and port number, the mount point ("/daisy") and the sitename to match your situation. This URL needs to be supplied with different parameters depending on what you want to, as described in the next sections.

5.14.5.2.1 startWithGet parameter

In some cases, you may want to redirect to the document editor from some server-side code. In such cases it is not possible to do a HTTP POST operation. Therefore, a special startWithGet parameter is available, to be used as follows:

http://localhost:8888/daisy/<sitename>/new/edit?startWithGet=true

5.14.5.2.2 returnTo parameter

Normally, when the user is done editing, the user will be shown the document that was just edited (or, when pressing cancel and it was a new document, the site's home page will be shown). It is possible to control where the user will be brought to after editing a document by means of a returnTo request parameter:

http://localhost:8888/daisy/<sitename>/new/edit?returnTo=/some/path/of/your/choice

This is useful when the edited document is part of some aggregated display, and you want to bring the user back to the aggregated page, rather then edited document.

5.14.5.3 Create a new document of a certain type

This is the most common case. The editor will be opened with a blank document of a certain type. The document type needs to be specified in a parameter called documentType, either by name or ID.

Thus for example, doing a POST to this URL will open a new editor for a SimpleDocument-type document

http://localhost:8888/daisy/<sitename>/new/edit?documentType=SimpleDocument

Optionally, branch and language parameters can be added if they would differ from the site's default.

5.14.5.4 Create a new document starting from a template document

This allows to create a new document by starting from the content of an existing document in the repository. This is the same as the "duplicate document" functionality that is available in the Daisy Wiki.

The ID of the template document needs to be specified in a parameter called template. Branch and language can optionally be specified, they default to those of the current site.

http://localhost:8888/daisy/<sitename>/new/edit?template=123&branch=main&language=default

5.14.5.5 Creating a new document variant

The cases described until now were about creating entirely new documents. Here we look at how to open the editor to add a new variant to an existing document.

The following request parameters need to be specified, all required:

• variantOf: the document ID
• startBranch and startLanguage: specify the existing variant from where to start
• newBranch and newLanguage: specify the new variant to create

The branches and languages can be specified by name or ID.

So an example URL could be:

http://localhost:8888/daisy/<sitename>/new/edit?variantOf=123&startBranch=main&startLanguage=en&newBranch=main&newLanguage=fr

5.14.5.6 Creating a new document with custom initialisation

This allows to open the editor with certain data already in the new document. It works as follows:

• create a Daisy Document object, set its properties as desired
• put the created Document object in a request attribute
• and then do an internal redirect to the editor, specifying a parameter templateDocument with the name of the request attribute containing the Document object.

This requires that you create a Daisy Wiki extension.

Here is an example:

cocoon.load("resource://org/outerj/daisy/frontend/util/daisy-util.js");

function makeNewDocument() {
    var daisy = getDaisy();
    var repo = daisy.getRepository();

    // Create the document
    // The parameters are the document name and the document type name
    var newDoc = repo.createDocument("A new document", "SimpleDocument");

    // Set some initial content in a part
    // The part content must be given as a byte array
    var initialContent = new java.lang.String("<html><body><p>Type something here."
                            + "</p></body></html>").getBytes("UTF-8");
    newDoc.setPart("SimpleDocumentContent", "text/xml", initialContent);

    // Add the document to the site's collection
    var siteCollection = repo.getCollectionManager().getCollection(
            daisy.getSiteConf().getCollectionId(), false);
    newDoc.addToCollection(siteCollection);

    // Store the document in a request attribute. The request attribute can have any name
    cocoon.request.setAttribute("myDoc", newDoc);

    // Switch to the editor
    var url = "cocoon:/" + daisy.getDaisyCocoonPath() + "/" + daisy.getSiteConf().getName()
              + "/new/edit?templateDocument=myDoc&startWithGet=true";
    cocoon.redirectTo(url);
}

For those not familiar with extensions yet, lets make the example complete.

Create a subdirectory in <wikidata dir>/sites/cocoon, for example called 'newtest'. Then save the above script in a file test.js in the newtest directory. Also in the newtest directory, create a file sitemap.xmap with the following content:

<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

  <map:components>
  </map:components>

  <map:views>
  </map:views>

  <map:resources>
  </map:resources>

  <map:flow language="javascript">
    <map:script src="test.js"/>
  </map:flow>

  <map:pipelines>

   <map:pipeline>
     <map:match pattern="newtest">
       <map:call function="makeNewDocument"/>
     </map:match>
   </map:pipeline>

 </map:pipelines>

</map:sitemap>

You can now call this example by surfing to the following URL:

http://localhost:8888/daisy/<sitename>/ext/newtest/newtest

(replace <sitename> and other stuff as appropriate. The first 'newtest' corresponds to the name of the 'newtest' directory, the second 'newtest' is the pattern matched in the sitemap.xmap)