6.2Configuring the cmsWorks desktop in JavaScript

« previous chapternext chapter »

The cmsWorks editors desktop needs to be configured adjusting input fields for documenttypes, declaring which document types result in web pages to be previewable, to configure all features of richtext fields, to spread ContentScripts to support content managing and more.

The location of the configuration is

<cmsWorks-installdir>/htdocs/webui/cmsdesk.custom/<myCustomerName>/q-custom.js

The target is to create a JSON structure with configuration information but also not to be restricted to simple JSON. So this file also enables to process Javascript for dynamic configuration if needed.

The basic structure of the q-custom.js - file looks like this:

var customer_modification = {
  "documenttypeicon":{}, // Document type icons
  "desktopBackground": {}, // Background color and/or default background image
  "generatorPrefixes": [], // URL prefixes to be ignored when searching documents from URLs
  "no-preview-doctype": [], // Document types having no preview
  "tooltip-field": {}, // Field content for a tooltip of a document
  "documentpropertiespicture":[], // Listing picture properties for picture search
  "searchpictures": {}, // Configuring picture search
  "richtext": {}, // Richtext
  "contentscript": [], // Listing ContentScripts and assigning context and privileges
  "extwin": [], // External pages as native cmsWorks desktop window
  "document":{} // Configuring each field of each document type if needed
}

The configuration sections are described below.

documenttypeicon - Document type icons

Document type icons are used beside the window title of documents or in document lists. You may configure these icons for each document type of your CMS document type model. We assume we have the document types "medium", "article", "category", configtask", example:

"documenttypeicon": {
  "medium" : "/doctypeicons/icn-resTypeMedium.png", /* for the document type with database name "medium" */
  "article" : "/doctypeicons/icn-resTypePage.png",
  "category" : "/doctypeicons/icn-resTypeCategory.png",
  "configtask" : "/doctypeicons/icn-resTypeConfigtask.png"
}

The location of the directory "doctypeicons" is right next to the q-custom.js file.

This entry is optional.

desktopBackground - Desktop background color / image

Just for the visual effect a default start image or a default start background color can be configured. If a user enters the cmsWorks desktop for the first time these entries are used to make a first impression. The user can choose another background image from the Menu / Settings / Background or not but anyway his choise will be stored into the user settings and is used for any further cmsWorks desktop session.

"desktopBackground": {
  "backgroundColor": "#ccc",
  "backgroundPicture": "default.jpg",
  "showOptionNoPicture": true
},

The path of the backgroundPicture is relative to <cmsWorks-installdir>/htdocs/webui/cmsdesk.custom/<myCustomerName>/backgrounds/. Feel free to provide a wide choise of background pictures with any folder depth.

This entry is optional.

generatorPrefixes - URL prefixes to be ignored when searching documents from URLs

A generator can have configured a prefix used in every URL this generator creates or interprets. To support finding a Document when putting a URL into the search input field, a configured generator URL prefix should be ignored.

The property generatorPrefixes lists all prefixes that are used by Generators of this project.

"generatorPrefixes": ["dyn", "syn"]

Just use the prefix name, not using the /.

This entry is optional.

no-preview-doctype - Document types having no preview

This is a list of all document types you must not call a preview for, so to say "nonvisual" document types. In the example above this would be the document types category and configtask, example:

"no-preview-doctype": [
  "category",
  "configtask"
]

If a preview is called for a document that has no preview page an error page from the preview will be called with a rather technical error message only developers will understand properly. If this document type is declared as a no-preview-doctype a warning message "No preview available" appears in the cmsWorks editors desktop.

This entry is optional.

tooltip-field - Field content for a tooltip of a document

"tooltip-field" : {
  "article":"headline",
  "person":"name",
  "container":"type"
},

The property tooltip-field assigns for a document type the field containing a key information about the document. That fields content is presented in a tooltip about a document within the explorer document list or any other document list like link lists or search results. So without opening the document an additional glimps of the content is presented.

This entry is optional.

documentpropertiespicture - Listing picture properties for picture search

This special configuration for a document type containing a blob input field. When uploading a picture the input field itself read the dimension and uses this entry to fill the assigned input fields for with and height if this is configured here.

Also this configuration supports the window "Picture search" enabling the search for dimensions.

documentpropertiespicture: [
  {type: "medium", blob: "data", width: "width", height: "height"}
],

One entry of the configuration contains an object with the properties

type - the document type containing a blob field
blob - the field name of the blob field of this document type
width - the field name of the width field of this document type
height - the field of the height field of this document type

This field is mandatory but may be empty.

searchpictures - Configuring picture search

In this section the behavor of the Serarch pictures window is configured. Currently there is only one entry that is used: dimensionsoffer.

Filling this property a dropdown appears containing default dimensions for pictures to be searched.

searchpictures: {
  dimensionsoffer: [
    [-1,-1, "empty"],
    [1600,-1, "1600"],
    [1200,-1, "1200"]
  ]
},

One entry is filled with width, height, label. If a width value is -1 it means that the width will not be checked. If a height value is -1 it means that the height of the found picture is not checked. If both values are -1 it means any dimension is accepted.

This entry is optional.

richtext - Richtext

the property richtext combines the default configuration of link types and the default TinyMCE configuration.

"richtext": [
  "linkTypes": [
    [0,"Standard"],
    [1,"New window"]
  ],
  "tinymce": {...},
  "components": true,
  "componenttypes" : {
    "m":getLang("Centered"),
    "i":getLang("Inline"),
    "l":getLang("Left"),
    "r":getLang("Right")
  }
]

The linkTypes section list fills a selectbox in the link dialog for links within the richtext. The link in the richtext is not the standard HTML link, it's filled with more properties like internal document id to another cmsWorks document or an external URL and the link type id. So the generator can decide how to create an URL to the targeted document depending on the link type. For example if the type 1 is set for "New window" the generator link creation process could add a property target="_blank".

The property tinymce is filled with a complex set of properties configuring TinyMCE and is described in a separate chapter .

The property components enables the placement of text components in the text (only if the plugin and tooltip entries are filled).

The property componenttypes fills a set of options for the component positioning. The key references the translated label.

This entry is optional. There is a fallback basic configuration if this entry is missing.

contentscript - Configuring ContentScripts

ContentScripts are self-programmed workflows which can be executed within the the cmsWorks desktop. A ContentScript

has a corresponding JSP in the ContentScript server
may be restricted by user names, user group names or privileges like 'admin' or 'manageUsersGroups'
works in a context "resource" (works only on documents optionally restricted to special document types), "folder" (works only on folders) or "global"
can have an initial width / height definition

Example configurations for the (yet imaginary) ContentScripts scriptcreatearticle.jsp, scripthandlehttps.jsp, scriptchangefolder.jsp and scriptaddarticleheadline.jsp (the properties title, name and context are mandatory):

"contentscript": [
  {
    "title": "Create an article", /* this is the visible title of the ContentScript in the editors desktop */
    "name": "createarticle", /* createarticle as in "scriptcreatearticle.jsp" */
    "context": "global"
  },
  {
    "title": "Handle some https stuff",
    "name": "handlehttps",
    "visibilityRestriction": {
      "userGroups": [],
      "users":      [],
      "privileges": ["admin"] // only for users belonging to a group with the Administration privilege selected.
    },
    "context": "global",
    "appearance": { "width": 750, "height": 500 } /* set an initial width and height for the ContentScript window*/
  },
  {
    "title": "Change the folder",
    "name": "changefolder",
    "context": "folder"
  },
  {
    "title: "Add an article headline",
    "name: "addarticleheadline",
    "context: "resource",
    "contextDetail": { /* this ContentScript is only available for documents of type article or category*/
      "resourceType": [ "article", "category" ]
    }
  }
]

The script createarticle works global and not depending on a folder or document.
The script handlehttps may only be called by users of user groups having the privilege Administration checked and has a defined initial with and height when showing up the first time for a user.
The script changefolder only works on folders.
The script addarticleheadline only works on resources (documents) of type article or category.

With the configuration property visibilityRestriction the visibility/accessibility of the single ContentScript may be restricted to some users only. These users may be selected by login names, user groups or privileges of assigned user groups. The combination of all restriction entries are combined by OR. A user may see and use the ContentScript if their login name is listed or at least one of their assigned user groups and so on.

This entry is optional. If not filled the Menu entry "ContentScript" is simply not available.

extwin - External pages as native cmsWorks desktop window

Sometimes it's useful to integrate external web pages into the cmsWorks desktop as a window that is treated like all other windows, too. For that entries can be placed in the extwin list as the example shows:

"extwin": [
  {
    "title": "Home of the cmsWorks developers",
    "url: "https://www.itechworks.de/portal/index.html",
    "visibilityRestriction": {
      "userGroups": ["Editors"],
      "users":      [],
      "privileges": ["admin", "manageUsersGroups"]
    },
    "appearance": { "width": 980, "height": 700 }
  }
]

Setting an extwin like this, the line "Home of the cmsWorks developers" appears in the cmsWorks desktop main menu. You may create as many extwin entries as you need.

The property visibilityRestriction works similar to the one in the ContentScript section.

This entry is optional.

document - Property input fields of document types

In cmsWorks there are in general six types of properties that can be stored in a document type. They may be combined in any way needed and are described in the chapter about Document type management.

Having a new document type created you can configure the input fields using the q-custom.js - 'document' section. How to configure the different input fields is described in the next chapter.

This entry is optional.