From a7cf60584f99ad78e45bb1d71e4f8ce7b3a4072d Mon Sep 17 00:00:00 2001 From: Guillaume Viger Date: Fri, 1 Sep 2023 10:34:59 -0400 Subject: [PATCH] admin: improve little things about the docs based on experience using them --- docs/develop/topics/administration_panel.md | 29 ++++++++++++--------- docs/reference/administration_reference.md | 15 ++++++----- 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/develop/topics/administration_panel.md b/docs/develop/topics/administration_panel.md index 200f60ad..46b9aabd 100644 --- a/docs/develop/topics/administration_panel.md +++ b/docs/develop/topics/administration_panel.md @@ -263,7 +263,7 @@ A custom view can be created by inheriting directly from `AdminView`. ##### Usage -In your module, create a new folder (anchor link to the folder structure) and a following `.py` file: +In your `` (called `invenio_module` for simplicity), create a `.py` file: ```python from invenio_administration.views.base import AdminView @@ -273,7 +273,7 @@ class MyCustomView(AdminView): name = "customview" category = "My category" - template = "invenio_administration/index.html" + template = "invenio_module/custom_view_template.html" # placed in templates/invenio_module/custom_view_template.html url = None menu_label = "Custom View" icon = "user" @@ -281,12 +281,12 @@ class MyCustomView(AdminView): The class defined for the custom view must be registered as an entry point, as follows: -Edit the setup.cfg of your module and add: +Edit the `setup.cfg` of your module and add: ```ini [options.entry_points] invenio_administration.views = - invenio_module_admin_custom_view = invenio_module.administration.views:MyCustomView + invenio_module_admin_custom_view = invenio_module.path.to.filename:MyCustomView ``` For the full attributes list and description visit the [reference docs](../../reference/administration_reference.md) @@ -331,7 +331,7 @@ In each view you can override or extend different blocks, mainly there are 2 blo - `admin_page_content`: Content of each view. It's present in all the views. - `JavaScript`: Main block to place any JavaScript content. -- + ```html {% extends "invenio_administration/details.html" %} @@ -340,8 +340,10 @@ In each view you can override or extend different blocks, mainly there are 2 blo {% endblock admin_page_content %} {% block javascript %} - {{ super() }} # don't forget the parent JS assets! - {{ webpack['invenio-administration-search.js'] }} # it is crucial to remember about adding proper assets to your Jinja + # don't forget the parent JS assets! + {{ super() }} + # don't forget to add proper assets to your template + {{ webpack['invenio-administration-search.js'] }} {% endblock %} ``` @@ -357,17 +359,16 @@ If you would like to, for example, change layout of the default view, you can cr Create a js file (`MyComponent.js`) containing your custom component, which you have to place in `/assets/js` folder of your module. ```javascript - class MyComponent extends Component{ - render(){ +class MyComponent extends Component { + render() { return "Hello World!" } } - const domContainer = document.getElementById("invenio-details-config"); domContainer && ReactDOM.render( - , + , domContainer ); ``` @@ -399,8 +400,10 @@ Once the file was added as webpack entry, we can add it to the template we are o {% endblock admin_page_content %} {% block javascript %} - {{ super() }} # don't forget the parent JS assets! - {{ webpack['my-component.js'] }} # make sure name of the asset matches the name you registered in webpack entry + # don't forget the parent JS assets! + {{ super() }} + # make sure the name of the asset matches the name you registered in the webpack entry + {{ webpack['my-component.js'] }} {% endblock %} ``` diff --git a/docs/reference/administration_reference.md b/docs/reference/administration_reference.md index ab54a965..6c356647 100644 --- a/docs/reference/administration_reference.md +++ b/docs/reference/administration_reference.md @@ -15,8 +15,8 @@ This document provides a reference guide for all the attributes available for `i | **resource_config** | *required* | | used to retrieve the resource (name of the resource attribute of the flask extension - available in ext.py) | | **search_request_headers** | | *{ "Accept" : "application/json" }* | specifies resource-specific headers to add during REST API request | | **title** | *required* | | displays a title in the list view page | -| **category** | | | places the menu entry under a category in the menu bar | -| **pid_path** | | *"pid"* | used for accessing the unique identifier of a resource | +| **category** | | | places the menu entry under a category in the menu bar | +| **pid_path** | | *"pid"* | used for accessing the unique identifier of a resource | | **icon** | | | displays an icon next to the menu's entry | | **template** | | *"invenio_administration/search.html"* | template to be rendered for the view. By default, it uses a predefined one. Can be overridden with a custom template | | **display_search** | | *True* | displays/hides a searchbar in the list view | @@ -39,7 +39,7 @@ This document provides a reference guide for all the attributes available for `i | **name** | | *view class name* | view's name used by Flask to create routing | | **url** | | *view's 'name'* | url used to route the view. | | **resource_config** | *required* | | used to retrieve the resource (name of the resource attribute of the flask extension - available in ext.py) | -| **pid_path** | | *pid_path* | used for accessing the unique identifier of a resource | +| **pid_path** | | *pid_path* | used for accessing the unique identifier of a resource | | **api_endpoint** | *required* | | used to indicate API endpoint of update the resource | | **title** | *required* | *"Resource details"* | displays a title in the view page. | | **list_view_name** | *required* | | name of the resource's list view name, enables navigation between detail view and list view. | @@ -59,11 +59,11 @@ This document provides a reference guide for all the attributes available for `i | **name** | | *view class name* | view's name used by Flask to create routing | | **url** | | *view's 'name'* | url used to route the view. | | **resource_config** | *required* | | used to retrieve the resource (name of the resource attribute of the flask extension - available in ext.py) | -| **pid_path** | | *pid* | used for accessing the unique identifier of a resource | +| **pid_path** | | *pid* | used for accessing the unique identifier of a resource | | **api_endpoint** | *required* | | used to execute POST request. | | **title** | *required* | | displays a title in the view page. | | **list_view_name** | *required* | | name of the resource's list view name, enables navigation between create modal and list view. | -| **form_fields** | *required* | | fields to be displayed in the creation form. | +| **form_fields** | *required* | | fields to be displayed in the creation form. | | **template** | | *"invenio_administration/create.html"* | template to be rendered for the view. Can be overridden by a custom template. | ## Edit View @@ -75,7 +75,7 @@ This document provides a reference guide for all the attributes available for `i | **name** | | *view class name* | view’s name used internally by Flask | | **url** | | *view's 'name'* | url used to route the view. | | **resource_config** | *required* | | used to retrieve the resource (name of the resource attribute of the flask extension - available in ext.py) | -| **pid_path** | | *pid_path* | used for accessing the unique identifier of a resource | +| **pid_path** | | *pid_path* | used for accessing the unique identifier of a resource | | **api_endpoint** | *required* | | used to update the resource. | | **title** | *required* | | displays a title in the view page. | | **list_view_name** | *required* | | name of the resource's list view name, enables navigation between edit view and list view. | @@ -83,8 +83,9 @@ This document provides a reference guide for all the attributes available for `i | **template** | | *"invenio_administration/edit.html"* | template to be rendered for the view. Can be overridden by a custom template. | -### Custom view +## Custom view +### Attributes | Attribute | Required | Default | Description | |----------------|----------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|