cPath

cPath is used to traverse and identify content in Bases, similar to a file system path for folders and files, and XPath for the XML DOM. However, cPath has query and filter options not available with file paths, which are easier to learn than similar options in XPath.

Example

The following cPath will retrieve content in the /Users/John folder or any subfolders recursively where the content is an Image with a Width greater than 640.

/Users/John//[:Image AND Width>640]

Where to use cPath

cPath can be used throughout webCOMAND to access and select folders and content.

Navigation Bar - Use the "Edit cPath" option in the Title Bar of Content Manager and other apps.
Search Inputs - cPath filters are recognized in many app search inputs.
API App - Query content from cQuery tabs.
Content Type Field Location - cPath controls which objects can be selected for relationship fields.
cQL IN Clause - Limit the scope of a cQL query to content described by a cPath.
cScript - Query content from functions including: cpath, list, context and insert.
cTemplate - Query content from directives including: #CPATH, #LIST, #CONTEXT and #INSERT.

Expressions

A cPath expression traverses a content hierarchy and filters results along the way to produce a collection of content items.

Element Reference

Element	Description
n	OID - A simple number will match on the object with that OID.
nD	DOID - A simple number followed by a capital 'D' will match on the object with that DOID.
uuid	UUID - A UUID in canonical textual representation will match on the object with that UUID.
`/`	Root - When the first character of a cPath is a slash, it references the root folder. cPaths that reference the root folder with the first character are said to be "absolute paths" because they always start from the root folder and are not relative to the current object or folder.
`/`	Children - A single slash after a folder title will get the collection of content in that folder. In addition to Folder, other content types can implement the Parent interface to make a primary collection of child nodes accessible with a slash separator.
`//`	Recursive Children - A second slash after a Root or Children slash will also retrieve the children of all sub-folders, or sub-objects of the same content type that precedes the slashes.
`/.`	Self - Current cPath object(s) if a previous cPath element exists, otherwise the current object. When followed by a slash, it will refer to the children of the current object(s).
`/..`	Parent - Parent cPath collection or object if one exists, otherwise the primary parent folder for the current object(s).
`/!!`	Object Parent - Primary parent folder for the current object(s), even if a parent cPath element exists.
`/...`	Top Parent - The top-most parent object(s) in the hierarchy below the root, relative to the current cPath object(s).
`^`	Top - Remove everything before and including the ^ in the cPath. This is useful for "resetting" the cPath when appending to an existing cPath, like a Content Type Field Location.
`.`	Field Key - When followed by a field key, it refers to the corresponding field value for the current object(s). If the corresponding field does not exist for the current object(s), it is treated like NULL or an empty collection.
`"key or string"` `'key or string'`	Quotes - Single- or double-quotes indicate the enclosed text is an object key or string that may contain characters including white-space, a leading number or characters that otherwise have special meaning in cPath. Quotes inside the quotes of the same type must be escaped with a preceding backslash (ie. "This is \"quoted\""). Quoted text can be quoted by single or double-quotes, but must end with the same type of quote. Quotes are optional for an object key that starts with a letter and only contains letters and numbers.
`[n]`	Index - At any point in a cPath, results can be refined with an index. A single number will filter the cPath collection down to the object at that zero-based index. If the number is negative, it will filter the collection down to that number of objects from the end. If the index is out of range, it will result in an empty collection.
`[n..m]`	Range - At any point in a cPath, results can be refined with a range. A range is specified as [n..m], where n is the first element in the range and m is the last, and both are optional. If not specified, the first or last index will be used respectively. Each number is a zero-based index. If the number is negative, it represents an index from the end, where -1 is the second last element and so on. If indexes are out of range, they will be ignored and only the indexes within range will be used. The first index does not need to come before the last index in a range.
`[filter]`	Filter - At any point in a cPath, results can be refined with a filter. A filter is a query expression surrounded by open and close brackets.
`{cQL}`	cQL Clauses - A cQL SELECT Statement can be appended to a cPath to refine the resulting collection of objects.
@'revision'	Revisions - Perform a temporal query, based on a timestamp (e.g. '2020-04-30 13:03:23'), revision number (e.g. 123456), workflow state (Active, Draft, Working), or relative format (e.g. now, yesterday, '2 hours ago').

Hierarchy (slashes)

The content hierarchy is traversed with slash-notation. Slashes are used to drill down into the content hierarchy. If a collection precedes the slash, the collection will be searched for content with a key that matches what comes after the slash. If nothing proceeds the slash, the root collection will be searched.

If the key following a slash does not start with single- or double-quotes, it is assumed to be made up of alpha-numeric characters up to the next slash or dot character. If the key contains a slash or dot, or begins with a single- or double-quote, it should begin and end with single- or double-quotes. A backslash can be used to escape single- or double-quotes inside a quoted string. Double-quotes do not need to be escaped inside a single-quoted string and vice-versa.

Root - Every repository has one root object, which is at the top of the hierarchy. A cPath that begins with a slash will retrieve a collection of the root object's children.
Children - A single slash after a folder object will get the collection of objects in that folder. In addition to Folder, other content types can implement the Children interface to make a primary collection of child nodes accessible with a slash separator.
Recursive - A second slash after a Root or Children slash will also retrieve the children of all sub-folders, or sub-objects of the same content type that precedes the slashes.
"Related" - A third slash after a Children slash will retrieve the second parent from the top (just under the root) and all of its children recursively.

The following simple cPath is similar to a file system path. It will return the content identified by "cats.png" in the /Users/John folder.

/Users/John/"cats.png"

A slightly more interesting cPath will return content identified by "dogs.jpg" in the /Users/John folder and any of its sub-folders.

/Users/John//"dogs.jpg"

Self, Parent and Top-Parent (slash-dots)

A slash can be immediately followed by one, two or three dots to indicate the current object/collection, parent object/collection or top-most object/collection.

"Self" (/.) - Slash followed by a single dot references the current cPath collection or object.
"Parent" (/..) - Slash followed by two dots references the previous cPath collection or primary parent object.
"Top Parent" (/...) - Slash followed by three dots references the top-most parent object in the hierarchy below the root.

Each slash-dot elements works in two ways, depending on context. When they are the first element in a cPath or appear immediately after a ^ character, they refer to the object(s) primary parent folder. When anywhere else, they refer to the parent cPath element's object(s). This can be a subtle, but important distinction.

cPath expressions are used to limit the scope of objects available for selection in Content Type reference fields, through the Location field. They are processed relative to the object, therefore if dot-slash elements come first, they refer to the object(s) primary parent folder.

The following cPath references all folders in the Users folder.

/Users/John/../[:Folder]

Primary Parent Folder

Parent reference (aka "slash-dot") cPath elements sometimes refer to the primary parent folder. The primary parent folder is typically the object's only parent folder. However, it is possible for an object to exist in multiple folders. In those cases, the primary parent folder is the oldest folder the object was associated with. In other words, if an object is placed in folder A, and then later in folder B as well, the primary parent folder is A. If the object is later removed from folder A, and even later placed back in folder A, the primary parent folder is B, since it was subsequently removed from A before being placed back again. When it was removed from A, B became the primary parent folder and will remain so unless it is removed from folder B.

When an object is associated with multiple folders, the primary folder can be set in Content Manager by opening the object in Form View, selecting the Info Sidebar, expand and hover over the desired folder at the bottom and click the "make primary" action (check box) to the right.

Object Fields (dots)

Content type fields in an object also represent hierarchy. Fields are traversed with the dot-separator.

NOTE: Only content type fields are allowed at the end of a cPath expression. Data type and layout type fields will produce an error because they do not reference an object or collection. cPath can only resolve to an object or collection. To retrieve a single value from a data type field, use cQuery. Filters can reference data type fields though, to compare field values in an object or collection.

The following cPath traverses to a contact, then retrieves the contact's phone object through the Phone field, which contains a single phone number object.

/Contacts/John.Phone

Similar to the example above, the following cPath retrieves a collection of the contact's phone objects through the Phones field, which contains a list of phone number objects.

/Contacts/John.Phones

The following cPath is similar to the first hierarchy example above, except it uses long-hand dot-notation. This will work even if the content type does not implement the Children interface. It will also return the content identified by "cats.png" in the /Users/John folder.

/Users.Contents/John.Contents/"cats.png"

Filters (square brackets)

At any point in a cPath expression, results can be refined with conditions and indexes. Multiple filters can be chained together if desired.

Conditions

Any condition allowed in a cQL WHERE clause is allowed in a cPath filter, including attributes.

Additionally, a colon followed by a content type identifier can be used as shorthand for [Type.Identifier=Name].

/Users/John//[:Image]

Get a collection of Images in the /User/John folder and any of its sub-folders, which would include the results of the two preceeding examples.

/Users/John//[:Image]

Get the same collection as above, but refined down to images wider than 640 pixels.

/Users/John//[:Image AND Width>640]

A colon and content type identifier can optionally be followed by a plus symbol to specify a content type and any content types that extend it. This is the same as the Extends Suffix in the cQL FROM clause.

/Users/John//[:Image+]

Indexes

A zero-based index can be used to reference a specific object or range of objects in a collection, based on their position in the collection.

Get the first object in the John folder.

/Users/John//[0]

Get the last object in the John folder.

/Users/John//[-1]

Get the second through last object in the John folder.

/Users/John//[1..-1]

Chaining

Multiple filters can be provided back to back and will be processed in order. This is most useful when combining conditions and indexes.

Get the first Image in the John folder that is greater than 640 pixels wide.

/Users/John//[:Image AND Width>640][0]

cQL Clauses (curly brackets)

A cQL SELECT Statement can be appended to a cPath expression in curly brackets to refine the resulting collection of objects. All cQL clauses are accepted. However, the following clauses are most common.

/Users/John/"cats.png"{SELECT Filename ORDER BY Filename DESC LIMIT 10}

A cQL query can be specified in curly brackets, preceded by a cPath expression or not. For example, here is a valid cPath that has no cPath expression and only cQL clauses. This syntax can be used to effectively perform a cQL query anywhere cPath is accepted.

{SELECT Filename FROM Image ORDER BY Filename DESC LIMIT 10}

Fields

A cQL SELECT clause may be appended to a cPath expression to explicitly retrieve certain fields in the resulting collection of objects.

/Users/John/"cats.png"{SELECT Filename, Data AS Image}

Order

A cQL ORDER BY clause may be appended to a cPath expression to specify the order of objects in the resulting collection.

/Users/John/"cats.png"{ORDER BY Filename DESC, LENGTH(Data)}

Limit

A cQL LIMIT clause may be appended to a cPath expression to specify the offset and/or maximum number of objects to retrieve from the collection.

/Users/John/"cats.png"{LIMIT 10}

Namespaces (v4)

Similar to the cQL NAMESPACE clause, specifies the namespace of a content type. The NAMESPACE clause(s) must be specified before any cPath clauses.

{NAMESPACE io_comand_core}/Users/John/"cats.png"

Revisions

The '@' symbol followed by a transaction time will cause the cPath query to be performed as if it were processed at the transaction time, returning only content that existed at that point in time, and in the state that it existed at that point in time.

Example Timestamp

/Bases/Website/[:WebPage]@'2020-04-17 12:00:00'

Example Relative Format

/Bases/Website/[:WebPage]@yesterday

Example Revision Number

/Bases/Website/[:WebPage]@1234

For more information, see Temporal Queries.