Only a little over a week into our development tools announcements, and there is already lots of buzz about our new UI Extensions. The UI Extensions handle a variety of functionality, and we will discuss them all in detail, over the course of multiple blog entries. For today, we'll start with an introduction and an overview of some of the basic usage.
Features and Functionality
UI Extensions are extensions to a single content class - Nodes, Items, Comments, or Reviews. With a UI Extension, you can:
- Add custom CSS classes and data attributes
- Add options to content menus
- Add badges to content item headers
- Add fields to content forms
- ACP-related functionality (for nodes)
And a couple of other small things that we'll cover here.
Setup
The Application Developer Center has 4 new options in the Extensions tab:
- UIComment
- UIItem
- UINode
- UIReview
To add a UI extension, simply create a class under the appropriate extension type.
Note: We are working on improving this process, however, those changes will likely be introduced at a later date.
The default extension file will be generated in the appropriate directory within your application's extensions folder. All UI Extensions are abstracted, so if you omit a method from your class, or if new methods are introduced later on, your extension will not throw an error.
All UI Extension methods receive the object as the first parameter.
UI Extensions for... UI
The idea for UI Extensions was born when we were reviewing the most common third-party development hooks. With the removal of theme hooks, we needed a way for developers to add custom CSS and attributes to areas such as topic rows, the author panel, among others. Even with the theme hooks in v4, the way to accomplish this was less than ideal. Adding a CSS class typically required at least 2 hooks per template - one to determine the correct class (usually based on custom logic) and one to insert the class as a variable. It was tedious and finicky at best.
All UI Extensions include the following methods:
-
css
Returns an array of CSS classes that will be applied to the object -
dataAttributes
Returns an array of data attributes (as "key=value", "key=value") that will be applied to the object
To insert those values into the appropriate location, our templates now contain the following syntax:
{$object->ui( 'css' )}
and
{$object->ui( 'dataAttributes' )}
Let's examine the Content::ui() method (identical to Model::ui().)
public function ui( string $method, ?array $payload=array(), bool $returnAsArray=false, string $separator = " " ) : array|string
The ui method accepts 4 arguments: the method name, an optional payload (determined based on the method being called), the option to return as an array (vs a string), and an optional separator (when data is returned as a string). The defaults for this method were set for the simplest, shortest syntax within the templates, as seen above. You may also see syntax like this:
foreach( $this->ui( 'menuItems', array(), TRUE ) as $key => $link ) { $links[$key] = $link; }
As you can see, in this case the ui method will return the results as an array.
Class-Specific Methods
Some of our extensions include methods that are applicable only to objects of that type.
-
UIItem::sidebar()
Returns HTML that will be included in the contextual sidebar when viewing the item -
UIComment::authorPanel()
Returns HTML to be inserted into the author panel of a post
Note: All methods in the UIComment extension are also available in UIReview.
We hope this entry gave you a glimpse into what will be available with this new tool, and a better understanding of the direction we are taking with our toolkit. We will discuss the other features of this tool in upcoming blog entries.
Recommended Comments