Add docs for updated route names and css (#915)

OnroerendErfgoed · Aug 12, 2024 · 7b05cf6 · 7b05cf6
1 parent 43bee21
commit 7b05cf6
Show file tree

Hide file tree

Showing 2 changed files with 132 additions and 31 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -3,6 +3,11 @@
 
 - ConceptVisitLog has an integer concept_id in the ConceptVisitLog class #906
 - skosprovider route /expand does not work #903
+
+  **If you are using custom pages or custom views with atramhasis routes, please see**
+  `the docs <https://atramhasis.readthedocs.io/en/latest/customisation.html#update-to-2-1-1>`_
+  **for a list of route name changes**
+
 - Manual ID text box not writable #902
 
 

diff --git a/docs/source/customisation.rst b/docs/source/customisation.rst
@@ -513,38 +513,85 @@ Changing the CSS
 
 Out of the box, Atramhasis, comes with the Zurb Foundation framework. We have
 created a custom style for this framework, but as always you are free to modify
-this style. Your custom instance contains a few extension points that make it
-easy to override and change style elements without having to rewrite to much
-css. All style related files can be found in the :file:`my_thesaurus/static`
-folder. This project's CSS is being maintained and generated by `Compass`. You
-will find a :file:`scss` folder that contains three files that can be used for
-easy customisations: :file:`_my_thesaurus-settings.scss`, 
-:file:`_my_thesaurus.scss` and :file:`_my_thesaurus-admin.scss`. The first file
-is a settings file that allows you to override a lot of variables that are used
-in generating the css. Suppose you want to override the default row width and
-the default font. You would change :file:`_my_thesarus-settings.scss` to the
-following:
+this style.
 
-.. code-block:: scss
+**Note:**
+This guide will use ``compass`` because atramhasis is built with it. But beware
+compass is no longer actively maintained and should be considered depreciated.
 
-    // Custom SASS code for my_thesaurus
+To override and hook your custom (s)css into the app follow these steps:
 
-    $row-width: rem-calc(1140);
-    $body-font-family: "museo-sans", "Open Sans", "Helvetica", Helvetica, Arial, sans-serif;
+#. Create a ``static`` folder (the name can be anything, but adjust accordingly)
 
-To have you changes take effect, you need to recompile the scss files and
-restart your webserver.
+   .. code-block:: sh
 
-.. code-block:: bash
+       mkdir static
+
+#. Inside of the ``static`` folder, setup the scss directories
+
+   .. code-block:: sh
+
+       cd static
+       compass init
+
+#. in ``config.rb`` (generated in the previous step) on top write
+
+   .. code-block:: ruby
+
+       atramhasis_static_path = "#{ENV["VIRTUAL_ENV"]}/lib/python3.10/site-packages/atramhasis/static"
+       add_import_path "#{atramhasis_static_path}/scss/"
+       add_import_path "#{atramhasis_static_path}/node_modules/foundation-sites/scss"
+       add_import_path "#{atramhasis_static_path}/node_modules/font-awesome/scss"
+
+   **Note**: we use the ``ENV["VIRTUAL_ENV"]`` variable which would mean that for future
+   ``compass compile`` steps you'd need to be in the python virtual environment.
+   If you do not want this. Write the absolute path.
+
+   **Note**: ``python3.10`` on line one may be different for you.
+
+#. Add your own scss file in the scss directory. In this example we'll call it
+   ``my_app.scss`` and we'll override the main font color and font family.
+
+   .. code-block:: scss
+
+       @import "atramhasis/atramhasis-settings";
+       $body-font-color: #20ae3c;
+       $body-font-family: "Comic Sans MS", "Comic Sans";
+       @import "app";
+
+#. Compile the scss to css
 
-    $ compass compile
-        write css/app-admin.css
-        write css/app.css
+   .. code-block:: bash
 
-The other two files, :file:`_my_thesaurus.scss` and
-:file:`_my_thesaurus-admin.scss` are the final scss files loaded before
-compiling them and can be used to overwrite things in the public or admin
-interface.
+       compass compile
+
+#. Lastly, add your new css to the pyramid configuration and restart the application.
+
+   .. code-block:: python
+
+       config.override_asset(
+           to_override="atramhasis:static/css/app.css",
+           override_with="myproject:static/stylesheets/my_app.css",
+       )
+
+
+Further notes regarding SCSS
+............................
+
+In the above example, ``atramhasis/atramhasis-settings`` is used. To know which files
+are possible you best look at `Github <https://github.com/OnroerendErfgoed/atramhasis/tree/master/atramhasis/static/scss>`_
+The settings file will contain most of the variables should you wish to edit any.
+
+The most commonly used files for scss overriding will be:
+
+* ``atramhasis/atramhasis-settings`` -- which contains most variables.
+* ``app.scss`` -- which generates ``app.css``, used by the public interface
+* ``app-admin.scss`` -- which generates ``app-admin.css``, used by the admin interface
+
+| In the above example we wanted to change the main ``app.css`` so we imported ``app``
+  to recreate the entire ``app.css``. And **before** that import we edited the variables.
+| To prevent atramhasis of overriding the variables we just overrided ourselves, we
+  made sure to import ``atramhasis/atramhasis-settings`` first.
 
 
 .. _security:
@@ -1060,17 +1107,19 @@ You can change the default session factory in the __init__.py file within the lo
 ensure you pass the settings variable to the load_app function from within the main() function.
 
 .. code-block:: python
-    def load_app(config, settings):
-        # Override default session factory
-        from pyramid.session import SignedCookieSessionFactory
-        atramhasis_session_factory = SignedCookieSessionFactory(settings['atramhasis.session_factory.secret'])
-        config.set_session_factory(atramhasis_session_factory)
+
+   def load_app(config, settings):
+       # Override default session factory
+       from pyramid.session import SignedCookieSessionFactory
+       atramhasis_session_factory = SignedCookieSessionFactory(settings['atramhasis.session_factory.secret'])
+       config.set_session_factory(atramhasis_session_factory)
 
 .. _upgrading_providers:
    
 Updating an older installation of Atramhasis
 ============================================
-
+Update to 2.0.0
+---------------
 If you are running an older installation of Atramhasis, it's important to reconfigure
 how providers are created. In pre-2.0.0 versions, providers were created by writing a
 bit of code. However, since version 2.0.0, they are created through the UI or the REST
@@ -1135,6 +1184,53 @@ through code in this file. Your final code should looks somewhat like this:
         return registry
 
 
+Update to 2.1.1
+---------------
+A route cleanup has happened because atramhasis was duplicating a lot of pre-existing
+pyramid routes and these duplicate routes could cause issues in certain cases.
+
+Atramhasis no longer duplicates routes, which means the names of some routes may
+be different now. Below is a table of all old and new route names.
+
+A lot of routes which used to have different names, now share the same name. This is
+because they differ in accept headers and/or HTTP methods which are no longer bound
+to the route, but rather on the view.
+
+.. csv-table:: Route name migration
+    :header: "Old route name", "new route name"
+
+    "concept", "skosprovider.c"
+    "conceptscheme", "skosprovider.conceptscheme"
+    "search_result", "skosprovider.conceptscheme.cs"
+    "search_result_export", "skosprovider.conceptscheme.csv"
+    "atramhasis.get_concept", "skosprovider.c"
+    "atramhasis.add_concept", "skosprovider.conceptscheme.cs"
+    "atramhasis.edit_concept", "skosprovider.c"
+    "atramhasis.delete_concept", "skosprovider.c"
+    "scheme_root", "<DELETED>"
+    "atramhasis.get_conceptscheme", "skosprovider.conceptscheme"
+    "atramhasis.get_conceptschemes", "skosprovider.conceptschemes"
+    "atramhasis.edit_conceptscheme", "skosprovider.conceptscheme"
+    "atramhasis.rdf_full_export", "skosprovider.conceptscheme.cs"
+    "atramhasis.rdf_full_export_ext", "skosprovider.conceptscheme.cs.rdf"
+    "atramhasis.rdf_full_export_turtle", "skosprovider.conceptscheme.cs"
+    "atramhasis.rdf_full_export_turtle_x", "skosprovider.conceptscheme.cs"
+    "atramhasis.rdf_full_export_turtle_ext", "skosprovider.conceptscheme.cs.ttl"
+    "atramhasis.rdf_conceptscheme_export", "skosprovider.conceptscheme"
+    "atramhasis.rdf_conceptscheme_export_ext", "skosprovider.conceptscheme.rdf"
+    "atramhasis.rdf_conceptscheme_export_turtle", "skosprovider.conceptscheme"
+    "atramhasis.rdf_conceptscheme_export_turtle_x", "skosprovider.conceptscheme"
+    "atramhasis.rdf_conceptscheme_export_turtle_ext", "skosprovider.conceptscheme.ttl"
+    "atramhasis.rdf_conceptscheme_jsonld", "skosprovider.conceptscheme"
+    "atramhasis.rdf_conceptscheme_jsonld_ext", "skosprovider.conceptscheme.jsonld"
+    "atramhasis.rdf_individual_export", "skosprovider.c"
+    "atramhasis.rdf_individual_export_ext", "skosprovider.c.rdf"
+    "atramhasis.rdf_individual_jsonld", "skosprovider.c"
+    "atramhasis.rdf_individual_jsonld_ext", "skosprovider.c.jsonld"
+    "atramhasis.rdf_individual_export_turtle", "skosprovider.c"
+    "atramhasis.rdf_individual_export_turtle_x", "skosprovider.c"
+    "atramhasis.rdf_individual_export_turtle_ext", "skosprovider.c.ttl"
+
 Application settings
 ====================
 These are settings you can use to change the atramhasis behaviour.