# mod\_admin Source: https://zotonic.com/docs/1331/mod_admin URI: https://zotonic.com/id/1331 Language: en Admin backend module that wires the core admin interface, assets, and admin-specific event handling. Extending the admin menu ------------------------ See model#admin_menu on how to extend the admin menu. System administration pages --------------------------- `admin_status` (`/admin/status`) shows health, background work and services. `admin_maintenance` (`/admin/maintenance`) contains repairs and rebuild operations. `admin_system_info` (`/admin/system-info`) shows versions and installation paths. Maintenance and system information require `use.mod_admin_config`; sensitive runtime information remains restricted to system administrators. Modules can contribute complete status panels with `_admin_status_panel.tpl` and maintenance panels with `_admin_maintenance.tpl`. Both use `all include`. Compose `_admin_maintenance_panel.tpl` with a translated `title`, optional `scope` and `panel_id`, and override its `tools` block for a consistent panel layout. Within a panel, compose `_admin_maintenance_action.tpl` with `title` and `description`, overriding its `action` block for the operation controls. Check permissions in the contribution and in every server-side action handler. The legacy `_admin_status.tpl` button hook remains on `/admin/status`, inside Additional module tools. `_admin_system_status.tpl` still accepts external status widgets. External modules do not need to migrate. Bundled tools instead live on their owning pages: modules, configuration, SEO, media, users, menu and categories. Import tools use `_admin_import_tools.tpl` on `admin_imports` (`/admin/imports`). Search maintenance contributions use `_admin_maintenance_search.tpl`. Extending the admin edit page ----------------------------- There are several special templates names that will be automatically included into the /admin/edit/xxx page from when you create these specially named templates. `_admin_edit_basics.tpl` Will be automatically included into main (left) div (at top). `_admin_edit_content.tpl` Will be automatically included into main (left) div (at bottom). `_admin_edit_sidebar.tpl` Will be automatically included into right sidebar (near middle/bottom). These templates are included using the tag#all_catinclude tag; so if you need something in the sidebar just for persons, create a `_admin_edit_sidebar.person.tpl` file in your project. ### Overriding TinyMCE options If you need to override TinyMCE options; adding plugins, or setting other settings; you can create an `_admin_tinymce_overrides_js.tpl` file which can contain extra settings for the TinyMCE editors in the admin. The template must contain JavasSript which modifies the tinyInit variable just before the editor is started. For example, to tweak the “paste” options you can put the following in the template: ```javascript tinyInit.theme_advanced_blockformats = "p,h1,h2" tinyInit.paste_auto_cleanup_on_paste = true; tinyInit.paste_remove_styles = true; tinyInit.paste_remove_styles_if_webkit = true; tinyInit.paste_strip_class_attributes = true; tinyInit.paste_text_sticky = true; tinyInit.paste_text_sticky_default = true; ``` ### TinyMCE Zotonic options Zotonic provides extra init options: `z_insert_dialog_enabled` Set this to false to prevent the insert media dialog from showing. Default `true`. `z_properties_dialog_enabled` Set this to false to prevent the media properties dialog from showing. Default `true`. Writing admin widget templates ------------------------------ This section contains examples of templates to create widgets for the /admin. Each of these examples extends basic several widget templates from mod\_admin. To write your own you need to drop example content and fill holes in these example widgets. You can use them as basis for your site admin-related tasks. `_admin_dashboard_example.tpl` Very simple example widget for admin dashboard. Contains blocks for title and body. Look at /admin to see several dashboard widgets (latest events, pages, media, etc). `_admin_widget_std.tpl` Sligthly more complex widget example. Same templates are used into /admin/edit/N for main content and sidebar widgets. These widgets do not provide any localization abilities. Also note that there are several special widget names: `_admin_widget_i18n.tpl` Complex widget example. Is used to edit localized rsc properties. It will be rendered as tabs. See /admin/edit/N top left to see the tabs. If mod\_translation disabled, then i18n-widgets are displayed same as \_admin\_widget\_std.tpl. Making an admin widget conditionally visible -------------------------------------------- An admin widget can decide whether its complete wrapper is rendered. Override the `widget_wrapper` block, test the condition, and use tag#inherit to render the wrapper supplied by the parent template. For example, the backup module only shows its edit-page widget when its admin panel is enabled: ```django {% extends "admin_edit_widget_std.tpl" %} {% block widget_wrapper %} {% if m.backup.admin_panel %} {% inherit %} {% endif %} {% endblock %} ``` When the condition is false, the overridden block renders nothing. When it is true, `{% inherit %}` renders the normal widget wrapper and all of its content. This keeps the visibility decision inside the widget instead of repeating the condition at every include site. Extending the admin overview page --------------------------------- The overview page at `admin/overview` shows a table with links to all pages. It can be filtered and sorted. This extension deals with the view when a category filter has been selected. The goal is to add more specific information that helps to distinguish pages. The Category column, second from the left, can be extended to carry category-specific information. As an example, pages of category Event show the start date for each event, grayed out when the event is in the past. Something like this: | Title | Starts | Created on | | ----------- | ------------------- | ------------------ | | Great event | 2016-08-27 00:00:00 | 25 Aug 2015, 22:19 | | Past event | 2014-01-02 00:00:00 | 01 Jan 2014, 13:10 | Instead of dates, the information can be anything - from color coding labels to location data, the number of comments or the completeness state of product descriptions. ### Setting up templates To make it work we are using 3 templates (where category\_name is the lowercase name of your category): `_admin_overview_list.category_name.tpl` Overrides the overview with a `field` variable for our custom sort. To sort by an existing resource property from model#rsc, such as `date_start`, we write: ```django {% include "_admin_overview_list.tpl" field="pivot.date_start" %} ``` `_admin_sort_header.category_name.tpl` The sort header caption. For a non-sortable header, just write the caption as text. For a sortable header, include the sort functionality in `_admin_sort_header.tpl` and pass the caption as variable: ```django {% include "_admin_sort_header.tpl" caption="My caption" type="date" %} ``` `type="date"` indicates that sorting should start descending, from new to old. `_admin_overview_list_data.category_name.tpl` Contains the category-specific information. This is a freeform Zotonic template. The Events example checks if the end date is in the past: ```django {% if id.date_end|in_past %} {{ id.date_start|timesince }} {% else %} {{ id.date_start|timesince }} {% endif %} ``` ### Custom sort properties To sort on values that are not stored in the default Zotonic resources, you will need to create a [custom pivot](/id/doc_cookbook_custom_pivot#cookbook-custom-pivots). This will create an additional database table with the values to sort on. Let’s take the (unlikely) example where we want to display the summary of each page (and sort on it as well). The summary data is not stored in an easily accessible way (at least for sorting), so we need to add 2 pivot methods to our Erlang module: ```django -module(mymodule). -export([ init/1, observe_custom_pivot/2 ]). init(Context) -> z_pivot_rsc:define_custom_pivot(?MODULE, [{summary, "text"}], Context), ok. observe_custom_pivot({custom_pivot, Id}, Context) -> case z_trans:lookup_fallback(m_rsc:p(Id, summary, Context), Context) of undefined -> none; Summary -> {?MODULE, [{summary, Summary}]} end. ``` For this example we are just grabbing the default language text. The `field` name in `_admin_overview_list.category_name.tpl` now just needs to contain the pivot column name: ```django {% include "_admin_overview_list.tpl" field="pivot.mymodule.summary" %} ``` And the sort header template `_admin_sort_header.category_name.tpl` adds the custom pivot variable: ```django {% include "_admin_sort_header.tpl" caption="Summary" %} ``` Resource meta features ---------------------- Resources in the meta category can have ‘features’: certain resource properties (usually in the form of checkboxes) that decide what to show or hide on certain pages in the admin. To use this, create a `_admin_features.category.tpl` in your module. For instance, the module mod\_geomap defines the following `_admin_features.category.tpl` to create an extra checkbox so that per category can be defined whether or not the geodata box should be shown: ```django
``` And on the edit page there is this check to conditionally include the geodata box: ```django {% if id.category_id.is_feature_show_geodata|if_undefined:true %} ``` The filter filter#if_undefined is used so that the default value can be true when the checkbox has never been touched. Configuration keys ------------------ For the admin there are the following configuration keys: - `mod_admin.rsc_dialog_tabs` - `mod_admin.rsc_dialog_is_published` - `mod_admin.rsc_dialog_is_dependent` - `mod_admin.rsc_dialog_hide_dependent` - `mod_admin.connect_created_me` The `mod_admin.rsc_dialog_tabs` key defines which tabs are shown in the new resource, media-upload, and image-link dialogs. Per defauls these dialogs show all the possible tabs, with this configurarion key it is possible to change that. Available tabs are: `find,new,upload,url,embed,oembed,depiction`. More can be defined by modules. Tab `depiction` is used for the TinyMCE image-link dialog; it shows all media connected using the `depiction` predicate. The configuration `mod_admin.rsc_dialog_is_published` defines the default *is\_published* state for new resources. Setting this key to 1 will check the *is\_published* checkbox. The configuration `mod_admin.edge_list_max_length` defines the maximum number of connections shown per predicate in the connection list sidebar. If there are more connections then the list truncated, and the message *Too many connections, only the first and last are shown.* is displayed. The default is 100 connections. The configuration `mod_admin.rsc_dialog_is_dependent` defines the default *is\_dependent* state for new resources. Setting this key to 1 will check the *is\_dependent* checkbox. With the configuration `mod_admin.rsc_dialog_hide_dependent` the *dependent* checkbox can be hidden for non admin users. If the `mod_admin.connect_created_me` is set then the connect dialogs will per default filter for content made by the current user. The current setting is stored in the sessionStorage with the key `dialog_connect_created_me`. Bulk updates and connections ---------------------------- The bulk-update dialog can update properties and add connections to all selected pages. **Add connections from** adds an edge from the chosen page to each selected page. **Add connections to** adds an edge from each selected page to the chosen page. Each direction has its own searchable page picker and predicate selector. A page and predicate must be selected together; leaving both empty makes no connection changes. Existing connections remain, and adding an existing edge does not create a duplicate. The `update_all` submit handler delegates to `z_admin_bulk_update:update/3`. It consumes `bulk_subject_id`, `bulk_subject_predicate`, `bulk_object_id`, and `bulk_object_predicate` as connection controls, without storing them as resource properties. Both selections are validated before any updates. Every selected page must be editable, and normal edge-insertion permissions apply. Failed operations are logged and reported to the user; successful changes are retained, so a failure can leave a partially applied bulk update. Accepted Events --------------- This module handles the following notifier callbacks: - `observe_acl_is_owner`: If the given resource is a temporary resource then the current session using `filter_temporary_rsc:is_creator`. - `observe_admin_edit_blocks`: Provide standard resource block types for the admin edit block chooser. - `observe_admin_menu`: Contribute standard admin menu items. - `observe_module_ready`: When the module is ready, flush the admin\_menu depcache using `z_depcache:flush`. - `observe_rsc_update_done`: After a resource is saved, ensure that all embedded resource references are using `m_config:get_boolean`. - `observe_sanitize_element`: Fix tinymce images that are the result of copying using `m_rsc:rid`. Delegate callbacks: - `event/2` with `postback` messages: `admin_note_delete_rsc`, `admin_rsc_redirect`, `delete_tasks`, `ensure_refers`. - `event/2` with `submit` messages: `admin_note_update_rsc`, `delete_all`, `dropbox_upload`, `update_all`. - `event/2` with `postback_notify` messages: `<<"admin-insert-block">>`, `<<"feedback">>`, `<<"update">>`. License: Attribution: Related resources: https://zotonic.com/api/agent/related/1331?language=en ## API access - [API help]() - [OpenAPI specification]() - [This resource as JSON]()