Custom DeskClient Actions using Client Scripts

These extensions appear as actions in the editor toolbar and in the document context menu or are run in the background when the user executes some document actions.

Custom client actions can do any of the following things:

• Read and modify the Sophora document of the active editor.
• Show a message box to the user.
• Search for documents in the Sophora Primary Server and show the result list in the search view.
• Full access to the Sophora Primary Server using the Client API.
• Abort the current user operation.

When a client action is selected in the editor toolbar or the document context menu, the corresponding script is executed in the DeskClient. The script will have access to the document currently active in the DeskClient and will have the permissions of the current user.

When a document action is executed (like publish, save or delete) the corresponding scripts are executed in the DeskClient. The script will have access to the document and will have the permissions of the current user. The script should not assume that an editor is currently open. But if an editor is open it can be updated.

Creating a Client Script

To create a new client script, open the Administration view and select Client Scripts > New: Client Script. A client script is a Sophora system document with the following fields:

The following script types are available:

The following document sources are available:

A script can support one to all of the sources. If a script is only a background script triggered on document actions like 'publish' or 'save' no document source has to be selected. In this case, the script will not appear in a UI menu.

Writing the Script Code

The source code of scripts has to be written in Groovy. In code you have access to some variables and methods to communicate with the Sophora DeskClient and Sophora Server.

Variables and Methods Available to Scripts

There is a fluent API for creating dialogs in client scripts. It is accessed by context.dialog(). The following table shows all calls possible to such an dialog. There's also an example.

Default Imports

These classes are imported for all client scripts:

• java.io.*
• java.lang.*
• java.math.BigDecimal
• java.math.BigInteger
• java.net.*
• java.nio.file.*
• java.util.*
• groovy.lang.*
• groovy.util.*
• com.subshell.sophora.api.*
• com.subshell.sophora.api.content.*
• com.subshell.sophora.api.content.value.*
• com.subshell.sophora.api.exceptions.*
• com.subshell.sophora.api.nodetype.*
• com.subshell.sophora.api.search.*
• com.subshell.sophora.api.structure.*
• com.subshell.sophora.client.*
• com.subshell.sophora.client.clientscript.*
• com.subshell.sophora.client.clientscript.field.*

Get the Right Document(s)

Client scripts can be run in the background (triggered by a document action), in the context of an open editor or having documents selected outside of an editor, for example in the search view. Therefore scripts have to be configured from where they get the documents they work on: the active editor, the current selection, both or none.

If your script should run ...

• ... only on the document of the active editor, you can use context.getDocument() to get it like before version 1.53.
• ... only on the selected documents outside of an editor, you can use context.getSelectedDocumentSummaries() to get them. Note that only summaries of the documents are returned and you have to get the full documents and locks by client calls if you want to modify and save them.
• ... on both document sources (depending on the focused view/editor), you can use the methods from above or just context.getDocuments() to get the focused document(s). The method context.isFromEditor(IContent document) helps you to get the information whether the given document is opened in the focused editor.
• ... in background triggered by actions like 'publish' or 'save', you do not have to specify a document source but you can use the above methods to get the document(s) the action has been triggered on.

The small script below works for all cases from above and demonstrates the methods context.getDocuments() and context.isFromEditor(IContent document) by just printing the focused documents in a dialog. This will show you which document(s) will be handled in which case.

List<INode> docs = context.getDocuments()
if (!docs.isEmpty()) {
    List<String> ids = docs.inject(new ArrayList()) {
         result, doc -> result.add(doc.getString('sophora:id') + " (is from editor: " + context.isFromEditor(doc) + ")"); result
    }
    context.dialog().showMessage("Documents:\n" + ids.join('\n'))
} else {
    context.dialog().showMessage("No documents")
}

Examples

Example 1: Edit document of active editor

The following script shows the content of the property "sophora-content:topline" of the document in the active editor to the user, then it sets the property to a new value:

def doc = context.getDocument()
def name = doc.getString('sophora-content:topline')
context.dialog().showMessage("The topline is '" + name + "'.")
doc.setString('sophora-content:topline', 'Breaking News')
context.updateDocument(doc)

Example 2: Searching for other documents

The next script searches for all documents with 'something' in the repository and shows the result in the search view (the Query object has to be an instance of com.subshell.sophora.api.search.IQuery):

def q = new TextQuery("something")
def params = new SearchParameters()
params.pageSize = Integer.MAX_VALUE
def searchResult = sophoraClient.findDocumentUuids(q, params)
if (searchResult) {
	context.showDocumentListToUser("Matching documents", searchResult.UUIDs)
} else {
	context.dialog().showMessage("No matching documents found.")
}

Example 3: Script triggered by document action

The following script copies the value of the property "sophora-content:topline" to the property "sophora-content:title". It saves the changed document, if the script was called before the document is published.

import static com.subshell.sophora.client.clientscript.ClientScriptTrigger.*

def doc = context.getDocument()
if (!doc) {
	doc = context.getDocuments().get(0)
}
def topline = doc.getString("sophora-content:topline")
if (topline) {
	doc.setString("sophora-content:title", topline)
} else {
	doc.removeProperty("sophora-content:title")
}

// this check is unnecessary if the script is only configured for "Triggered by: Publish"
if (context.getTrigger() == DOCUMENT_ACTION_PUBLISH) {
	context.saveDocument(null, doc)
} else {
	context.updateDocument(doc)
}

Example 4: Use a dialog to get input from user

The following script asks the user to input a date, a label and confirm the rules. Therefore a dialog with input fields will be build. Note that the type of field value retrieved from the IDialogResult depends on the input field type.

import static com.subshell.sophora.client.clientscript.field.DialogFields.*

def dialogResult = context.dialog().withTitle("Example Script").create()
	.addLabel("Please choose the date and describe the action.")
	.addField("date", "Date of event", date())
	.addField("action", "Action text", text("Once upon a time ...").charCounter().maxChars(118).required())
    .addField("attachment", "Attachment", file(FileMode.FILE))
	.addField("location", "Location", structure(context.getDocument().getStructureNodeUuid(), sophoraClient.getFilteredStructureFactory().getReadableStructure(), false, false))
	.addField("confirm", "Acknowledge rules", checkbox())
	.open()

// same getter but type depends on field
Calendar date = dialogResult.get("date")
String action = dialogResult.get("action")
Path attachment = dialogResult.get("attachment")
boolean confirmed = dialogResult.get("confirm")
// do something with the values

Example 5: Use a merge dialog to merge a document

The following script shows how to open a merge dialog and process the user's input after the dialog has been closed i.e. merge a document based on the results of the dialog.

This can be useful if you want to offer the possibility of merging the content of a standard document into others.

Open the merge dialog

ISophoraDocument targetDocument = context.document
ISophoraDocument mergeNode = sophoraClient.getDocumentByUuid(UUID.fromString("8b549962-1514-42b8-952c-1b4ce241da0e"))

IMergeDialogResult dialogResult = context.dialog().createMerge()
	.setOriginalData(targetDocument)
	.setNewData(mergeNode)
	.setPropertiesAndChildNodes(["sophora-content:title"] as Set,
		["sophora-content:copytext", "sophora-content-nt:storyref"])
	.open()

Perform the actual merge based on the dialog's result and trigger post merge scripts.

if (!dialogResult.abort) {
	boolean successful = context.merge(targetDocument, mergeNode, dialogResult)
	if (successful) {
		sophoraClient.saveDocument(null, targetDocument)
	}
}

Example 6: Use a script to open a document in an editor

The following script opens or focuses an editor with the given uuid. A dialog is shown with a specific reason if a document with the uuid could not be found.

def uuid = UUID.fromString("50fc8c22-56d1-4155-885a-19fb0790e6f1")

try {
 	context.openInEditor(uuid)
} catch (SophoraException e) {
	context.dialog().withTitle("Error: Could not open the document") 
 		.create()
		.addLabel("Could not open the document in an editor, reason:")
		.addLabel(e.getMessage())
		.open()
}

Example 7: Use a script to execute mass operations, e.g. to set multiple documents offline

The following script sets the given documents offline while showing a progress dialog to the user.

context.doWithProgress("Set everything offline", documents, {document -> document.getSophoraId()}, {document -> document.setOffline()}, true)

Example 8: Open a document for a custom URL

If a user tries to open a document from an URL in the clipboard and the URL cannot be resolved by Sophora a script can be triggered. In such a script you can open a document editor for the URL.

Create a client script with the field "Triggered by" set to "After "Open document by URL in clipboard" couldn't resolve the URL". To access the URL in the script call context.getTextFromClipboard(). Afterwards process the URL and determine which document it refers to. You could for example do a query for a part of the URL by using the sophoraClient.
Afterwards the script must open the editor itself by calling context.openInEditor(UUID). If no document was found a feedback message should be displayed to the user that no document could be found as the DeskClient will not display it if scripts exist.

String url = context.getTextFromClipboard()
// resolve the document from the text as you need
String sophoraId = url.split('/').last()
Optional<ISophoraDocument> document = client.getDocumentBySophoraIdIfExists(sophoraId)
// open document or show message if none found
document.ifPresentOrElse(
		{ doc -> context.openInEditor(doc.getUUID())},
		{ context.dialog().showMessage("Es konnte kein Dokument ermittelt werden zu der URL '${url}'")})