Theming guide

The following sections will teach you how to customize the content and appearance of CKAN pages by developing your own CKAN themes.

See also

Getting started

If you just want to do some simple customizations such as changing the title of your CKAN site, or making some small CSS customizations, Getting started documents some simple configuration settings you can use.

Note

Before you can start developing a CKAN theme, you’ll need a working source install of CKAN on your system. If you don’t have a CKAN source install already, follow the instructions in Installing CKAN from source before continuing.

Note

CKAN theme development is a technical topic, for web developers. The tutorials below assume basic knowledge of:

• The Python programming language

• HTML

• CSS

• JavaScript

We also recommend familiarizing yourself with:

• Jinja2 templates

• Bootstrap

• jQuery

Note

Starting from CKAN version 2.10 the Bootstrap version used in the default CKAN theme is Bootstrap 5. For backwards compatibility, Bootstrap 3 templates will be included in CKAN core for a few versions, but they will be eventually removed so you are encouraged to update your custom theme to use Bootstrap 5. You can select which set of templates to use (Bootstrap 5 or 3) by using the ckan.base_public_folder and ckan.base_templates_folder configuration options.

• Customizing CKAN’s templates
  • Creating a CKAN extension
  • Replacing a default template file
  • Jinja2
  • Extending templates with {% ckan_extends %}
  • Replacing template blocks with {% block %}
  • Extending parent blocks with Jinja’s {{ super() }}
  • Template helper functions
  • Adding your own template helper functions
  • Template snippets
  • Adding your own template snippets
  • HTML tags and CSS classes
  • Accessing custom config settings from templates
• Adding static files
• Customizing CKAN’s CSS
• Adding CSS and JavaScript files using Webassets
  • X-Sendfile
• Customizing CKAN’s JavaScript
  • Overview
  • Initializing a JavaScript module
  • this.options and this.el
  • Default values for options
  • Ajax, event handling and CKAN’s JavaScript sandbox
  • Error handling
  • Pubsub
  • jQuery plugins
  • Internationalization
  • Testing JavaScript modules
• Creating dynamic user interfaces with htmx
  • Overview
  • Implementing new features with htmx
  • 2. Accesing to HTMX request headers in CKAN
  • 3. htmx examples
• Best practices for writing CKAN themes
  • Don’t use c
  • Use url_for()
  • Use {% trans %}, {% pluralize %}, _() and ungettext()
  • Avoid name clashes
  • JavaScript modules should have docstrings
  • JavaScript modules should unsubscribe from events in teardown()
  • Don’t overuse pubsub
  • Use {% snippet %}, not {% include %}
  • Snippets should have docstrings
• Custom Jinja2 tags reference
• Variables and functions available to templates
  • tmpl_context
  • c
  • app_globals
  • g
  • h
  • request
  • response
  • session
  • _()
  • N_()
  • ungettext()
  • translator
  • actions
• Objects and methods available to JavaScript modules
• Template helper functions reference
  • HelperAttributeDict
  • literal
  • core_helper()
  • chained_helper()
  • redirect_to()
  • get_site_protocol_and_host()
  • url_for()
  • url_for_static()
  • url_for_static_or_external()
  • is_url()
  • url_is_local()
  • full_current_url()
  • current_url()
  • lang()
  • strxfrm()
  • ckan_version()
  • lang_native_name()
  • is_rtl_language()
  • get_rtl_theme()
  • flash_notice()
  • flash_error()
  • flash_success()
  • get_flashed_messages()
  • link_to()
  • nav_link()
  • build_nav_main()
  • build_nav_icon()
  • build_nav()
  • map_pylons_to_flask_route_name()
  • default_group_type()
  • default_package_type()
  • humanize_entity_type()
  • get_facet_items_dict()
  • has_more_facets()
  • get_param_int()
  • sorted_extras()
  • check_access()
  • linked_user()
  • group_name_to_title()
  • truncate()
  • markdown_extract()
  • dict_list_reduce()
  • gravatar()
  • sanitize_url()
  • user_image()
  • pager_url()
  • get_page_number()
  • get_display_timezone()
  • render_datetime()
  • date_str_to_datetime()
  • parse_rfc_2822_date()
  • time_ago_from_timestamp()
  • dataset_display_name()
  • dataset_link()
  • resource_display_name()
  • resource_link()
  • tag_link()
  • group_link()
  • organization_link()
  • dump_json()
  • snippet()
  • convert_to_dict()
  • follow_button()
  • follow_count()
  • add_url_param()
  • remove_url_param()
  • debug_inspect()
  • groups_available()
  • organizations_available()
  • member_count()
  • roles_translated()
  • user_in_org_or_group()
  • escape_js()
  • get_pkg_dict_extra()
  • get_request_param()
  • html_auto_link()
  • render_markdown()
  • format_resource_items()
  • get_allowed_view_types()
  • rendered_resource_view()
  • view_resource_url()
  • resource_view_is_filterable()
  • resource_view_get_fields()
  • resource_view_is_iframed()
  • resource_view_icon()
  • resource_view_display_preview()
  • resource_view_full_page()
  • remove_linebreaks()
  • list_dict_filter()
  • SI_number_span()
  • uploads_enabled()
  • get_featured_organizations()
  • get_featured_groups()
  • featured_group_org()
  • resource_formats_default_file()
  • resource_formats()
  • unified_resource_format()
  • resource_url_type()
  • check_config_permission()
  • get_organization()
  • license_options()
  • get_translated()
  • facets()
  • mail_to()
  • clean_html()
  • load_plugin_helpers()
  • sanitize_id()
  • get_collaborators()
  • can_update_owner_org()
  • decode_view_request_filters()
  • check_ckan_version()
  • make_login_url()
  • csrf_input()
• Template snippets reference
• JavaScript sandbox reference
• JavaScript API client reference
• CKAN jQuery plugins reference