Open dev-marcoC opened 4 days ago
Hi Marco, to customize the front-end template in CKAN using the ckan-docker setup, the best approach is to create a CKAN extension where you can override templates, add custom styles, and implement any additional frontend logic you need. Here are the basic steps for developing a custom theme in CKAN:
Set up your CKAN extension To customize the front-end, you'll need to create an extension. CKAN allows overriding its default templates by creating an extension that loads your custom templates, styles, assets, helpers, etc. You can follow these basic steps:
Create a CKAN extension: You can use the development mode and ckan-docker
documentation.
Structure of the extension: The extension will have the following structure:
ckanext-yourtheme/
├── ckanext/
│ └── yourtheme/
│ ├── assets
│ │ └── css/
│ │ └── js/
│ ├── public
│ └── templates/
│ └── (template overrides here)
├── setup.py
└── README.md
Override CKAN templates: To customize the frontend, place your templates into the templates directory of your extension. CKAN's core templates are located in the ckan/templates
folder. You can override any of the by creating a file with the same name in your extension or by creating news, in your extension: Customizing CKAN templates
Load your extension: Once your extension is ready, enable it by adding it to the CKAN plugins in your ckan.ini configuration file:
ckan.plugins = yourtheme
Modify Templates
For example, if you want to customize the homepage (home/index.html
), you
would copy the default index.html from the core CKAN templates into your
extension’s templates directory and then modify it as needed. Make your changes in this file, and CKAN will use it instead of the default one.
Use offical docs & existing Extensions as Reference The official CKAN documentation is really good and is always a great reference for further development:
For reference, you can check out some of our existing CKAN extensions that customize the front end:
ckanext-schemingdcat
- This extension demonstrates how to customize forms and
layouts using custom templates and much more.
ckanext-fototeca
- Another basic example of customizing CKAN’s frontend and backend by extending templates and functionality.
These repositories will give you a good idea of how to structure your code, override templates, and add custom logic.
Stack Technologies for CKAN Front-End CKAN uses a stack of technologies for its frontend, including:
You'll primarily be working with Jinja2 templates to modify the HTML and extend CKAN’s interface. Additionally, you can customize the look and feel with CSS and add interactivity using JavaScript.
Cheers!
Hi, I tried to add a custom plugin from a git repository. I followed all your instructions, but the result is always the same.
My plugin doesn't override the scheming template, and my team and I can't figure out why. Could you help us out?
We have verified that the custom plugin is correctly loaded inside the ckan_dev container in the src_extensions folder, but the template located in /srv/app/src/ckan/ckan/templates is still the one from scheming.
Hi, I tried to add a custom plugin from a git repository. I followed all your instructions, but the result is always the same.
My plugin doesn't override the scheming template, and my team and I can't figure out why. Could you help us out?
We have verified that the custom plugin is correctly loaded inside the ckan_dev container in the src_extensions folder, but the template located in /srv/app/src/ckan/ckan/templates is still the one from scheming.
I try to help you, ckanext-scheming
is a bit unique in that you need to leverage its schema system but still want to override its templates. For this, you have to load scheming in your src/
directory - development mode- but avoid including it in the active plugin list. Additionally, you need to implement and inherit from scheming interfaces to ensure you can both use the schema functionality and override the templates correctly.
Here’s how you can adjust your setup:
Make sure the scheming extension is available in your src/
folder. You’ve probably already done this.
Do not load scheming in the ckan.plugins list (CKAN__PLUGINS
)
In your ckan.ini, ensure that scheming is not explicitly listed in the ckan.plugins section. You’ll only load your custom plugin that inherits from scheming.
Example:
ckan.plugins = your_custom_plugin
SchemingDatasetsPlugin
class, as you pointed out. This will allow you to inherit the schema functionality while overriding the templates. Here’s an example structure for your plugin from our ckanext-schemingdcat
:from ckanext.scheming.plugins import SchemingDatasetsPlugin
import ckan.plugins as plugins
class CustomSchemingPlugin(SchemingDatasetsPlugin):
plugins.implements(plugins.IConfigurer)
plugins.implements(plugins.IConfigurable)
plugins.implements(plugins.ITemplateHelpers)
plugins.implements(plugins.IDatasetForm, inherit=True)
plugins.implements(plugins.IActions)
plugins.implements(plugins.IValidators)
def read_template(self):
# Override the default read template
return "your_custom_plugin/package/read.html"
def resource_template(self):
# Override the default resource template
return "your_custom_plugin/package/resource_read.html"
def package_form(self):
return "your_custom_plugin/package/snippets/package_form.html"
def resource_form(self):
return "your_custom_plugin/package/snippets/resource_form.html"
This approach ensures that CKAN will use your custom templates (your_custom_plugin/templates/
) instead of the ones from scheming.
update_config
function in your plugin class:def update_config(self, config):
# Add the custom templates directory to CKAN's search path
plugins.toolkit.add_template_directory(config, 'templates')
If you run into any more issues, feel free to reach out.
Hello @mjanez,
I'm currently working with the ckan-docker setup and would like to customize the front-end template. Could you please guide me on how to proceed with modifying the template? Any help or pointers would be greatly appreciated.
Thank you for your time and assistance!
Best regards, Marco