Receiving and storing variables for Admin Boxes

They key of an admin box is an array for storing variables/meta information about your Admin Box.

The id of the item being edited

All Admin Boxes should have an "id" variable in their key, e.g.:

example_module_4__animal:
    key:
        id: ''

When your Admin Box is first opened, if an administrator is editing an existing item, the CMS put the id of the item being edited into the id variable, which you can then read in your php code using the $box['key']['id'] variable.

If an administrator is creating a new item, the $box['key']['id'] variable will be empty. When you save it in your saveAdminBox() method, you should record the newly inserted id and then place it in the $box['key']['id'] variable to let the CMS know the new id.

Additional Properties

You can define extra properties should you need them. For example, from the categories Admin Box has two entries:

zenario_categories:
    key:
        id: ''
        parent_id: ''

The id variable works as described above. The parent_id variable is custom and stores the id of the parent category.

When editing an existing category, the parent_id variable is not needed, as the category already exists and the correct value can be looked up from the database.

When creating a new category, nothing can be looked up from the database so the parent_id variable is needed to determine where the category should be placed upon creation.

Setting the values of additional properties from buttons in Organizer or the Admin Toolbar

If your Admin Box is opened from a button in Organizer or the Admin Toolbar, you can set variables in the key by defining them against the button. Different buttons can have different variables defined, for example:

item_buttons:
    settings:
        label: Edit meta data
        admin_box:
            path: zenario_content
    duplicate:
        label: Duplicate
        admin_box:
            path: zenario_content
            key:
                duplicate: true

The Edit meta data button opens the Admin Box normally. The Duplicate button opens the admin box with the duplicate variable set.

If you were writing the logic for this Admin Box in your php code, you could make it so that it loaded and saved normally when the duplicate variable was not set, but saved a copy of the item when the duplicate variable was set.

Setting the values of properties in your php code

You may change the variables in the key by changing the $box['key'] variable in your php code.

These changes will persist until the Admin Box is close. For example, you can set a variable in your fillAdminBox() method and then read its value in your saveAdminBox() method, even though these take place in different requests to the server.

Reference for key: