Please help us by completing this survey

Go to survey
Documentation

Docs / Guides / Content Naming

Content Naming

In the sensenet Content Repository every Content has a Name Field that together with its location identifies the Content. The Content Name is part of the Content Path, and since the path can be used to address the Content via url, there are certain restrictions against the Name. The Content in the Repository also have a DisplayName that is the user-friendly human readable name of Content and can contain any kind of characters without restrictions. This article summarizes the connection between these two fields and other common aspects of Content naming.

If you are interested in customizing how the name of a downloaded file looks like, please check out the Document binary provider article for developers.

Name and DisplayName

All content in the sensenet Content Repository is identified by the following Fields:

Field Description Example
Name identifier of the Content Examples-tutorials
Path link to the Content in Content Repository /Root/DemoContents/Examples-tutorials
DisplayName a legible name of the Content for better human readability Examples & tutorials

The Name is the main identifier of the Content. Its value is also included in the Path property which acts as a permalink to the Content. Thus changing a Content’s Name (aka. renaming a Content) also changes the Path and therefore renaming operations should be carried out carefully. A path change may result in a lengthy operation (paths of child content are also changed respectively) and may also result in broken links in the Content Repository (if another content refers to the changed one through its path - e.g. an article containing a link in its text). These two properties are used when the Content is referred to via a url link and therefore may not contain special characters.

Do not worry about referenced content: those are connected by content ids instead of paths, so renaming a referenced content will not brake reference fields.

The DisplayName is the main display name of the Content. It acts as a legible, human readable name and may contain punctuations and accented characters as well. Generally, when a Content is displayed on the front-end of the portal, the value of the DisplayName property is shown. Changing the DisplayName is a simple operation and does not cause broken links (because changing only the DisplayName does not change the Url Name).

Naming conventions of different types

Although all content types contain the 3 properties above there are some special cases when the Name or DisplayName of a Content is not shown when editing or browsing a Content. The following table shows the different types:

Type Name and DisplayName importance Description Example Content Types
File only Name is important The File types are identified by their file names in general file systems. When a Content of this naming type is uploaded the Name will act as its file name. When listing this Content the value of its Name will be shown. The path of the Content that acts as a permalink will also contain the file name. A simple .txt file for example does not have a legible DisplayName, only a file name (Name in sensenet Content Repository). File, Image
Item only DisplayName is important The Item types are Content that are created frequently but permalinks to the Content are rarely used. When a Content of this type is created only the human readable DisplayName is specified and the Name is auto-generated (sometimes a Guid or a contenttype-date value). A memo or a meeting request for example has a subject (the DisplayName will act as a legible subject in this case) but its Name or the permalink to the Content is indifferent. Memo, Comment
Regular both Name and DisplayName are important The Regular types are Content that have a legible DisplayName and they also act as common links and organizing units in the Content Repository - therefore their Name is also important. An Organizational Unit for example has a legible DisplayName (like 'Marketing department') and also acts as an organizing folder with identifiable permalink (like '/Root/IMS/marketing-department'). The Name appears in its children content's permalink (like '/Root/IMS/marketing-department/exampleuser') Folder, OrganizationalUnit

Content naming on surface

For the Name and DisplayName Fields come two special Field Controls that provide the users handy interfaces to set the Names and DisplayNames of Content: the Name Field Control and the DisplayName Field Control. In situations where both or only the DisplayName is visible by default the Name is automatically generated from the DisplayName typed in by the user. The following screenshot shows the general layout of the two controls in a common scenario:

The user always has the possibility to change the Name by clicking the pencil to switch the Name Field Control to edit mode:

Automatic name generation

Since it can be very time consuming to provide a Name and a DisplayName for a Content at the same time - especially in cases when the Name can be derived from the DisplayName - sensenet provides automatic name generation mechanisms both on client and on server side. A Name can always be automatically generated from a given DisplayName by encoding or removing invalid characters. When the Content is created using a Content View name generation is done using two special Field Controls: the Name Field Control and the DisplayName Field Control.

Content naming behavior is customizable. Please check out the ContentNamingProvider article (for developers) that describe the built-in naming providers and other details.

Autonaming on client side

The DisplayName Field Control automatically fills the value of the Name Field Control visible in the same Content View, from the value entered to the DisplayName Field Control. The entered DisplayName is processed so that invalid characters are encoded - the resulting string will be the automatically created Name for the Content. The Name however does not change automatically in the following cases:

Autonaming on server side

In case no Name Field Control is visible in the same Content View, the Name for the Content is automatically generated from the entered DisplayName on the server side, using the same algorithm to generate the Name as on client side.

Rename and autoname

Generally speaking it is not desired to change the Name of a Content automatically when changing its DisplayName as it would be considered renaming of the Content, and would possibly cause broken links (since the Name is part of the Path that also acts as a permalink to the Content). Therefore the following rules apply to Name autogeneration:

Configuration of autonaming

You can fine-adjust autonaming with the contentNaming section in the web.config:

 <sensenet>
    <contentNaming>
      <!-- Regex pattern defining invalid name characters. Escape (\) character can be used as is (ie.: "[^a-zA-Z0-9.()[\]]"). 
Pattern must start with '[' and end with ']'. -->
      <add key="InvalidNameCharsPattern" value="[^a-zA-Z0-9.()[\]\-_ ]" />
      <add key="ReplacementChar" value="-" />
    </contentNaming>
  </sensenet>

Note that changing InvalidNameCharsPattern will affect path validation logic in the whole Content Repository. It is therefore desired to change validation messages when changing invalid characters pattern, see Invalid names and error messages below.

Autonaming rules

Please note that the automatic algorithm changes to lessen the possibility of name collisions: we provide a short list of invalid characters (see example below) that will be encoded or replaced (depending on the configured ContentNamingProvider) and everything else is allowed. You may still make the regular expression less permissive if you need to.

We opened our content naming API so that you can provide your own naming algorithm. See the default providers and customization options in the ContentNamingProvider article.

Invalid names and error messages

The value of the Name Field falls under special validation according to certain restrictions. An auto-generated name by default is always correct but the user always has the possibility to override any auto-generated name and provide a name manually. If the name (hence the path) of the Content does not satisfy the requirements an error message is displayed upon saving the Content. These can be the following:

Incremental naming

Since the path identifies the Content, it has to be unique. Therefore a Content cannot be saved with a name that another Content already uses in the same Folder. By default in this case an error message is shown upon saving the Content:

Cannot create new content. A content with the name you specified already exists.

It is possible to set up a Content Type so that when saving instances of that type no error message is shown when a Content with the same name already exists - but the name is automatically suffixed with a number until it does not collide with any name in the same folder. This setting is controlled using the AllowIncrementalNaming element in the CTD of the type. Possible settings:

<AllowIncrementalNaming>false</AllowIncrementalNaming>

if another Content with the same name exists in the same Folder, an error message is shown and the Content is not saved.

<AllowIncrementalNaming>true</AllowIncrementalNaming>

if another Content with the same name exists in the same Folder, the Content is saved with the provided name suffixed with a number. Ie. My-Content will be saved as My-Content(1) if the Folder already contains a Content named My-Content. If My-Content(1) is also occupied, it will be saved as My-Content(2), etc.

The incremental naming behavior is also customizable using the ContentNamingProvider feature.

Example

Default configuration: invalid characters for Content name

The following web.config settings marks the characters that are not allowed in a URL as invalid characters. Everything else is considered a valid character:

<add key="InvalidNameCharsPattern" value="[\$&amp;\+,/:;=?@&quot;&lt;&gt;\#%{}|\\^~\[\]'’`\*\t\r\n]]" />

Defining allowed characters for Content name

The following web.config settings allows alphanumeric characters, the ‘.’, ‘(‘, ‘)’, ‘[’, ‘]’, ‘-‘, ‘_’ characters and the space for names. Everything else is considered an invalid character:

<add key="InvalidNameCharsPattern" value="[^a-zA-Z0-9.()[\]\-_ ]" />

Defining invalid characters for Content name

The following web.config settings marks the ‘%’ and the ‘/’ as invalid characters for names. Everything else is considered a valid character:

<add key="InvalidNameCharsPattern" value="[%/]" />

Is something missing? See something that needs fixing? Propose a change here.