DEFINITION OF BUILT-IN DATA TYPES

A number of data types come with the basic install of Umbraco. Most of the data types listed in the following sections also allow you to create variations of them to fit your own needs. For example, the Ultimate Picker data type allows you to specify which type of HTML input control should be rendered as well as indicate which node to start with.

The fields that allow you to set additional configurations require you to add either prevalues (predefined values for the user to select from), or set other settings like HTML control type and so on. The steps that follow describe how this is done. Each field, however, is made up of at least three attributes. This includes a Name to identify the data type; the Render Control, which specifies which HTML control is used to enter or interact with the data; and finally, a system-generated GUID (globally unique ID).

1. As shown in Figure D-1, enter the desired value in the Add prevalue field and click the Save button in the toolbar toward the top of the screen.
2. Repeat step 1 for the remainder of the values that you need to add.
3. You can edit a prevalue value by clicking the value. This reveals an editable field, shown in Figure D-2, that auto-saves when you click outside of the field.

FIGURE D-1

FIGURE D-2

Approved Color

The Approved Color data type allows you to create a field that presents a color picker with a predefined list of colors from which the editor can select. Simply add the hexadecimal colors you want the editor to have access to in the Add prevalue field, as shown in Figure D-3. Figure D-4 shows what the end result looks like when you use the data type in the Content section.

FIGURE D-3

FIGURE D-4

The saved result will be a string of the selected color value as you defined in the prevalue list.

Checkbox List

As the name implies, Checkbox List allows you to render a list of checkboxes with the values you define in the prevalue list, shown in Figure D-5. The view in the Content section is shown in Figure D-6.

FIGURE D-5

FIGURE D-6

The saved result of the checkbox list datatype is a comma-separated list of the selected values. The following code snippet shows how to work with the saved values in XSLT:

<xsl:variable name=“items”
     select=“umbraco.library:Split($selectedCheckboxItems,‘,’)” />
<xsl:for-each select=“$items//value”>
   <xsl:value-of select=“umbraco.library:GetPreValueAsString(current())”/>
</xsl:for-each>

Content Picker

The Content Picker is a replica of the content tree shown in the Content section. The editor is presented with the Content Tree view that he or she has permission to see and can select a node from this tree, as shown in Figure D-7. No prevalue is here because the tree is automatically generated based on the user's permissions.

FIGURE D-7

Date Picker with Time

A Date Picker with Time presents your user with a calendar control to pick a date and select a time (consisting of the hour and minute). Figure D-8 shows the view that the editor sees. Use this data type to specifically set a time and a date. If you are only interested in the date, use the Date Picker data type.

The saved result for this data type is a date object. To put the value in a human-readable format, you can use the available date format function from the umbraco.library extension methods, as shown in the following code snippet. Any valid date format can be supplied.

FIGURE D-8

<xsl:value-of
   select=“umbraco.library:FormatDateTime($dateNode, ‘MM/dd/yyyy’)”/>
<xsl:value-of
   select=“umbraco.library:FormatDateTime($dateNode, ‘hh:mm’)”/>

Date Picker

The Date Picker presents a user with a calendar control to pick a date. Figure D-9 shows the view that the editor sees.

The saved result for this data type is a date object. To put the value in a human-readable format, you can use the available date format function from the umbraco.library extension methods, as shown in the following code snippet. Any valid date format can be supplied.

FIGURE D-9

<xsl:value-of
   select=“umbraco.library:FormatDateTime($dateNode, ‘MM/dd/yyyy’)”/>

Dropdown Multiple

The Dropdown Multiple data type allows you to present the editor with an HTML select box to pick multiple values from. As with other data types, simply add the prevalues you want, and the editor will see something similar to what is shown in Figure D-10.

FIGURE D-10

Similar to the saved result of Checkbox List, the saved result is a comma-separated list of values. For an example of how to output the selected values using XSLT, see the section “Checkbox List” earlier in the chapter.

Dropdown

The Dropdown control simply displays a standard HTML select box, giving the editor the option to select one and only one value from the list. Again, add your values using the Add prevalue field, repeating for all the values that you need to display in the dropdown field.

Image Cropper

The Image Cropper control is very useful if you have editors uploading images to the Media section of the Umbraco backoffice. This particular data type only applies to the Image media type. It allows you to specify predefined crop sizes for images that are uploaded, which restricts the user to publishing images in a specific format. To add crop sizes and behavior specific to your needs, follow these steps:

1. In the Property alias field, enter umbracoFile. This stores the file that you're uploading to the Media section.
2. Select the Save crop images checkbox. A Quality input field appears. In this field you can specify the DPI (dots per inch) with which the resulting cropped image should be saved. Figure D-11 shows an example of the image cropping result.

   FIGURE D-11

   

3. Select the Show Label checkbox. Doing this will display the name of the crop in the Media section.
4. Fill in the name of the crop region. This example has a headshot format available for users to use when cropping images.
5. Fill in a target width and height. These values set the maximum dimensions of the crop.
6. Set the default position of the crop. This setting determines where the crop region is placed when the crop action is first initiated.
7. Click the Add button.
8. Repeat step 1 through 7 for the number of different crops that you want to make available to your editors.
9. Save the data type by clicking the Save icon in Umbraco's main toolbar.

Before you can use the cropper, you must add the data type as a property for the Image media type. To do this, follow these steps.

1. Navigate to the Settings section in the Umbraco backoffice.
2. Expand the Media Types node and click Image.
3. Click the Generic Properties tab at the top of the screen.
4. Click the “Click here to add a new property bar” option toward the top of the right-hand pane.
5. Fill in the name of the property. In this example, the property name is Crop.
6. Select Image Cropper as the Type.
7. Save the Image media type by clicking the Save button in Umbraco's main toolbar.

Your media library is now set up to show the cropper when an Image is uploaded. See Figure D-12 for an example of what the cropping plugin will look like. Now you can use the corner handles on the defined regions to specify what portions of the original image should be shown in the crop.

FIGURE D-12

To access these images in your XSLT, simply output the image using the following code snippet:

<!-- get the image from media library usign GetMedia -->
<xsl:variable name=“pic”
    select=“umbraco.library:GetMedia($img1, ‘true’)/umbracoFile” />
<-- Create an image object -->
<img>
    <!-- add the src attribute to the image tag -->
    <xsl:attribute name=“src”>
        <xsl:value-of select=“$pic/crops/crop [@name=‘headshot’]/@url”/>
    </xsl:attribute>
</img>

Macro Container

The Macro Container allows you to give your editors a way to add macros to the Content node. This provides a way for editors to include custom functionality from any macros that you have developed (see Chapter 5).

As shown in Figure D-13, you must specify which macros your users can select, how many they can select for any given node, and what the dimensions of the control should be in the Content section.

FIGURE D-13

The saved result of this selection is a list of Umbraco macro tags. A sample of this output is shown in the following code snippet:

<macroContainer>
    <![CDATA[
        <?UMBRACO_MACRO  macroalias=“NewsAreaList”  />
        <?UMBRACO_MACRO  macroalias=“SiteNavigation”  />
    ]]>
</macroContainer>

Media Picker

The Media Picker is just what the name suggests. This data type allows editors to select a media item from the media library. Permissions and access for the individual editor applies here just like in the Content Picker. So, if an editor has a specific start node set, that's all he or she will see when using this control. Figure D-14 shows what the editor sees when working with the Media Picker in the Content section of the Umbraco backoffice.

The saved result for this data type is the ID of the media item. An example of how to get the path of the file is shown in the following code snippet:

FIGURE D-14

<xsl:value-of
    select=“umbraco.library:GetMedia(imageFieldName, ‘true’)/umbracoFile” />

Member Picker

The Member Picker simply shows a list of any members that have been added to the Members section of the Umbraco backoffice. The saved result of this data type is the member ID.

Radiobox

Similar to the Checkbox List data type, Radiobox displays a list of the added prevalues in a list with HTML radio buttons. As is expected with HTML radio buttons, an editor can only select one value when using the data type.

Related Links

This data type is very useful when you need to display a list of internal or external links associated with a particular page. As shown in Figure D-15, the control allows you to add as many related links as you need for any given node. When you add an internal link, you are asked to select a node using the Content Picker. When you add an external link, you simply enter the URL. In addition, you can indicate whether the particular link should open in a new window.

The saved result of this data type produces XML that you can parse using simple XPath statements.

FIGURE D-15

Richtext Editor

The Richtext Editor data type is the foundation of the Umbraco WYSIWYG (what you see is what you get) editor and what allows editors to manage content in a non-technical fashion. As shown in Figure D-16, you can toggle quite a number of settings for this data type. As you can see, this data type is based on the TinyMCE plug-in, which is an open source WYSIWYG editor that Umbraco has elected to implement.

FIGURE D-16

The options for this data type are fairly obvious, and the default settings are a good standard for your editors. The most important setting to note here is the Related Stylesheets setting, which allows you to specify stylesheets that you want to apply when rendering the content in the richtext editor control. For example, if you want the paragraph tag to look a certain way within the editor window, you can specify that in the stylesheet that applies.

The saved result of this data type produces standard and XHTML-compliant HTML.

Simple Editor

Again, the name kind of gives away what Simple Editor is. It's a multi-line text field that allows very simple editing, such as inserting HTML bold, italic, and link tags into the text. Figure D-17 shows an example of the editor.

FIGURE D-17

Tags

The Tags data type (see Figure D-18) provides editors with an auto-suggest control so that tags are not added multiple times for any given field across multiple pages. For example, if you add the string cars to this field on a particular page, and then go to edit the same field on another page, you'll see “car” as a suggestion as soon as you type the letter c in the textbox.

FIGURE D-18

As of Umbraco 4.6.x, you can also specify a tag group for the data type. This means you can keep separate lists of tags for different data types so as not to cross-contaminate the lists between different types of fields.

The saved result of the Tags data type is a comma-separated list of values. See the section “Checkbox List” earlier in the chapter for an example of how to work with this data in XSLT.

Textbox Multiple

Textbox Multiple is simply a multi-line text input in the form of the HTML element <textarea />. By default, this data type is based on Ntext, which allows you to put in an unlimited amount of data (or as much as your database can store).

Textstring

The Textstring data type is a standard one-line text HTML input field that allows you to save simple strings.

True/False

The True/False data type presents the editor with a checkbox to indicate a true or false value for a field. You use this data type for something like determining whether a node appears in the navigation.

The saved result of this data type is a 1 if the checkbox is selected and a 0 if the checkbox is not selected.

Ultimate Picker

The Ultimate Picker data type is a powerful control that allows you to provide editors with a means of selecting nodes from your content tree. Options for the render controls include: Auto Complete (like the Tags data type), Checkbox List, Dropdown List, List Box (like the Dropdown Multiple data type), and Radiobutton List (like the Radiobox data type). In addition, you can specify where in the content tree the nodes should start. This means that you can limit the view of a certain subset of the nodes in the content tree. Combine this data type with a document type filter capability, and you have a very flexible content picker.

Here's an example. In the website example in this book two separate sites are set up with two different languages. If you want to create a content picker with only the FAQs from the English website, you can configure the Ultimate Picker data type to look something like Figure D-19.

Similar to the Checkbox List and other multi-select data types, the Ultimate Picker saves the values in a comma-separated value list.

FIGURE D-19

Upload

The Upload data type enables you to attach a file to a page. This field is different from using the Media section in that the file you upload is not accessible from the Media section. If you know the path to the file, the file is only accessible from the scope of the currentPage in your XSLT.

The saved result from this data type is the path to the uploaded file as a string.