core.theme
==========

.. py:module:: core.theme

.. autoapi-nested-parse::

   onegov.core provides very basic theming support with the following
   features:

   * Themes can be external to onegov.core
   * Themes can be used by onegov.core applications
   * Themes can be compiled and the result is shared between applications

   Themes are not meant to be switched at runtime though, they are statically
   defined by the applications. The idea is to have a way to share themes
   between applications, not to have powerful skinning features where the user
   can change the theme at any given time.

   A theme is basically a CSS file. There is no way to define images/icons
   and so on. The only way to do that is to include the image in the css
   file (which is not *that* crazy of an idea anyway).

   To write a theme, create a class providing the properties/methods of
   :class:`Theme`.

   To use a theme you need to define the following setting::

       @App.setting(section='core', name='theme')
       def get_theme():
           return Theme()

   To override the options passed to a theme, override the following function
   in your application class::

       class App(Framework):

           @property
           def theme_options(self):
               return {'background': 'red'}

   To include the theme in your html, call the following function in your
   template::

       <link rel="stylesheet" type="text/css" href="${request.theme_link}">

   Note that for the theme to work you need to define a filestorage. See
   :meth:`onegov.core.framework.Framework.configure_application`.



Classes
-------

.. autoapisummary::

   core.theme.Theme
   core.theme.ThemeFile


Functions
---------

.. autoapisummary::

   core.theme.get_filename
   core.theme.compile
   core.theme.get_theme
   core.theme.get_themestorage_file


Module Contents
---------------

.. py:class:: Theme

   Describres a onegov.core theme.

   A onegov theme is any kind of compiled or non-compiled css file. The core
   expects a single css file that stays the same as long as the same options
   are passed to the compile function.

   Some framework based themes might required the ability to serve
   javascript at the same time. This is not done here. Such javascript
   needs to be manually included through webassets.

   This is due to the fact that onegov themes are not meant to be switched
   around. An application will chose one theme and stick with it (and
   test against it).


   .. py:attribute:: version
      :value: '2025.17'



   .. py:property:: name
      :type: str

      :abstractmethod:


      The name of the theme, must be unique. 



   .. py:property:: default_options
      :type: dict[str, Any]

      :abstractmethod:


      The default options of the theme, will be overwritten by options
      passed to :meth:`compile`.




   .. py:method:: compile(options: dict[str, Any] | None = None) -> str
      :abstractmethod:


      Returns a single css that represents the theme. 



.. py:function:: get_filename(theme: Theme, options: dict[str, Any] | None = None) -> str

   Returns a unique filename for the given theme and options. 


.. py:function:: compile(storage: fs.base.FS | fs.base.SubFS[fs.base.FS], theme: Theme, options: dict[str, Any] | None = None, force: bool = False) -> str

   Generates a theme and stores it in the filestorage, returning the
   path to the theme.

   If the theme already exists and doesn't need recompiling, it will not
   compile the theme again.

   :storage:
       The Pyfilesystem storage to store the files in.

   :theme:
       The theme instance that should be compiled.

   :options:
       The hashable options passed to the theme.

   :force:
       If true, the compilation is done in any case.



.. py:function:: get_theme() -> Theme | None

   Defines the default theme, which is no theme. 


.. py:class:: ThemeFile(path: str)

   Bases: :py:obj:`onegov.core.filestorage.FilestorageFile`


   Defines a static file served by the application. The difference
   between this and :class:`onegov.core.static.StaticFile` is the storage.

   Filestorage files are stored per application_id locally or on the cloud.
   Static files are the same for the whole application class and they are
   deployed statically. That means they are not content, but part of
   the distribution.

   Note that this is only used if the file is local. Files stored in the
   filestorage should be linked using
   :meth:`onegov.core.request.CoreRequest.filestorage_link`, which might
   result in a local path, for which this class is used. Or it might result in
   a remote path that is served by some different webserver.



   .. py:attribute:: storage
      :value: 'themestorage'



.. py:function:: get_themestorage_file(app: onegov.core.framework.Framework, absorb: str) -> ThemeFile | None

   Serves the theme files.