[ckan-discuss] Basic orientation to CKAN

[Sean Hammond]

> Thanks for this, it goes a long way to getting me started.

Great!

> Just a couple of quick follow-up questions: 1) How/where is menu/url
> management implemented, for instance if I wanted to add or disable a
> URL-based feature (or page or function) such a "About" (/about) or
> "Groups" (/group)?

This happens in ckan/config/routing.py which contains routing
definitions that define with URLs get routed to which servers. It uses
routes.groovie.org. You could add, edit or delete routes here. But
rather than customising the CKAN source code itself, it's probably
better to maintain a custom CKAN extension and use CKAN's IRoutes plugin
interface to customise the routing. You can find IRoutes documented on
this page:

docs.ckan.org/en/ckan-1.7.1/writing-extensions.html

For example, for a custom CKAN site I was working on recently we wanted
to redirect the dataset search page so that it appears as the front
page, and were able to do that from an extension using IRoutes:

https://github.com/NewAmsterdamIdeas/ckanext-cmap/blob/master/ckanext/cmap/routing.py

>    2) In the Genshi templates I notice pervasive use of objects and
>    properties (e.g., h.url_for_static) and functions (e.g., page_title()
>    ). Are these specific to CKAN, and if so are the they documented
>    somewhere, or are they part of genshi, or pylons or something else, or
>    a mix?

These are specific to CKAN. The ones that start with h. are defined in
ckan/lib/helpers.py, which contains helper functions for use by CKAN
templates. CKAN extensions can also add their own helper functions using
the ITemplateHelpers plugin interface, and can then use these helper
functions from the templates.

Functions that don't start with h like page_title() are Genshi functions
which are defined somewhere in ckan/templates/. For example,
layout_base.html uses ${page_title()}. If you search the template files,
you'll find that lots of them contain definitions like:

<py:def function="page_title">Reset password</py:def>

layout_base.html is a base template file that is not directly rendered
by any CKAN controller, but rather is included by other templates that
are based on it. These templates define page_title() with a py:def like
the one above. So when the reset password page is being rendered,
layout_base.html will get "Reset password" when it calls page_title(),
when the dataset page is being rendered it will get something else, etc.

There are also some Genshi functions defined in
ckan/templates/_util.html, these can be used by the templates directly,
e.g. ${tag_list(tags)} etc. but the template file has to import the
_util.html file first with a line like

    <xi:include href="../_util.html"/>

In general if you see something such as a function used in a Genshi
template file that is not defined anywhere in that file, look for it in
the files that it includes.