diff --git a/admin-manual/customization/theming.rst b/admin-manual/customization/theming.rst index e17442af..14e33e6e 100644 --- a/admin-manual/customization/theming.rst +++ b/admin-manual/customization/theming.rst @@ -4,16 +4,22 @@ Theming ======= -AtoM themes can be customized by editing the appropriate css and .php files, or -you can create a custom theme. +AtoM themes can be customized by editing the appropriate css/scss and .php files, +or you can create a custom theme. Please note AtoM 2.7 introduced a new version of the Bootstrap (“BS5”) web -framework, and shipped with a theme based on BS5. Creating a custom theme using -BS5 is slightly different than documented below (which was written using the -original BS2 framework provided in previous versions of AtoM). This -documentation will be updated, but in the meantime it is still possible to -create a custom theme using BS2 using the instructions below. +framework, and shipped with a theme based on BS5. +Bootstrap 2 Deprecation Notice +------------------------------ + +Bootstrap 2 themes have been deprecated and will be removed in a future release. +Please consider switching to a Bootstrap 5 theme. + +.. SEEALSO:: + + * :ref:`Change theme ` + * :ref:`Create a custom theme ` Customize how an AtoM theme looks --------------------------------- @@ -54,23 +60,124 @@ don't have to get your hands too dirty. It's in the details where most of the complexities are found. Dominion is the result of a cyclic process of testing and refining by a large community of users, try not to underestimate that! -AtoM bundles two themes: arDominionPlugin and arArchivesCanadaPlugin. Their -names follow the naming convention of Symfony 1.x plugins, because that is how -themes are implemented in AtoM. You may want to read more about Symfony plugins +AtoM bundles three themes: arDominionPlugin, arDominionB5Plugin and arArchivesCanadaPlugin. +Their names follow the naming convention of Symfony 1.x plugins, because that is +how themes are implemented in AtoM. You may want to read more about Symfony plugins later following `one of their guides `_. -arDominionPlugin is the default theme, i.e. the theme that will be used in a +arDominionB5Plugin is the default theme, i.e. the theme that will be used in a fresh installation. arArchivesCanadaPlugin was developed as an extension of the former and the following instructions will show you how to create your custom theme as we did with arArchivesCanadaPlugin. -Assuming that you already have AtoM installed in your development environment -(you can use our :ref:`Vagrant box `), let's start -building the plugin structure from the command line. Our theme is going to be -called Corcovado (arCorcovadoPlugin). We are going to track its contents with -git and publish them in a remote repository hosted by GitHub so we can enable -others to contribute in the development. The repository is open source so you -can use it for your own reference, see https://github.com/artefactual-labs/atom-theme-corcovado. +.. TIP:: + + The following instructions assume you already have an AtoM development environment set up + locally. If not, we have two development-friendly environments for AtoM - see: + + * :ref:`dev-env-vagrant` + * :ref:`dev-env-compose` + +++++++++++++++++++++++++ +Custom Bootstrap 5 Theme +++++++++++++++++++++++++ + +With the new BS5 framework, creating a custom theme that is an extension +of the default arDominionB5Plugin theme has become significantly easier. A +skeleton for an empty AtoM theme plugin that extends arDominionB5Plugin without +any modifications can be found in this `arThemeB5Plugin repository +`_. + +Additional steps for tarball installations: +******************************************* + +If not already installed, first `download the node.js binary distributuion +`_ and export the PATH variable. + +The tarball is missing three required files for this: + +* :version-ref:`package.json` +* :version-ref:`package-lock.json` +* :version-ref:`webpack.config.js ` + +Copy the above files from the *correct stable branch* +(stable/|version|.x for AtoM |version|) of our `AtoM repo `_. + +Test that everything has been installed correctly: + +.. code-block:: bash + + $ npm install + $ npm run build + +If you encounter any issues at this point, we recommend resolving any issues by +consulting the :ref:`maintenance-troubleshooting` documentation before continuing. + +Let's begin creating our new BS5 Theme: +*************************************** + +.. code-block:: bash + + $ cd ~/atom + $ git clone --depth=1 https://github.com/artefactual-labs/arThemeB5Plugin.git plugins/arCustomThemeB5Plugin + $ rm -rf plugins/arThemeB5Plugin/.git plugins/arB5ThemePlugin/README.md + +Here, we've cloned the repo directly into the `atom/plugins` directory, renaming +the theme to `arCustomThemeB5Plugin`, and removed the git related files. + +.. code-block:: bash + + $ cd plugins/arCustomThemeB5Plugin/config/ + $ mv arThemeB5PluginConfiguration.class.php arCustomThemeB5PluginConfiguration.class.php + +To configure the theme plugin, we've renamed the config filename to match the +plugin name. Next, we need to change the `class name `_ +to match the new config filename (`arCustomThemeB5PluginConfiguration` for this +example). + +Optionally, you can update the theme summary and version within the config file +and change the theme image thumbnail by replacing `arCustomThemeB5Plugin/images/image.png`. + +To change the logo for BS5 themes, add the logo to `plugins/arCustomThemeB5Plugin/images/logo.png`. +Style changes can be made directly to, or linked in, the `main SCSS file `_. +Custom javascripts can be added to the js directory and linked in the `main js file `_. + +For additional functionlity modifications, copy files required into the new `plugins/arCustomThemeB5Plugin` +directory for overwriting. Due to file precedence, when copying files, first +check the `plugins/arDominionB5Plugin` for the required file, and only copy from +`apps/qubit` when the file is not found in `plugins/arDominionB5Plugin`. Files +copied should have the same file path with `plugin/arCustomThemeB5Plugin` replacing +`apps/qubit` or `plugins/arDominionB5Plugin`. + +.. code-block:: bash + + cd ~/atom + npm install + npm run build + +Once you've made all the required changes to your theme, build the theme assets, +and you should now be able to use your new theme! + +.. TIP:: + + If you are still not seeing your changes take effect, remember to + :ref:`clear the Symfony cache ` and your + web browser's cache as well! + +++++++++++++++++++++++++ +Custom Bootstrap 2 Theme +++++++++++++++++++++++++ + +.. NOTE:: + + Bootstrap 2 themes have been deprecated and will be removed in a future + release. Please consider switching to a Bootstrap 5 theme. + +Let's start building the plugin structure from the command line. Our theme is +going to be called Corcovado (arCorcovadoPlugin). We are going to track its +contents with git and publish them in a remote repository hosted by GitHub so we +can enable others to contribute in the development. The repository is open source +so you can use it for your own reference, see https://github.com/artefactual-labs/atom-theme-corcovado. You can also `create your own repository `_. Let's begin to do some real work: diff --git a/admin-manual/installation/ubuntu.rst b/admin-manual/installation/ubuntu.rst index 169ce7b0..d5b728c3 100644 --- a/admin-manual/installation/ubuntu.rst +++ b/admin-manual/installation/ubuntu.rst @@ -301,6 +301,17 @@ For development environments, the dev libraries should also be installed: After downloading the code, you will need to compile the themes files: +Compile Bootstrap 5 Theme Files: +******************************** + +.. code-block:: bash + + sudo npm install + sudo npm run build + +Compile Bootstrap 2 Theme Files: +******************************** + .. code-block:: bash sudo apt install npm make @@ -766,9 +777,16 @@ use. You can access it by entering your base URL into a web browser - the configuring the installer. See :ref:`getting-started-all` for further information on your first steps using AtoM. -If you encounter any issues, we recommend consulting the -:ref:`maintenance-troubleshooting` documentation for suggestions on how to -resolve common errors. +.. TIP:: + + After implementing the above changes during the initial setup, you might need + to :ref:`clear the cache ` and + :ref:`restart PHP-FPM ` for the changes to + take effect. + + If you encounter any other issues, we recommend consulting the + :ref:`maintenance-troubleshooting` documentation for suggestions on how to + resolve common errors. :ref:`Back to top ` diff --git a/admin-manual/installation/upgrading.rst b/admin-manual/installation/upgrading.rst index 71b6f4c1..b26b4a9e 100644 --- a/admin-manual/installation/upgrading.rst +++ b/admin-manual/installation/upgrading.rst @@ -368,9 +368,60 @@ Upgrading with a custom theme plugin If you have developed a custom theme plugin for your application (for more information, see :ref:`customization-custom-theme`), you may need to perform an additional step following an upgrade to ensure that all pages are styled -correctly. Please note that the instructions below are for upgrading a custom -theme that continues to the Bootstrap 2 (“BS2”). Documentation for upgrading to -BS5 will be provided at a later date. +correctly. + ++++++++++++ +Bootstrap 5 ++++++++++++ + +Additional steps for tarball installations: +******************************************* + +If not already installed, first `download the node.js binary distributuion +`_ and export the PATH variable. + +The tarball is missing three required files for this: + +* :version-ref:`package.json` +* :version-ref:`package-lock.json` +* :version-ref:`webpack.config.js ` + +Copy the above files from the *correct stable branch* +(stable/|version|.x for AtoM |version|) of our `AtoM repo `_. + +Test that everything has been installed correctly: + +.. code-block:: bash + + $ npm install + $ npm run build + +If you encounter any issues at this point, we recommend resolving them by +consulting the :ref:`maintenance-troubleshooting` documentation before continuing. + +Rebuild BS5 theme assets: +************************* + +.. code-block:: bash + + cd ~/atom + npm install + npm run build + +.. TIP:: + + If you are still not seeing your changes take effect, remember to + :ref:`clear the Symfony cache ` and your + web browser's cache as well! + ++++++++++++ +Bootstrap 2 ++++++++++++ + +.. NOTE:: + + Bootstrap 2 themes have been deprecated and will be removed in a future + release. Please consider switching to a Bootstrap 5 theme. Specifically, :ref:`job-details` may not appear properly styled in a custom theme without an additional step. To ensure your Jobs pages properly inherit @@ -413,10 +464,10 @@ Specifically, your modified files should be updated to match these lines: `__ Recompiling after making modifications --------------------------------------- +====================================== After making any necessary updates to your custom theme, you should rebuild -the CSS for the custom themeplugin, using the ``make`` command. Here is an +the CSS for the custom theme plugin, using the ``make`` command. Here is an example of rebuilding the CSS for the ArchivesCanada theme - you can swap in the name of your plugin: diff --git a/conf.py b/conf.py index e22574d7..5efd79fe 100644 --- a/conf.py +++ b/conf.py @@ -71,9 +71,11 @@ # built documents. # # The short X.Y version. -version = "2.7" +# version = "2.7" # The full version, including alpha/beta/rc tags. release = "2.7.3" +version = '.'.join(release.split('.')[:2]) +extensions = ['sphinx_version_ref'] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/user-manual/administer/images/change-theme.png b/user-manual/administer/images/change-theme.png index 4e75b3d0..24b32cca 100644 Binary files a/user-manual/administer/images/change-theme.png and b/user-manual/administer/images/change-theme.png differ diff --git a/user-manual/administer/images/dominionB5-theme.png b/user-manual/administer/images/dominionB5-theme.png new file mode 100644 index 00000000..b826c0d6 Binary files /dev/null and b/user-manual/administer/images/dominionB5-theme.png differ diff --git a/user-manual/administer/themes.rst b/user-manual/administer/themes.rst index c4d865a2..7839e3ef 100644 --- a/user-manual/administer/themes.rst +++ b/user-manual/administer/themes.rst @@ -15,27 +15,32 @@ This section describes how to change the theme, :term:`site title`, .. _themes-change-theme: +.. IMPORTANT:: + + Bootstrap 2 themes have been deprecated and will be removed in a future + release. Please consider switching to a Bootstrap 5 theme. + Change theme ============ -AtoM 2.7 ships with 3 themes: the default :term:`Dominion theme` -(arDominionPlugin) and the Archives Canada theme (arArchivesCanadaPlugin). +AtoM 2.7 and up ships with 3 themes: the default :term:`Dominion theme` +(arDominionB5Plugin) and the Archives Canada theme (arArchivesCanadaPlugin). The Dominion themes are grey, white and black with the AtoM logo. The Archives Canada theme is yellow, blue and white with the ArchivesCanada logo (see images below). -The new version of the Dominion theme is based on Bootstrap 5 (“BS5”), a +The default version of the Dominion theme is based on Bootstrap 5 (“BS5”), a framework for developing websites. BS5 provides a number of improvements over the previous version (“BS2”) such as better security, responsiveness and accessibility. -If you’re a brand new AtoM user, we suggest that you use the BS5 theme. If you -are performing an upgrade to 2.7 from an older version, and you have a custom -theme, we recommend you continue to use BS2 at this time. +If you’re a brand new AtoM user, please use the default BS5 theme. If you +are performing an upgrade from an older version, and you have a custom +theme, we recommend upgrading that theme to use BS5. -.. figure:: images/dominion-theme.* +.. figure:: images/dominionB5-theme.* :align: center :figwidth: 60% :width: 100% @@ -68,6 +73,10 @@ To change the theme: 2. Click on the :term:`radio button` in the "Enabled" column for the theme you wish to have enabled and click "Save." +.. SEEALSO:: + + * :ref:`Create a custom theme ` + .. _themes-add-remove-elements: Add or remove elements