<!--
Copyright (c) 2022 CESNET
This software is released under the MIT License.
https://opensource.org/licenses/MIT
-->
# OARepo UI
This package provides implementation of base UI components for use in dynamic (React JS) & static (Jinja) pages and
functions to render layouts from model configuration.
## Usage
### JinjaX
See also [JinjaX documentation](https://jinjax.scaletti.dev/).
Oarepo builds its static UI pages on top of the JinjaX library.
To load a Jinja application, a JinjaX component is expected on the input.
The relative path to the component is taken from the configuration
Components by default accept record metadata, ui definition and layout definition as parameters.
To work with parameters within components, you need to define them in the template in the way described in the JinjaX documentation.
### Examples
Example of component specification in config:
```python
templates = {
"detail": "DetailPage",
"search": "SearchPage"
}
```
Example of possible contents of the DetailPage component, contained inside `templates/DetailPage.jinja`
```json
{#def metadata, ui, layout #}
{% extends "oarepo_ui/detail.html" %}
{%- block head_links %}
{{ super() }}
{{ webpack['docs_app_components.js']}}
{{ webpack['docs_app_components.css']}}
{%- endblock %}
{% block record_main_content %}
<Main metadata={{metadata}}></Main>
{% endblock %}
{% block record_sidebar %}
<Sidebar metadata={{metadata}}></Sidebar>
{% endblock %}
```
Sample of possible contents of Main component:
```json
{#def metadata, ui, layout #}
<h1 style="margin-bottom: 1em">{{ metadata.title }}</h1>
<dl class="ui very basic table">
<Field label="accessibility">{{metadata.accessibility}}</Field>
```
You can also namespace your ui components, by using dot notation:
```python
templates = {
"detail": "myrepo.DetailPage",
"search": "myrepo.SearchPage"
}
```
Then, the component will be loaded from the `templates/myrepo/DetailPage.jinja` file.
#### JinjaX components
Within the Oarepo-ui library, basic components are defined in the `templates` folder.
### React
To render a custom layout in a React app (e. g. records search result page), this package provides the `useLayout` hook and an entrypoint
for bootstrapping [Search UI](https://github.com/inveniosoftware/invenio-search-ui) app. In your `search.html` template, you can use it like this:
```jinja
{%- extends config.BASE_TEMPLATE %}
{%- block javascript %}
{{ super() }}
{# imports oarepo-ui JS libraries to be used on page #}
{{ webpack['oarepo_ui.js'] }}
{# boots Invenio-Search-UI based search app, with dynamic UI widgets provided by oarepo-ui #}
{{ webpack['oarepo_ui_search.js'] }}
{%- endblock %}
{# ... #}
<div class="ui container">
{# provides a DOM root element for the Search UI to be mounted into #}
<div data-invenio-search-config='{{ search_app_oarepo_config(app_id="oarepo-search") | tojson }}'></div>
</div>
```
Next you will need to register an app context processor named `search_app_oarepo_config` and register it
to blueprint handling the `search.html` template route. In the context processor, you can provide your
own layout configuration for different parts of UI to be used by `oarepo-ui` libs to generate user interface widgets.
```python
def create_blueprint(app):
"""Blueprint for the routes and resources."""
blueprint = Blueprint(
"your-app",
__name__,
template_folder="templates",
static_folder="static",
)
blueprint.add_url_rule("/", view_func=search)
blueprint.app_context_processor(search_app_context)
return blueprint
def search():
"""Search template."""
return render_template('your-app/search.html')
def search_app_context():
"""Search app context processor."""
return {
"search_app_oarepo_config": partial(
search_app_config,
"OAREPO_SEARCH",
[], #current_app.config["OAREPO_FACETS"],1
current_app.config["OAREPO_SORT_OPTIONS"],
endpoint="/api/your-records",
headers={"Accept": "application/json"},
overrides={
"layoutOptions": {
"listView": True,
"gridView": False,
"ResultsList": {
"item": {
"component": 'segment',
"children": [{
"component": "header",
"dataField": "metadata.title"
}]
}
}
}
}
)
}
```
In your `invenio.cfg`, customize the general search app settings:
```python
OAREPO_SEARCH = {
"facets": [],
"sort": ["bestmatch", "newest", "oldest", "version"],
}
OAREPO_SORT_OPTIONS = {
"bestmatch": dict(
title=_("Best match"),
fields=["_score"], # search defaults to desc on `_score` field
),
"newest": dict(
title=_("Newest"),
fields=["-created"],
),
"oldest": dict(
title=_("Oldest"),
fields=["created"],
),
"version": dict(
title=_("Version"),
fields=["-versions.index"],
),
"updated-desc": dict(
title=_("Recently updated"),
fields=["-updated"],
),
"updated-asc": dict(
title=_("Least recently updated"),
fields=["updated"],
),
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/oarepo/oarepo-ui",
"name": "oarepo-ui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "oarepo ui",
"author": "Mirek Simek",
"author_email": "miroslav.simek@vscht.cz",
"download_url": "https://files.pythonhosted.org/packages/00/d4/9763d0e5346325f8488a59c5306b82f0fadd6b247116378370f5d92701d5/oarepo_ui-5.2.25.tar.gz",
"platform": "any",
"description": "<!--\n Copyright (c) 2022 CESNET\n\n This software is released under the MIT License.\n https://opensource.org/licenses/MIT\n-->\n\n# OARepo UI\n\nThis package provides implementation of base UI components for use in dynamic (React JS) & static (Jinja) pages and\nfunctions to render layouts from model configuration.\n\n## Usage\n\n### JinjaX\n\nSee also [JinjaX documentation](https://jinjax.scaletti.dev/).\n\nOarepo builds its static UI pages on top of the JinjaX library.\nTo load a Jinja application, a JinjaX component is expected on the input. \nThe relative path to the component is taken from the configuration\n\nComponents by default accept record metadata, ui definition and layout definition as parameters.\nTo work with parameters within components, you need to define them in the template in the way described in the JinjaX documentation.\n\n### Examples\n\nExample of component specification in config:\n\n```python\ntemplates = {\n \"detail\": \"DetailPage\",\n \"search\": \"SearchPage\"\n }\n```\n\nExample of possible contents of the DetailPage component, contained inside `templates/DetailPage.jinja`\n\n```json\n{#def metadata, ui, layout #}\n{% extends \"oarepo_ui/detail.html\" %}\n\n{%- block head_links %}\n\n{{ super() }}\n{{ webpack['docs_app_components.js']}}\n{{ webpack['docs_app_components.css']}}\n\n{%- endblock %}\n\n{% block record_main_content %}\n <Main metadata={{metadata}}></Main>\n{% endblock %}\n\n{% block record_sidebar %}\n <Sidebar metadata={{metadata}}></Sidebar>\n{% endblock %}\n```\n\n\nSample of possible contents of Main component:\n```json\n{#def metadata, ui, layout #}\n<h1 style=\"margin-bottom: 1em\">{{ metadata.title }}</h1>\n<dl class=\"ui very basic table\">\n<Field label=\"accessibility\">{{metadata.accessibility}}</Field>\n\n```\n\nYou can also namespace your ui components, by using dot notation:\n\n```python\ntemplates = {\n \"detail\": \"myrepo.DetailPage\",\n \"search\": \"myrepo.SearchPage\"\n }\n```\n\nThen, the component will be loaded from the `templates/myrepo/DetailPage.jinja` file.\n\n\n#### JinjaX components\n\nWithin the Oarepo-ui library, basic components are defined in the `templates` folder.\n\n### React\n\nTo render a custom layout in a React app (e. g. records search result page), this package provides the `useLayout` hook and an entrypoint\nfor bootstrapping [Search UI](https://github.com/inveniosoftware/invenio-search-ui) app. In your `search.html` template, you can use it like this:\n\n```jinja\n{%- extends config.BASE_TEMPLATE %}\n\n{%- block javascript %}\n {{ super() }}\n {# imports oarepo-ui JS libraries to be used on page #}\n {{ webpack['oarepo_ui.js'] }}\n {# boots Invenio-Search-UI based search app, with dynamic UI widgets provided by oarepo-ui #}\n {{ webpack['oarepo_ui_search.js'] }}\n{%- endblock %}\n\n{# ... #}\n\n<div class=\"ui container\">\n {# provides a DOM root element for the Search UI to be mounted into #}\n <div data-invenio-search-config='{{ search_app_oarepo_config(app_id=\"oarepo-search\") | tojson }}'></div>\n</div>\n```\n\nNext you will need to register an app context processor named `search_app_oarepo_config` and register it\nto blueprint handling the `search.html` template route. In the context processor, you can provide your\nown layout configuration for different parts of UI to be used by `oarepo-ui` libs to generate user interface widgets.\n\n```python\ndef create_blueprint(app):\n \"\"\"Blueprint for the routes and resources.\"\"\"\n blueprint = Blueprint(\n \"your-app\",\n __name__,\n template_folder=\"templates\",\n static_folder=\"static\",\n )\n\n blueprint.add_url_rule(\"/\", view_func=search)\n blueprint.app_context_processor(search_app_context)\n return blueprint\n\n\ndef search():\n \"\"\"Search template.\"\"\"\n return render_template('your-app/search.html')\n\ndef search_app_context():\n \"\"\"Search app context processor.\"\"\"\n return {\n \"search_app_oarepo_config\": partial(\n search_app_config,\n \"OAREPO_SEARCH\",\n [], #current_app.config[\"OAREPO_FACETS\"],1\n current_app.config[\"OAREPO_SORT_OPTIONS\"],\n endpoint=\"/api/your-records\",\n headers={\"Accept\": \"application/json\"},\n overrides={\n \"layoutOptions\": {\n \"listView\": True,\n \"gridView\": False,\n \"ResultsList\": {\n \"item\": {\n \"component\": 'segment',\n \"children\": [{\n \"component\": \"header\",\n \"dataField\": \"metadata.title\"\n }]\n }\n }\n }\n }\n )\n }\n```\n\nIn your `invenio.cfg`, customize the general search app settings:\n\n```python\nOAREPO_SEARCH = {\n \"facets\": [],\n \"sort\": [\"bestmatch\", \"newest\", \"oldest\", \"version\"],\n}\n\nOAREPO_SORT_OPTIONS = {\n \"bestmatch\": dict(\n title=_(\"Best match\"),\n fields=[\"_score\"], # search defaults to desc on `_score` field\n ),\n \"newest\": dict(\n title=_(\"Newest\"),\n fields=[\"-created\"],\n ),\n \"oldest\": dict(\n title=_(\"Oldest\"),\n fields=[\"created\"],\n ),\n \"version\": dict(\n title=_(\"Version\"),\n fields=[\"-versions.index\"],\n ),\n \"updated-desc\": dict(\n title=_(\"Recently updated\"),\n fields=[\"-updated\"],\n ),\n \"updated-asc\": dict(\n title=_(\"Least recently updated\"),\n fields=[\"updated\"],\n ),\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "UI module for invenio 3.5+",
"version": "5.2.25",
"project_urls": {
"Homepage": "https://github.com/oarepo/oarepo-ui"
},
"split_keywords": [
"oarepo",
"ui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e46369349f630a797071e692006bf653a165dd220101a21cf5b6b0d8b3f480f7",
"md5": "81652636757a8bc0031419c7ac32b082",
"sha256": "b69359d556505ab35a708ac3dc5e596a718bcecab1bed54266456adefe738cc4"
},
"downloads": -1,
"filename": "oarepo_ui-5.2.25-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "81652636757a8bc0031419c7ac32b082",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.10",
"size": 217743,
"upload_time": "2024-11-15T14:52:20",
"upload_time_iso_8601": "2024-11-15T14:52:20.697941Z",
"url": "https://files.pythonhosted.org/packages/e4/63/69349f630a797071e692006bf653a165dd220101a21cf5b6b0d8b3f480f7/oarepo_ui-5.2.25-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00d49763d0e5346325f8488a59c5306b82f0fadd6b247116378370f5d92701d5",
"md5": "ef471bb1904b5457cffc8d05e505ab4a",
"sha256": "20d43ae92f028b516c3adf14e968933dd5762c7df3add5a30bc32edc1f979192"
},
"downloads": -1,
"filename": "oarepo_ui-5.2.25.tar.gz",
"has_sig": false,
"md5_digest": "ef471bb1904b5457cffc8d05e505ab4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 120714,
"upload_time": "2024-11-15T14:52:22",
"upload_time_iso_8601": "2024-11-15T14:52:22.414961Z",
"url": "https://files.pythonhosted.org/packages/00/d4/9763d0e5346325f8488a59c5306b82f0fadd6b247116378370f5d92701d5/oarepo_ui-5.2.25.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 14:52:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oarepo",
"github_project": "oarepo-ui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "oarepo-ui"
}
JSON
