How to use Controller::asCpScreen()

[mikejpeters]

Hi, I'm wondering the best way to render the edit screen for a custom element type in the CP.

In previous versions of Craft CMS I did most of the work in a template (e.g. _edit.twig), but when upgrading to Craft 4 I see there is an asCpScreen() method that seems convenient for generating this screen and I assume will be less likely to break in future versions of Craft (vs. a lot of markup in a template file). Is this the recommended approach now?

I searched the Craft docs and here but didn't find much, except links to the FsController which uses this method. I've also tried looking at the ElementsController but it seems more advanced than I need and a bit hard to follow.

What I have so far:

    public function actionEdit(?int $donationId = null, ?Donation $donation = null): Response
    {
        $this->requireCpRequest();
        
        // ... some logic to get the donation being edited, check permissions, set some defaults, etc.
        
        return $this->asCpScreen()
            ->title($isNewDonation ? 'Enter a new donation' : 'Edit Donation')
            ->addCrumb('Donations', 'donations')
            ->action('donations/donations/save')
            ->redirectUrl('donations')
            ->prepareScreen(
                function(Response $response, string $containerId) use ($donation) {
                    $fieldLayout = $donation->getFieldLayout();
                    $form = $fieldLayout->createForm($donation, false, [
                        'registerDeltas' => true, // not sure about this
                    ]);

                    /** @var Response|CpScreenResponseBehavior $response */
                    $response
                        ->tabs($form->getTabMenu())
                        ->content($form->render(false));
                }
            );

I'm hoping I'm on the right track because I get a page rendered with a title, "Save" button, and tabs, but there are some problems such as the tab being empty until I click on a tab.

I'm also hoping to be able to add the details sidebar (e.g. with Author, dates, and statuses) and other actions like "Delete".

I don't mind digging through the code more to figure out some of this but would really appreciate any guidance you can give, thanks for your time!

[AugustMiller]

You're definitely on the right track, here! Yes, asCpScreen() is the preferred method for generating responses that target multiple contexts.

This section of the element type docs covers our recommendations for handling the edit view for your element.

In short, letting Craft construct the view via the elements/edit controller action will provide virtually everything an element relies on.

Beyond that, you can implement the metadata(), metaFieldsHtml(), and prepareEditScreen() methods to customize the screen and its output—without having to maintain your own controller action.

The two meta* methods here are likely what you're looking for with respect to altering the contents of the sidebar. ✌️

[mikejpeters]

Thank you! Don't know how I missed this when I looked at the docs; it doesn't really give help for asCpScreen() but it looks like overriding the methods you described and removing my custom controller actions completely avoids the need to get into that.