In today’s post, I’ll talk about property aliases and why they’ll be your friend when creating custom components in QML. I’ll give you an introduction to the topic by creating a Header component, which consists of a Label and a Divider wrapped inside a Container.

I assume that you already know how to create custom components in QML. Basically you create a new file and name it to whatever the name of your component is, for example ‘Header.qml’. So say we have a file ‘Header.qml’ with the following content:

import bb.cascades 1.0

Container {

    Label {
        id: titleLabel
        text: "Sample Title"
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

To create a Header instance from another QML file, we simply write the following lines:

...

Header {
}

...

Looks good, but I assume that we also want to set the title to something more appropriate for the context where the header is to be used. Because we don’t have direct access to the Label’s text property from outside the Header component (you can only access top level properties), we need to add a new property to the Container in the Header component:

import bb.cascades 1.0

Container {
    property string titleText: “Sample Title”

    Label {
        id: titleLabel
        text: titleText
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

The Label’s text property binds to the newly added titleText property. Now we can specify a title by setting the titleText property:

Header {
    titleText: “My Header”
}

Looks nice and works great, but I’m still not satisfied. I had to introduce a new property just to be able to specify a title text. What I actually want is to expose the Label’s text property to users of the Header component. Fortunately there’s a solution for this, and the name is property alias:

import bb.cascades 1.0

Container {
    property alias titleText: titleLabel.text

    Label {
        id: titleLabel
        text: “Sample Title”
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

Much better. We got rid of the titleText property by simply making it an alias to the titleLabel’s text property instead. Even the instance of the Label can be exposed as an alias, which gives you access to all of the Label’s properties, if that’s what you need:

import bb.cascades 1.0

Container {
    property alias titleLabel: titleLabel

    Label {
        id: titleLabel
        text: “Sample Title”
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }

    Divider {
    }
}

Now that we have access to all of the Label’s properties, we can also change the text style:

Header {
    titleLabel {
        text: “My Title”
        textStyle.base: SystemDefaults.TextStyles.TitleText
    }
}

Handy, right?