We recently added a couple of new features to the CMS that was required for the Static Pages plugin. After we implemented them we realized that they add a new level of flexibility to the CMS and even change the way how the components are developed and used!

The features we added are: component support in partials and external values for component properties.

Component support in partials

This is a simple, but powerful feature that has been requested many times. Partials can now host components, so you can reuse pre-configured components across your website. Keep in mind there are some limitations - as partials are initialized only when they're rendered, components defined in partials cannot handle AJAX requests. The regular POST form handling should work, although if the form triggers a redirection it could be a problem. See the updated partials documentation.

External values for component properties

This is the most interesting addition which, we think, adds a great amount of power and flexibility to the components concept. Before this moment components could only have fixed property values, which you define when you add a component to a template. There were workaround for this problem. Some existing components allow to specify the URL parameter name to load the property value from. This approach uses the propertyOrParam() method (see the documentation). This solution is not flexible as it requires a developer to implement the support for the URL parameters in every property which, by the author's opinion, could be loaded from the page URL. However we know that developers and users are different kinds of people. Components are going to be used in ways their author can't anticipate during the time of development. That's why we built the external property values support into the system. Now authors shouldn't worry about where the property value comes from - whether it's a fixed value specified in the component definition, an URL parameter or a partial parameter.

This is a very simple example which should help you to understand the idea. Imagine a Twitter component that displays messages of a specific Twitter user. The component has the user property which specifies the user name. The component author hasn't provided a way to load the property value from an URL parameter, or from a partial parameter. Before this day all you can do is to define the component with a fixed property value:

[twitter]
user = "octobercms"

But what if you want to create a page which displays Twitter messages for a user whose name is specified in the URL, like this /twitterfeed/john or /twitterfeed/andy? Should you contact the component author and ask to add the support for URL parameters? It was the only option before this update. Now you can configure the component to load the parameter value from the URL parameter:

url = "/twitterfeed/:username"

[twitter]
user = "{{ :username }}"

The special syntax allows you to refer to the URL parameter in the component property definition. Now imagine another case - you're building a page that displays Twitter feeds for three different users. Should you add the component to the page three times, and set different values for the user property? Well, that's definitely a solution, but remember about partials, which purpose is to encapsulate reusable chunks of markup and which can host components. The best option for displaying the three Twitter feeds on a page is to create a partial, put the Twitter component to it and define the property value like this:

[twitter]
user = "{{ username }}"

Note that the syntax is different - it refers to the partial parameter. By the way, you can still refer to URL parameters in partials too. Now that you have the partial, you can include it to a page:

{% partial "twitter-feed" username="octobercms" %}
{% partial "twitter-feed" username="john" %}
{% partial "twitter-feed" username="andy" %}

In the CMS back-end you can define an external parameter with the new feature of the Inspector - the external parameter editor, which is attached to all component properties by default.

During the development phase, if you think that loading a property value from an external parameter doesn't make sense, you can disable this feature for the property with the showExternalParameter key (see the documentation). The external property editor is enabled for all properties by default intentionally, as we want the feature to be supported by the majority of component properties. Developers of existing components might want to update their plugins to disable the feature for some properties.

The old approach that uses the propertyOrParam() method is still supported for now and we will eventually deprecate and remove this method from the CMS core, so we encourage to use the new approach when you develop components. Remember that now, when you want your component to load a value from the URL, you should name the property something like "slug" instead of "slugParameterName" and expect a component user to bind the value to the URL or partial parameter.

Enjoy the flexibility, friends. To infinity, and beyond!