Publish folders and documents from API scripts

What you'll see

You are building a SaaS app on Docly: a sign-up endpoint in #/API/ should create a website for each new customer and publish it on one of your domains, for example customers.example.com/ola/. Until now a script could create folders and files and read publications with docly.getPublications(), but not publish anything.

What's actually happening

Four functions are available to scripts in the API folder (.js files under #/API/). They are not available in page templates.

• docly.getDomains() returns [{ domain, https }] – the verified domains on the workspace's subscription. Unverified domains are left out because they cannot be published on.
• docly.publishFolder(path, { domain, alias, template, authMode }) publishes a folder and returns the publication in the same shape as a row from docly.getPublications().
• docly.publishDocument(path, { domain, template, alias, authMode }) does the same for one document. template is the template's id or display name, and may be left out when the document's schema has exactly one.
• docly.unpublish(guid) removes a publication and returns true. The guid comes from publishFolder, publishDocument or getPublications.

All four require SaaS on the workspace's subscription (Docly Cloud → subscription → API access). Without it they throw "Publishing folders and documents from scripts is not enabled on your subscription." (result code 16) before anything happens. A workspace with no subscription gets the same message as the Publish dialog.

The reach is the site's own folder. A folder must lie below the site, and a document inside it. Folders elsewhere in the workspace and the app's (template's) files are reported as path not found in the site, and the site itself cannot be given another address. unpublish only removes publications of something inside the site.

The script publishes as the user who published the site, through the same code as the Publish dialog. Publishing rights, the domain's subscription and the one-URL-one-publication rule are all checked there, so a script can never do more than that user can do by hand.

What to do

Do – put customer sites under #/Websites/ and take the domain from getDomains:

// #/API/signup.js
export default function (form) {
  var path = "#/Websites/" + form.slug;
  docly.createFolder(path);
  docly.saveFile(path + "/index.html", form.html);

  var domains = docly.getDomains();
  var pub = docly.publishFolder(path, { domain: domains[0].domain, alias: form.slug });
  return { url: pub.url, guid: pub.guid };
}

Content under # is not reachable from the main site, so the customer sites do not show up as pages of your app.

Options for publishFolder:

• domain – required. The name as getDomains returns it, not an id.
• alias – the path under the domain. Defaults to the folder name.
• template – the app folder the site runs: short guid, F-prefixed or full guid.
• authMode – leave out for a public site, 2 = sign-in by redirect, 3 = sign-in in a popup.

Things to know:

• Changing an existing publication (address, domain, sign-in) is not supported. Call unpublish and then publishFolder.
• Turning SaaS off stops new publishing. What a script has already published stays published.
• The error messages are fixed texts and never repeat what you sent. Catch them with try/catch and show your own message to the end user.
• The normal publishing rules apply: one URL can only be published once, the aliases app/ and api/ are reserved, and numeric aliases are not allowed.