Configuring the DeskClients

There is a "Configuration" menu item in the navigation panel of the administrator view. Here you can define general settings that apply for all DeskClients.

Table of Contents

Configuration Parameter

There is a "Configuration" menu item in the navigation panel of the administrator view. Here you can define general settings that apply for all DeskClients.

To edit the configuration expand the menu item and open the configuration document via double click or using the context menu.

The name of a configuration document can be set arbitrarily. In addition, there may be multiple configuration documents whereas only one can be employed in a Sophora server (see property sophora.configuration.document.externalId of the Sophora server)

The actual configuraton is done using key value pairs in the document's table (see figure below). Each key can get assigned multiple values. The ordering of the individual rows can be altered with the arrow icons.

Creating a new entry:

  1. Click on the [TABLEROW_INSERT_BEFORE] icon (before the current row) or the [TABLEROW_INSERT_AFTER] icon (after the current row) on the left side of the table.
  2. Enter a key in the left column.
  3. Click on the "..." button in the right column and enter the values in the emerging dialog (there again, entries are added with the help of one of the icons).
  4. Confirm with OK.

Editing an entry:

  1. Select the entry you want to edit.
  2. Click on the "..." button in the right column and edit the desired values in the emerging dialog (additional values can be added with the help of the icons; see above).
  3. Confirm with OK.

Removing an entry:

  1. Select the entry you want to remove.
  2. Click on the [TABLEROW_DELETE] icon on the left side of the table.

When you are finished save the configuration document.

Add a new configuration document:

  1. Mark the menu item "Configuration", open its context menu and select "New: Configuration".
  2. In the emerging dialog, you may select a different structure node than the system site for localisation and enter an altering ID stem for this configuration document.
  3. Clicking on "finish" opens an empty form for configuration parameters. Here, you can set up the properties.
  4. Save the new configuration document.
The newly created configuration document will not be recognised as long as you have not announced it to the Sophora master sever (see property sophora.configuration.document.externalId of the Sophora server). Keep in mind that only one document at a time can be employed by the server.

In the following sections, parameters - ordered by Sophora components and functions - are displayed in tables containing all valid keys and their explanations. These parameters can be used in the previously described way (adding, editing and removing) in a configuration document.

DeskClient

The subsequent table consists of parameters that directly affect the DeskClients.

ParameterDescription & Example
component.tab.sophoraid.visibleManages the visibility of the Sophora ID in the compact view of the component tab.
Values: true and false
Default: false
componentstructure.inheritance.canDisableIf set to false, inheritance of hierarchy groups can not be (de-)activated by context menu in the document editor's components structure view.
Default: true
componentstructure.inheritance.editInHierarchyDocumentsOnlyIf set to true, inheritance of hierarchy groups can be (de-)activated in hierarchy documents only (by context menu in the document editor's components structure view).
Note that componentstructure.inheritance.canDisable must be set to true.
Default: false
componentstructure.legacyComponentModeIf set to true, the legacy behavior on determining the allowed components in component groups is enabled. This affects reference types that extends another reference type. See issue SOCI-869 for further information.
Default: false
componentstructure.useDocumentReferenceLabelIf set to true and a reference label is configured in the reference type of a component, the reference label will be shown in the document's component structure instead of the Sophora ID.
Default: false
(Since version 2.5.4)
deskclientHelpSearchUrlURL to search for help
Example: http://my.sophora-host.de/cmswiki/index.php/search
deskclientHelpIndexUrlURL of the help index
environment.nameA name for the server environment that is displayed in the DeskClient, e.g. "PROD", "LIVE", "TEST"
environment.descriptionAn optional description for the server environment that is displayed in the DeskClient, e.g. "This is a test system for experimental usage."
geoData.document.uuidUUID of the Geo Data document which is used as a filter in terms of geo-blocking. This parameter is deprecated, use geoData.document.
externalId instead.
Example: ce619611-da26-48ac-a88f-28fc6b6908bb
geoData.document.externalIdExternal ID of the Geo Data document which is used as a filter in terms of geo-blocking.
Example: geodata or 951663af-814c-4175-8da6-8b40d544cb12
sophora:attributeSets the name of the attribute property of reference node types (node types that inherit from "sophora-nt:reference") respectively components. This property has to be configured as a select value field. The label of the selected selectvalue in a component is displayed in the full mode on the components tab in the document editor of the deskclient. The default property name is sophora:attribute.
document.state.disallowedUuidsForOfflineList of UUIDs of documents that must not be set offline. This parameter is deprecated, use document.state.
disallowedExternalIdsForOffline instead.
document.state.disallowedExternalIdsForOfflineList of External IDs of documents that must not be set offline.
document.export.propertiesNotToExportInSophoraXmlList of property names that should be excluded when exporting documents to Sophora XML. In most situation the following default value should be used:
sophora:id
sophora:site
sophora:structureNode
sophora:liveStructureNode
sophora:category
sophora:state
sophora:isOnline
sophora:creationDate
sophora:createdBy
sophora:modificationDate
sophora:modifiedBy
sophora:publicationDate
sophora:publishedBy
sophora:externalId
sophora:originalDocument
sophora:isDeleted
sophora:enabledChannels
sophora:disabledChannels

sophora:idHistory

Note that the property sophora:tags has been removed from this list because it became a configurable property as every other. Before, the tags experienced a special treatment so that they need to omitted from now on.
document.export.stringToReferencePropertiesMapping node type and properties that should be exported as external reference.
Format:
NodeType=propertyName,propertyName

Example:
sophora-content-nt:teletextPage=sophora-content:template

sophora-content-nt:teletextSlotPage=sophora-content:page, sophora-content:slot
document.file.saveFilePathIf enabled, the paths of file attachments in documents will also be saved. If disabled the file paths will not be saved and already saved file paths will not be shown in the documents.
Values: true and false 
Default: false
The path will be saved in the property sophora:filepath in sophora-nt:binaryData.
Note that the user may prevent the file path from being saved in his user preferences.
document.idstem.filter.regexpRegular expression to constrain the ID stem property.
Example:
[a-z]+ (only lower case letters)

Note: Even if a custom id stem regexp is defined, all id stems have to match the system internal id stem regexp (?![iI][nN][dD][eE][xX][_-])[-a-zA-Z0-9_]*[-a-zA-Z_] as well.
document.image.bulkCreate.limitSet the limit for a bulk creation of image documents, if the system permission for mass upload of images is set. If there is no configuration for that property, the user can upload an unlimited number of image documents.
document.publish.dialog.hideDocumentsWithPublishAtDateIf set to true, by default hides documents with a 'Publish At' date set in the dialog 'Unpublished Components' when publishing documents. A user can overwrite this setting in his personal preferences in the section 'Documents'.
adminDashboardUrlURL of the admin dashboard
contentTypePropertyNameName of the (string) property for the content types (used for, e.g., submenus in document type filters within the search).
Default: sophora:contentType
This property has to be configured as a select value field within a specific node type configuration.
deskclient.document.release.buttonVisibleManages the visibility of the button "Release" in the toolbar. Changing this parameter requires a restart of the deskclient.
Possible values are true and false. Default is true
image.autoscale.jpegCompressionRatioCompression ratio when automatically downscaling JPEGs. Values inbetween 1 and 100. Default is 75.
image.alignment.horizontal.defaultDefault horizontal alignment for image sections of newly imported images. Possilbe values: left, center & right
Default: left
image.alignment.vertical.defaultDefault vertical alignment for image sections of newly imported images. Possilbe values: top, center & bottom
Default: top
proposal.endDate.default
(since 2.5.24)
Set the default period of a proposal. unknown leaves the field empty (see proposals).
Values: day, two days, week, month, unknown
Default: day
timing.validDateReferencePropertiesAllowed date reference properties for the timing configuration of structure nodes (example: sophora:creationDate). This is a multiple value field.
If no values are set or the key is missing, no filtering will be done (all date references are allowed).
Default:
tags.assist.enabledEnable or disable input assistance for tags in the search text input field, in the document editor's tag field and in the id stem field within the New Document Wizard and Change Id Stem dialog.
Values: true and false
Default: true
searchAgent.updateIntervalThe interval that should be used to automatically update search agents in the DeskClient (in seconds.)
Default: 300
sophora.client.connection.isReadAnywhereEnables the readAnywhere functionality for all clients.
user.password.regexThe regular expression all (new) user passwords have to match to be valid i.e. saveable.
user.password.regex.descriptionThe description for the regular expression for the user passwords. If the user enters an invalid password the description will be shown.
document.clone.technical.enabledEnable or disable technical clone. The difference between two types of clones is that with editorial clone the ID of the original document will be saved in the property "sophora:originalDocument" of the clone whereas with technical clone this property will be left blank. When set to true it will result in a submenu with two options of cloning at clone menu entries: technical and editorial. When set to false only editorial clone will be available, the clone action will be associated directly with editorial clone (there will be no submenu). Default is false.
spellcheck.initiallyEnabledSet the default enabling of the spell checking option. As soon as a user switches the spellchecking on or off, this will be saved in their personal preferences and overwrites this setting for them. The default is false; any other value than true (non-case-sensitive) will be interpreted as false.

User Management

The following table lists parameters which affect user accounts.

ParameterDescription
sophora.authenticate.expireAfterDaysSpecifies the duration (in days) after which a user's account expires if they have not been logged into the Sophora server during that time.
sophora.authenticate.expireAfterDays.helpAn additional help text that will be displayed in the error dialog when the user tries to log in, but the account is expired.
sophora.authenticate.changePasswordAfterDaysSpecifies the duration (in days) after which users are required to change their password.
passwordLost.mail.subjectThe subject of mails that are sent to users containing the code for the "password lost" function.
passwordLost.mail.textThe text of mails that are sent to users containing the code for the "password lost" function.

${code} inserts the actual code.
\n inserts a line break.

HTTPS Connection Configuration

The following system parameters for the configuration of a HTTPS connection to the sophora server also apply to other sophora components. For the DeskClient these parameters can be configured in the deskclient.ini file. These parameters must be set behind the -vmargs parameter like:

-vmargs 
-Xmx1024m 
-Dsophora.auth.trusted.certificates.only=true
ParameterDescription
-Dsophora.auth.trusted.certificates.onlyDefines whether the certificate of the server should be checked or not. Note that the protocol HTTPS must be enabled on the server.
Possible values: true, false.
Default value: false
-Dsophora.auth.truststore.urlDefines the URL to the truststore.
The truststore must contain the certificates of the Certificate Authority which should be used to verify the certificate of the server.
Is only needed and considered when the certificate is checked
Possible values: Any valid url. E.g: file:/data/sophora/truststore.jks
Default value: none
-Dsophora.auth.truststore.passwordThe password for the truststore.
Possible values: Any String
Default value: none

Teletext / Texas

For the teletext component there are the following parameters configurable:

ParameterDescriptionExample
texas.config.uuidUUID of configuration XML file for Texas. This parameter is deprecated, use texas.config.externalId instead.63c48aed-484f-4355-a94f-0c02e945a939
texas.config.externalIdExternal ID of configuration XML file for Texastexasconfiguration or 951663af-814c-4175-8da6-8b40d544cb12
texas.config.propertyName of the property for binary data. Usually this is "sophora-content:binarydata"sophora-content:binarydata
texas.property.teaserWidthThe width of a teaser on story pages (has to fit to the index page). Default: 3533
texas.teaser.typeName of the default tag of the teaser structure in the template for index pages.index
texas.teaser.type.Name of the tag of the teaser structure in the template for certain sections.
For this key, the first value needs to be the name of the tag and the second is interpreted as UUID of the page section.
Key: texas.teaser.type.background
Values:
Background index
0acba9e5-2022-46cc-8094-ea193d2bf566
texas.storyElementNamesList of names of used story elements in the XML template. Default: shortstory, longstory 
texas.headlineElementNameName of the element within the XML template that contains the headline (has to be in the story element). Default: headline 
teletext.showEinsExtraSlotSwitchesShow the EinsExtra toggles (true or false)? Default is false 
teletext.showPage100TeaserWarningsShow warning for page 100 (true or false)? Default is false 

Tools

External websites or webapplications may be called from within the DeskClient using the main menu item Documents >> Tools. Such tools need to be announced in the configuration:

ParameterDescriptionExample
toolsList of (external) tools that should appear in the deskclient's main menu.
Format of this entry:
Name;URL
Tools can use special URIs to trigger actions in the DeskClient, e.g. to publish a document.
Channel overview;http://my.sophora-host:8082/system/channeloverview.jsp
Sending a telegram;https://mailer-service.de/userpages/10913/newsletter/?bc4d776fd428&action=telegram&
ParameterDescriptionExample
textlinkNodeTypeDocument type of link documentssophora-content-nt:link
textlinkUrlPropertyName of the URL property within link documentssophora:url

Copytext Editor

The behaviour of the copytext editor can be influenced in the following way:

ParameterDescriptionExample
textReplacementsList of characters that should be replaced when the user executes the "Clean Up" function on the copytext. You can use Unicode characters for special signs. Duplicated whitespace character are removed automatically and need not to be defined here.
Format of this entry:
targetCharacter=Replacement
Here, dashes are replaced by minus signs, several kinds of quotation marks are replaced by " and apostrophies are replaced by '
\u2013=-
\u201c="
\u201d="
\u201e="
\u201f="
\u00b4='
\u02b9='
\u0060='
\u2018='
\u2019='
\u201b='
\u2032='
\u2035='
document.markup.languages.backgroundDefines the background color of language markups. The value must be a valid color represented by its HEX String. If this key is not present or has an invalid configuration the default value (beige) is applied.#6600CC
document.markup.quote.backgroundDefines the background color of the quote markup. The value must be a valid color represented by its HEX String. If this key is not present or has an invalid configuration the default value (green) is applied.#FFCC00
document.markup.abbreviation.backgroundDefines the background color of the abreviation markup. The value must be a valid color represented by its HEX String. If this key is not present or has an invalid configuration the default value (purple) is applied.#00FF00
document.markup.anchor.backgroundDefines the background color of the anchor markup. The value must be a valid color represented by its HEX String. If this key is not present or has an invalid configuration the default value (sky blue) is applied.#87CEEB
document.markup.languages.selectvalue.externalidExternal ID of the select value which provides the list of languages for language markups. 
copytext.paragraphbox.labelSpecifies the label for paragraph groups displayed in the copytext statistic dialog. Default: "paragraph group" (englisch) / "Absatzgruppen" (german)."Container"

Concerning the search the following settings can be defined:

ParameterDescriptionExample
search.button.positionConfigures the position of the search button. By default the button will be in front of the text field. If set to right it will be positioned behind the text field. The default is left.
(Since 2.5.18)
left
search.modifiersList of customised search modifiers. These modifiers are available under the "Customised search modifiers" toggle button within the search view.

Format of this entry:
<Label>;<Search modifier>
The label is displayed in the menu of the toggle button in the search view.

Either XPath or Solr queries can be used as search modifier. XPath queries are marked with a leading § and Solr queries are marked with a leading $. By using a Solr query the Solr field names must be used instead of the property names.
XPath
Example 1:

All published videos;§[@sophora:state='published' and @jcr:primaryType='sophora-content-nt:video']

Example 2:

Videos and Audios;=video =audio

Solr
All published videos;$[sophora_state_s:published AND primaryType_s:sophora-content-nt\:video]
search.forceSolrIf the Solr search is enabled on the Sophora server and this setting has the value true, then the DeskClient will use the Solr search. This setting overrides the user preference 'Always run a JCR search'. The default value is false.true

Deprecated Categories

ParameterDescriptionExample
showDeprecatedCategoriesDefines whether the deprecated (old) categories should be shown. If the value is false, the enhanced categories are shown instead. Valid values are true and falseDefault value is true

EPG

ParameterDescriptionExample
sophora.epg.gap.backgroundDefines the background color of gaps in the schedule. The value must be a valid color represented by its HEX String. If this key is not present or has an invalid configuration the default value (red) is applied.#BFFF00
sophora.epg.template.delayWhen applying a program template, all the documents in the template are cloned and modified. To reduce the impact this might have on the server, a delay between cloning to documents may be specified using this property. The delay is in milliseconds. Use "0" to turn off the delay.500
sophora.epg.noTemplateLabelDefines the text that is shown in the template dropdown field when no template is selected. If not set, the default "(No template)" (or "(Kein Vorlage)" in German localization) is used.(Current schedule)

Linkchecker

The Linkchecker's configuration is explained within the Linkchecker documentation.

Mimetypes

Also located at the "Configuration" menu item, mimetypes are configured in a separate file. The usage of this document is analogous to the previously described configuration files.

Important Note
Please keep in mind that the mimetypes configuration document has to be published after modification. This is necessary because the mimentypes configuration affects the staging delivery.

Update-Keys

A document called Update-Keys can be found among the list of configuration documents. In contradiction to this, it is not intended for manual configuration and is maintained sophora internally.

Purpose

This document lists the keys of all sophora-internal updates performed on the sophora server or cluster the client is currently connected to. Under normal circumstances, this can safely be ignored. In cases however where an update (e.g. through the Deskclient) has not been performed properly it may be helpful to check the list of update keys contained here.

Important Note
Never modify this document unless you are asked to do so by the sophora support.

Search Result Order Options

The options how search results can be sorted in the search view are configured in the select value "Search Result Order". These options need to be defined as top level select values, with a value that defines the property and direction of sorting (e.g. "sophora:modificationDate descending" or "sophora-content:title ascending" in which 'ascending' is optional), and a name and icon that are displayed in the UI. If the special value "score" is set, the sorting is done by relevance. If a select value is set to default, this will be the default sort option for the first time the DeskClient is started. Otherwise the first select value is the default option. See the following screenshot.

Search results may also be sorted using Solr-only properties from the default index, which are not existing in the JCR repository (see the Solr Search guide for details on how custom Solr properties may be defined on the default index). For instance, a Solr-only property named specialProperty_s can be used as sort order as follows: $[specialProperty_s] descending.

Important Note
Sorting by Solr-only properties may only be used in combination with a Solr search. Thus, users must deselect the  'Always run a JCR search' user preference, or Solr searches must be enforced using search.forceSolr=true (see Search). However, customised search modifiers may still require a JCR query; when having selected a Solr-only search order in such a case, an error will be shown.

Paragraph Styles

Paragraph styles are used in Sophora's copytext editor. The interpretation of paragraph styles is configurable for the delivery.

Some examples:

  • Paragraph style "Pagebreak" creates a page break. Using this paragraph style, a document can be divided into multiple pages.
  • Paragraph style "Citation" may effect that a citation (this paragraph's content) is displayed highlighted somehow; e.g., in a box or in italic font.
  • Paragraph style "Line" creates a <hr> tag in the delivery.

Creating a new paragraph style

  1. Go to the paragraph style menu item, open its context menu and select "New Paragraph style".
  2. Thereupon, a dialog opens where you can provide an ID stem and select a structure node. By default, the system site is pre-selected and an ID stem is already proposed.
  3. Click on "Finish" and the editor opens with an empty form where you have to give the details of the new paragraph style.
  4. Finally, save the paragraph style.

Please note that a newly-created paragraph style must be configured in the configuration of a copytext field so that it can actually be used in that copytext field.

Editing an existing paragraph style

To edit an existing paragraph style expand the paragraph style menu item and doubleclick the desired paragraph style document. Modify the paragraph's details and save the changes.

Paragraph Style Properties

Each paragraph style must have a name and a label. Furthermore the appearance in the copytext editor can be configured by choosing an icon, display type and background color. Note that some display types like "html" or "pagebreak" have a default background color that is used if no color is specified. Finally it can be restricted whether text links, what kind of markups and box types are allowed in paragraphs of that type.

Paragraph Properties

You can also define Properties for each paragraph style. These will be shown in the component details view if you select a paragraph from the component structure. If you check "Inline paragraph fields" the properties will also be shown directly in the paragraph.
To do so you have to do the following steps:

Prepare the paragraph node type

  1. Open the "sophora-extension-nt:paragraph" nodetype.
  2. Put the "sophora-extension:paragraphProperties" child node on the components tab.
  3. Open the child node configuration of the child node and set "sophora-extension-mix:paragraphProperties" to be a valid child node type.

Create the property nodetype

  1. Create a new nodetype containing the properties which should be used for a paragraph style.
  2. Create a nodetype configuration for this nodetype and put the properties on the base tab.
  3. You may also configure a child node with the dynamic table input field type. Note that this child node will always be positioned at the end of the paragraph properties independent from the position in the tab configuration.
  4. Select "sophora-extension-mix:paragraphProperties" as mixin for this nodetype.

Configure property nodetypes for a paragraph style

  1. Open the paragraph style document for the paragraph style you wish to add paragraph properties to.
  2. Enter the nodetype name of your created property nodetype into the field "Nodetypes of the paragraph fields"
You can also define multiple nodetypes as property nodetypes for a paragraph style. If you do so avoid defining properties with the same name in different nodetypes which are used in the same paragraph style.

Markups

In the administration view it is possible to configure the languages and abbreviations that can be used as markup in the copytext.

Configuration of Languages

The markup languages are configured in a select value. The corresponding select value document is initially created by the server; it has the name Languages. Nonetheless, you can define another document to provide the markup language. To do so the configuration key document.markup.languages.selectvalue.externalid has to refer to the new language document (see the configuration properties table for the copytext). However, languages need to be defined as top level select values, with the international country code as the key and a meaningful name.

Configuration of Abbrevations

The abbreviations, which appear in the abbreviation dialogue when editing the copytext, are defined in a configuration document. This document is initially created by the server. It has the name Abbreviations. To create an abbreviation it is necessary to create an entry in the configuration table. The key is the abbreviation and the value is the correspondent of the abbreviation. To define an abbreviation with more than one correspondent just create an entry with more than one value.

Flexible Tabs

It is possible to configure the displayed tabs for each document editor individually. This is done by creating tab documents. By default, there are the tab documents "Base" and "Metadata".

Adding a new tab:

  1. Open the context menu in the administrator view and select "New: Tab".
  2. A dialog for tab creation opens. Here, you can select a structure node for localization and enter an ID-stem for the tab.
  3. Clicking on "finish" opens an empty form for tabs. Here, you can set up the properties for the new tab.
  4. Save the new tab.

The label parameter display name of a tab that is shown in the document editors of the configured document types. The internal name needs to be unique and must not be changed since it is used internally to represent this tab in the node type configurations. If the internal is changed anyway, this tab is considered as newly created and the legacy configuration will be dismissed. The state of a tab document is irrelevant. By default each newly created tab is assigned to all existing document types. Deselect the types you do not want the new tab to be displayed in the according document editor.

Tab Types

A tab is either of the type "form" or "browser". These types are defined by the select value "Type".

Form Tabs

Form tabs are shown in the node type configurations so that you can assign arbitrary properties and childnodes to be shown on these tabs.

Browser Tabs

A browser tab is used to display a website within a document editor. The website's address has to be given in the URL field within the corresponding tab document. Within browser tabs neither properties nor childnodes can be displayed. If the website requires login credentials it is possible to add the username and passwort for automatic login within the deskclient.

Dynamic URLs

It is possible to insert a placeholder in the configured URL of a browser tab, which is  filled dynamically with the values of the configured properties of each document type this tab is configured for.

An example:
URL: www.google.de/#hl=de&source=hp&q=${sophora:id}+${sophora-content:tags}
Such URL initiates a Google search with document's Sophora-ID and tags.

The notation of the placeholder is ${<PropertyName>}. If the given property does not exist in the document, the placeholder will be removed from the URL automatically. All kinds of property types may be referenced here except for binary and multi-value properties. Childnodes cannot be used.

Special cases:

  • $PREVIEW_BASE_URL at the start of the URL is replaced by the value of the configuration property sophora.previewBaseUrl. This property can be set in the sophora.properties file of the server.
  • A document's UUID can be used by ${uuid}
  • The document's delivery URL can be output by ${documentUrl}. This requires to have set the matching site URL in the site configuration, and to have at least one configured delivery in the Sophora Staging Slave Server. For more information on how to configure connected deliveries of a Sophora Server, please refer to the Server documentation under the section "Configuring the Sophora Server" > "Configuration Parameters of the sophora.properties File" > "Configuring connected deliveries of a Sophora (Staging) Server".
  • The node type of a document can be obtained by ${jcr:primaryType}
  • The name of the site can be obtained by ${site} (the UUID of the site can be accessed directly by the property ${sophora:site}).
  • The path of the structure node after the site can be obtained by ${structurePath}. For the full path you have to prepend a slash and ${site}: /${site}${structurePath}!
  • The username of the current user by ${username}
  • The firstname and the surname of the current user by ${userDisplayName}
  • For date properties you can define the output format. The notation is ${<PropertyName>;<DateFormat>}; e.g., ${sophora:date;dd.MM.yyyy HH:mm:ss}. If the given date format in the placeholder is either omitted or invalid, the default format yyyy-mm-dd HH:mm:ss is applied automatically.

Within the date specification the following symbols may be used:

SymbolDescriptionExample
GEra designatorAD
yyYear (two-digit)9
yyyyYear (four-digit)2009
MMonth in year7
MMMonth in year (two-digit)7
MMMMonth in year (short)Sep
MMMMMonth in year (long)September
dDay in month26
hHour (1--12)9
HHour in day (0--23)0
mMinute13
sSecond22
SMillisecond257
EDay in week (short)We
EEEEDay in week (long)Wednesday
DDay in year304
FDay in week in month3
wWeek in year12
WWeek in month3
aAm/pm markerAM
kHour in day (1--24)24
KHour (0—11)0
zTime zoneGMT+02:00
ZTime zone (RFC 822)200
'Character for unhandled textHello World!
'Single apostrophe'

Positioning of Tabs

The configured tabs are always shown on the left side of the tab bar within the document editor. The order of the tabs can be controlled by the field "Position". It may contain the relative position at which the tab is displayed (relative to the other configurable tabs). If two tabs have the same position value, they are sorted alphabetically according to their labels. A tab's position can only be arranged within the set of configurable tabs (those having their own tab document). Non-configurable tabs are always displayed to the right of the configurable tabs.

Visibility of Tabs

The field "Document Types" manages in which document editors a tab is visible. Thereby, you can hide tabs from certain document types.

Note
When creating a new node type configuration for a document type, you need to specify the visibility of all existing tabs before creating the actual configuration (a dialog will pop up and ask you to do so). By that, you do not have to modify the visibility of all existing tab documents after creating a new document type.

The visibility of tabs is also restricted by the tab permissions the user has. If a user has read and edit permissions for a tab, he can see the tab and edit the tab contents. With only read permission, the user can see the tab, but not edit its content. Note that browser tabs make no distinction between read and edit permissions. If a user does not have read permission for a tab, the tab is hidden, i.e. not shown along with the other tabs at the bottom of the document editor.

Configuration of Tabs

Form tabs appear in the node type configuration of document types for which the tabs are visible. On these tabs you can configure properties and childnodes freely.

Deleting Tabs

Removing Tab Documents
Do not delete the base or metadata tab unless you are exactly aware of the consequences.

When a tab document is deleted, all properties and childnodes, which have been located on this very tab, are automatically moved to the system tab. The first time the node type configuration of a concerned document type is entered afterwards, the user will be informed about this incident in a separate dialog. This confirmed when saving the configuration (otherwise it would pop up the next time someone opens this configuration).

If all tab documents have been removed so that no form tab is available anymore, both base and metadata tab are shown automatically since otherwise there won't be a possibility to create new tab documents.

Proposal Sections

Documents may be proposed to other users. Such proposals are organised in proposal sections. These sections need to be created and configured at first. Proposal sections are organised in hierarchies so that one section can have (multiple) subordinate proposal sections.

Creating a new proposal section on top level:

  1. Go to the proposal section menu item, open its context menu and select "New Proposal section".
  2. Thereupon, an empty form opens where you can define the proposal sections name.
  3. Finally, save the proposal section.

Adding a new proposal section to an existing one/creating a subordinate section:

  1. Expand the proposal section menu item and select the prospective parent section.
  2. Open the proposal section's context menu with a right-click and select "New Proposal section".
  3. Thereupon, an empty form opens where you can define the proposal sections name.
  4. Finally, save the proposal section.

To edit an existing proposal section expand the proposal section menu item and doubleclick the desired proposal section. Modify the section's name and save the changes.

XML Feeds

For details about configuring and using XML feed subscriptions and importing XML feed items consult the add-on's documentation: Feed-Manager.

Channels

Sophora can deliver documents through different channels. A channel has a name and a description that can be displayed to the user. A channel can be enabled or disabled for certain document types as well as for entire sites. If a channel is activated for a site and a document type, the channel is generally available for this combination. Whether the channel is enabled by default for documents of the given type in the given site, is configured in the structure node configuration.

Creating a new channel:

  1. Go to the channel menu item, open its context menu and select "New: Channel".
  2. Thereupon, a dialog opens where you can provide an ID stem and select a structure node. By default, the system site is pre-selected and an ID stem is already proposed.
  3. Click on "Finish" and the editor opens with an empty form where you have to specify the details of the new channel.
  4. Finally, save the channel document.

To edit an existing channel expand the channel menu item and doubleclick the desired channel document. Modify the channel's details and save the changes.

New Image - Multiupload

On the final page, in the "New Image Wizard" with previous checkbox "Create multiple image documents" selected, you have to fill in the mandatory fields.
These values are used for each image document to be created.

These fields are defined in the node type sophora-extension-nt:Image.
If these node type has a variant with the name multiupload, then this fields from the base tab are choosen instead.

Image Variants

Images are usually necessitated in different variantes; i.e. in different sizes. Therefore, Sophora allows to specify customised image variants where users may select relevant and/or desired clippings.

Creating image variants:

  1. Go to the image variants menu item, open its context menu and select "New: Image Variant".
  2. Thereupon, a dialog opens where you can provide an ID stem and select a structure node. By default, the system site is pre-selected and an ID stem is already proposed.
  3. Click on "Finish" and the editor opens with an empty form where you have to specify the details of the image variant.
  4. Finally, save the image variant document.

To edit an existing image variant expand the image variants item and doubleclick the desired image variant document. Modify the variant's details and save the changes.

An image variant contains the following parameters:

  • an internal name
  • a label for displaying
  • a boolean value defining whether this variant is subject to an additional (and stronger) restriction. By default, when saving or opening an image variant as well as when uploading a new original, variants are only disabled automatically, if their size exceeds the size of the original. If enabled the parameter "Disable if aspect ratio not equal to original" ensures that a variant is disabled automatically, if its aspect ratio is unequal to the original's aspect ratio. This means that for such a variant an image clipping can neither be selected by the system nor can it be set by a user. Enabling this parameter is useful, if you require a certain format, e.g. landscape, and it is likely that the automatically selected image clippings are not satisfactory (may be because the original's aspect ratio is totally different to the one of this variant).
  • the size (given in its height and width in pixels)
  • a boolean value specifying whether this variant is the smallest allowed for all images. In the image editor, no image variant can be made smaller than this one, if multiple are selected.
  • a boolean value defining whether this variants images should be scaled down automatically. Force auto scale is useful for the original image variant to control the image size and it's useful for other image variants to control the size of manual added images. For example, if an (original) image variant has a defined width of 100 pixels without a defined height and an image with more than 100 pixel width is set as the (original) image variant, then the (original) image will be scaled to 100 pixel width, if "Force auto scale" is active, otherwise the size is unchanged. Force auto scale works for the multi image upload, changing the original image or an image variant and also for importing image documents.
  • a maximum size in MB for binary data that is uploaded for this variant. The defined byte size limit does not apply for generated variants based on the original!
  • JPEG compression ratio (range: 1-100) – this values is taken as default; it may be overwritten in each image document for this variant.
  • the image sharpness (range: 0-100) – this values is taken as default; it may be overwritten in each image document for this variant.

Image variants within Sophora's image editor:

Changing multiple image clipping areas at once can be done via selecting the checkbox Show only one variant per ratio. In the picture above are 2 image variants with the aspect ratio 1:1. Selecting them and changing the image clipping will affect both image variants clipping area. Very useful if the image variant sizes for e.g. are 100 x 100, 200 x 200 and 350 x 350; recorgnize that for this example the original image must have the minimum size of 350 x 350.

Status and Sorting of Image Variants

If an image variant should be used within a website, it has to be enabled for this site at first. This can be done in the website's editor (which is available from the structure tree view). Enabled variants are shown in all image documents located at this website and disabled variants are hidden (invisible). Additionally, there are "related" image variants which are visible in this site but not used in its delivery. Such related variants are relevant when an image document is used in a different context than the parent website where the related variant is required. By default, related image variants are not visible in image documents. They can be displayed by checking the according box above the variants table on the base tab of the documents. On the variants tab, related image variants are displayed.

The order in which the image variants are shown in the image documents (on the base and on the variants tab) can be arranged in the website's editor using the arrow buttons on left side of the image variants table.

Automatically Downscaling Oversize Images on Upload

In order to prevent unnecessary image data filling up the repository, Sophora provides a mechanism for very large images to be resized to a pre-set maximum size on upload (The whole process is optional, prompting the user to decide on each upload whether an image should be scaled down or uploaded in full size). To enable the automatic downscaling, the maximum height and width of images can be specified via the height and width properties in the "original" image variant. For the downscaling of jpeg pictures, a compression ratio will be used. The default setting of 75 can be overridden by the property image.autoscale.jpegCompressionRatio in the configuration.

Redirects

You can define redirections for the webapp, so that requests to specific paths are redirected to other locations. These locations include documents, urls relative to your website, and external urls. There are four different types of redirects that can be configured via redirect documents in the admin view. These are: REDIRECT, METAREDIRECT, SSI and MAPPING.

Prerequisites

In order for the redirects to work, a template for the nodetype sophora-nt:shortcut must be configured in the delivery webapp. See the Delivery Documentation for details.
Additionally, all redirect types you want to use must be added to the SelectValue document for redirect types (usually 'redirecttypes100').

Types of redirects:

  • METAREDIRECT
  • This embedded in the header of the html ("meta refresh"), and redirects to a specific document relative path or external url.
  • SSI (Preserve path)
  • This redirect maintains the same url while loading content from a specific document or relative path.
  • MAPPING
  • This redirect maps the request to a different relative path. This way, content can be requests for content in a non existent structure node or path are redirected to an existing structure node, where the content can be found. This type is comparable to structure node aliases, with the exception, that mapping redirects are not considered when generating document urls, whereas structurenode aliases are considered.
  • REDIRECT (Redirect)
  • This redirect is sent to the client via the http response and redirects to a specific document, relative path or external url. It is not recommended to use this type of redirect, unless there is a good reason to do so. METAREDIRECT should be used instead, since it is easier to implement and redirects get cached.
Note that a Selectvalue with the corresponding values must be configured.
The value of such a Selectvalue must be either METAREDIRECT, SSI, MAPPING or REDIRECT.

Creating a redirect document:

  1. Go to the redirect document menu item, open its context menu and select "New: Redirect document".
  2. Thereupon, a dialog opens where you can provide an ID stem and select a structure node. By default, the system site is pre-selected and an ID stem is already proposed.
  3. Click on "Finish" and the editor opens with an empty form where you can specify several redirections in the table.
  4. When you are done, save the redirect document.
  5. In order for the redirects to become active, the redirect document must be published.

Redirections of type "Redirect" require an arbitrary URL as argument in the column "Forward to URL". Redirections of type "Preserve Path" only accept another Sophora document. Therefore, you can drag and drop the target document into the column "Forward to Sophora document".

Within the column "Request path" you can specify multiple values to be redirected to either the given URL or the Sophora document (dependent on the redirection type). By that, you can define different paths to be redirected to one target. In addition, you can configure a regular expression like /demosite/inland.*.

You can set different channel names for the same redirection path in order to indicate different targets. If no channel name is set, the default channel will be used.
Remember that it is necessary to define a template set in the template.xml for the specified channel and the shortcut.jsp. Please refer the Sophora Delivery documentation for this concern.

Within the column "Comment" you can leave a comment on a redirect for informational purposes.

Structure Nodes Only
Note that you can only define redirections for structure nodes but not for single documents.

If there are multiple redirections defined for an individual path, they are a prioritised as the given order in the table. However, redirections, that have been defined via such redirect documents from within the deskclient, are preferred to those defined in the templates.xml in the delivery.

To edit existing redirections expand the redirect document item and doubleclick the desired redirect document. Modify the redirections, save the changes and publish the document.

Dictionaries

The DeskClient includes two dictionaries as standard - the "default" dictionary and an additional dictionary called "user". In the "user" dictionary, the words added by editorial journalists within the copytext editor are stored. The resulting dictionary is a combination of the default and the user dictionary. In addition to adding words to the dictionary via the context menu, you can also upload an already existing dictionary.

Uploading a dictionary:

  1. Expand the menu item "Dictionaries".
  2. Doubleclick "default"
  3. Press "Search..." and select a dictionary file in Sophora format (that is a simple text file – UTF-8 encoded – containing each individual word in a separate line).
  4. Save the dictionary.
Please note that uploading a new dictionary takes effect only after restarting the DeskClient.

Exporting Dictionaries

Exporting a dictionary

  1. Expand the menu item "Dictionaries".
  2. Mark the desired dictionary and open its context menu with a right-click.
  3. Select "Export...".
  4. Specify the target file's full path as well as its name.
  5. Start the export by clicking "Finish".

Dictionaries are stored as UTF-8 encoded text files. The can be uploaded as described in the previous section.

Previews

Multiple previews can be configured for the system using preview documents. Each preview document contains an URL pointing to the implementation of the preview.

To create a preview document:

  1. Open the administrator view, select the item "Previews".
  2. Open the context menu and select "New: Preview".
  3. The document creation dialog opens. Select a structure node for the preview (usually /system) and an id stem.
  4. Set up the properties of the new preview document.
  5. Save the preview document.

A preview document has the following fields:

FieldDescription
NameThe name of the preview is shown in the drop-down menu of the address bar in the preview view and in the menu of the preview toolbar button.
URLThis is the URL of the preview service. When a preview is shown for a document, the sophora-id of the document will be appended to this URL.
Example:
http://master.example.com/mysite/system/preview.jsp?sophoraid=
Default previewMarks this preview as the default preview.
Some functionality in the DeskClient, such as the "Print document" action or the "Overview" tab, use the preview behind the scenes. If multiple previews are available for the current document, the first default preview is used. A default preview doesn't need a separate position (see "Separate position" below) since the preview button in the toolbar already opens the default preview.
User name for URLIf the preview website is password protected you can enter the user name here. This is required for the live preview to work correctly!
Password for URLIf the preview website is password protected you can enter the password for the user name above here. This is required for the live preview to work correctly!
OrderDetermines the order of the previews in toolbar and (context) menus. Valid values are positive and negative integers. Previews with equal values will be sorted alphabetically by their name. (since server version 2.5.16)
Separate positionSpecifies if the preview will be placed as a separate icon in the toolbar and context menu. (since server version 2.5.16)
Node typesThe preview will only be available for these node types.
Web sitesThe preview will only be available for documents located at the selected sites.
The preview URL can contain placeholders the same way URLs in tab documents can.

Personalized Preview URLs

For each preview document, the preview URL can be customized for each user in the user editor. This is intended for users working at remote sites, who need to use a different URL to access the preview server than users working at the main office.

Preview Tooltips

The DeskClient is able to show custom HTML tooltips for documents of specified types. This might be useful to show the video of a video document inside its tooltip or have an audio player in the tooltip of audio documents.

Preview Tooltips

These HTML tooltips are generated by the preview delivery by calling the preview URL for the document with the special template type "sophoraTooltip", e.g.

http://mypreviewserver:8080/sophora-demosite/demosite/system/preview.jsp?sophoraid=fashionshow102&type=sophoraTooltip

To configure those tooltips in your system you have to

  • check the "HTML Tooltips" checkbox in the node type configuration of your document type, e.g. "sophora-content-nt:video"
  • create a JSP template in the preview delivery that renders the HTML tooltip. The JSP has to be configured in the templates.xml for the template type "sophoraTooltip" of your document type, e.g. "sophora-content-nt:video"
<nodetype name="sophora-content-nt:video">
	<templateset extends="default">
		<template type="default">/demosite/templates/media.jsp</template>
		<template type="sophoraTooltip">/demosite/templates/mediatooltip.jsp</template>
	</templateset>
</nodetype>
  • At least your preview.jsp has to delegate the template type parameter to the templates.xml mechanism:
<sc:createLink sophoraId="${param.sophoraid}" urlOnly="true" var="redirectUrl" templateType="${param.type}"/>

Work Environments

You can configure default settings for the DeskClient. This settings are assigned to roles. If a user has one or multiple roles with several assigned work environments, the work environment with the highest priority is taken.

Currently the settings you can define are the perspective (window layout), a start search of the DeskClient and the available search options in the DeskClient Search.

If a user has a role with work environments his default perspective and start search will be taken from that role. This means that the pre-defined perspective and search will be used instead of the default settings for the first start. Also if he uses 'Restore default window layout' the DeskClient will be restored to the perspective stored in his role. The start search will be performed each time the user launches the DeskClient or reopens the search view unless he has defined his own start search.

Creating default perspectives

You can capture your current perspective and save it in a work environment document. Afterwards you can assign your settings to a role.

  1. Create a fresh perspective. Ensure that you start the DeskClient with an admin user that has no perspective assigned by a role and choose "Restore default work environment" in the 'User' menu.
  2. Arrange the views to layout the perspective.
  3. Select 'Store window layout in work environment...' from the 'User' menu.
  4. Select one of the existing work environments or enter a new name in the appeared dialog. If you wish, the changed settings can be published immediately so that they can directly be used. For that click the checkbox 'Publish?'. Otherwise you have to publish the work environment document later to be able to assign it to a role.
  5. To assign settings to a role you have to open the desired role. Next, select your published settings under 'Work Environments' in the role editor . Finally, save the role.

Creating start searches

Analogously to creating default perspectives you can perform a search in the DeskClient's search view and save it in a work environment document. Afterwards you can assign your settings to a role.

  1. Select 'Save current search in work environment' from the 'Saved searches' dropdown menu in the search view.
  2. You can select one of the existing work environments or enter a new name. If you wish, the changed settings can be published immediately so that they can directly be used. For that click the checkbox 'Publish?'. Otherwise you have to publish the work environment document later to be able to assign it to a role.
  3. To assign settings to a role you have to open the desired role. Next, select your published settings under 'Work Environments' in the role editor . Finally, save the role.

By default the DeskClient Search has many toolbar actions and search options. This may confuse users who will never need all these buttons.

Vollständige Suchoptionen

To reduce the number of buttons, the available toolbar actions and search options for a role can be configured in its work environments. Since the document type and category search buttons may appear several times these numbers can be configured, too. The order of the buttons is configured by the corresponding select values "Search actions" and "Search options". Do not forget to publish the Select values and work environments after changing them.

A possible search may look like this:

Angepasste Suchoptionen

This is the DeskClient Setting for the Search above:

Arbeitsumgebung

Configuring Opening Editor Tabs

You can configure the opening editor tabs for any document type for a particular work environment.

For example, a work environment may specify that image documents should open with the "Variants" tab initially instead of the default. Users using this work environment will see the "Variants" tab first, while other users will see the default tab.

To configure a non-default opening editor tab for a document type, enter the node type name (for example, "sophora-content-nt:story") and select an editor tab from the list.