From 928db6e6c9ca52219b53c8e71195de8cfe358231 Mon Sep 17 00:00:00 2001 From: mel Date: Tue, 29 Sep 2026 10:12:17 -0700 Subject: [PATCH] Update docker and themeing docs --- admin-manual/customization/theming.rst | 192 ++++++++++++++++++++++++- dev-manual/env/compose.rst | 117 +++++++++++++++ 2 files changed, 306 insertions(+), 3 deletions(-) diff --git a/admin-manual/customization/theming.rst b/admin-manual/customization/theming.rst index 7573885a..0f0a6489 100644 --- a/admin-manual/customization/theming.rst +++ b/admin-manual/customization/theming.rst @@ -150,15 +150,201 @@ check the `plugins/arDominionB5Plugin` for the required file, and only copy from copied should have the same file path with `plugin/arCustomThemeB5Plugin` replacing `apps/qubit` or `plugins/arDominionB5Plugin`. +======================================== +Common theme customization code snippets +======================================== + +Splash on homepage +------------------ + +plugins/arCustomB5Plugin/modules/staticpage/templates/homeSuccess.php: + .. code-block:: bash - cd ~/atom - npm install - npm run build + $ + + +plugins/arCustomB5Plugin/templates/layout_homepage.php: + +.. code-block:: bash + + $ + + +Homepage carousel +----------------- + +File structure: + +.. code-block:: bash + + plugins/arXyzB5Plugin/ + ├── carousel + │ ├── config.yml # sets captions for each image + │ ├── image01.jpg + │ ├── image02.jpg + │ └── image03.jpg + ├── js + │ ├── carousel.js # use as template + │ └── main.js # import + └── modules + └── staticpage + ├── actions + │ └── homeAction.class.php # calls and sets $carouselItems array from /carousel directory + └── templates + └── homeSuccess.php + +Carousel `homeAction.class.php` snippet: + +.. code-block:: bash + + class StaticPageHomeAction extends StaticPageIndexAction + { + public function execute($request) + { + parent::execute($request); + + if (null === $this->carouselItems) { + $this->carouselItems = sfYaml::load('plugins/arXyzB5Plugin/carousel/config.yml'); + } + + $culture = $this->context->user->getCulture(); + if (!in_array($culture, ['en', 'fr'])) { + $culture = 'en'; + } + $this->culture = $culture; + } + } + +Carousel `homeSuccess.php` div snippet: + +.. code-block:: bash + + + +Carousel js snippet: + +.. code-block:: bash + + (($) => { + "use strict"; + + $(() => { + var node = $("#carousel"); + + $(node) + .imagesLoaded() + .always(() => { + $(".carousel-inner").slick({ + autoplay: true, + autoplaySpeed: 5000, + slidesToShow: 1, + slidesToScroll: 1, + draggable: false, + swipe: false, + arrows: true, + dots: false, + }); + })(jQuery); + +To execute the custom carousel script, run the following command: + +.. code-block:: bash + + $ npm run build + + +Newest Additions component +-------------------------- + +`modules/default/templates/_newest.php` template snippet: + +.. code-block:: bash + +
+

+ +

+
+ + + + __toString())) ?> + + +
+
+ +`modules/default/actions/newestComponent.class.php` action code snippet: + +.. code-block:: bash + + class DefaultNewestComponent extends sfComponent + { + private function getNewestAdditions() + { + $rootIds = array(QubitInformationObject::ROOT_ID, QubitRepository::ROOT_ID, QubitActor::ROOT_ID); + + $sql = 'SELECT o.id FROM object o LEFT JOIN status s ON o.id = s.object_id WHERE o.class_name IN ("QubitInformationObject", "QubitRepository", "QubitActor") AND o.id NOT IN ( ' . implode(',', $rootIds) . ') AND s.status_id <> ? ORDER BY created_at DESC LIMIT 10'; + + $rows = QubitPdo::fetchAll($sql, array(QubitTerm::PUBLICATION_STATUS_DRAFT_ID)); + return array_map(function($x) { return $x->id; }, $rows); + } + + public function execute($request) + { + $this->newestAdditions = $this->getNewestAdditions(); + + if (0 == count($this->newestAdditions)) { + return sfView::NONE; + } + } + } + +`modules/staticpage/templates/homeSuccess.php` homeSuccess snippet: + +.. code-block:: bash + + 10, + 'sf_cache_key' => $sf_user->getCulture(), + ]); ?> + +Rebuild theme assets +-------------------- 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! +.. code-block:: bash + + cd ~/atom + npm install + npm run build + .. TIP:: If you are still not seeing your changes take effect, remember to diff --git a/dev-manual/env/compose.rst b/dev-manual/env/compose.rst index 7dbceba2..74d450dd 100644 --- a/dev-manual/env/compose.rst +++ b/dev-manual/env/compose.rst @@ -213,6 +213,123 @@ stop and remove related containers, network and volumes by running: docker compose down --volumes +Other Useful Docker Commands +============================ + +Loading AtoM data in Docker +--------------------------- + +You will need to customize the path to your mysqldump file in the first +line. + +.. code:: bash + + docker compose cp [mysql source path] percona:[target save path in container] && \ + docker compose exec percona mysql -h localhost -u atom -patom_12345 -e "DROP DATABASE IF EXISTS atom;" && \ + docker compose exec percona mysql -h localhost -u atom -patom_12345 -e "CREATE DATABASE atom;" && \ + docker compose exec percona bash -c "mysql -h localhost -u atom -patom_12345 atom < /atom.sql" && \ + docker compose exec atom php -d memory_limit=-1 symfony tools:upgrade-sql --no-confirmation && \ + docker compose exec atom php -d memory_limit=-1 symfony search:populate + +If you plan to use this command often, it is recommended that you turn +it into a script for ease of use. + +Clearing AtoM caches +-------------------- + +.. code:: bash + + docker compose exec atom php symfony cc && \ + docker compose restart atom && \ + docker compose restart memcached && \ + docker compose restart atom_worker + +Run symfony without a memory limit +---------------------------------- + +This option, ``-d memory-limit=-1`` can be used with any command, setting +the PHP memory limit to unlimited while running lengthy symfony scripts/tasks + +.. code:: bash + + docker compose exec atom php -d memory_limit=-1 symfony tools:purge --demo + + +Debugging and troubleshooting +----------------------------- + +These commands and scripts can help with some common issues during +development. + +If the Elasticsearch container keeps shutting down +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If your Elasticsearch container constantly shuts down within a few +seconds of starting it, you may need to ``increase vm.max_map_count`` to +262144 or higher in your host system. More information is available +`here `__. + +Run + +.. code:: bash + + sudo sysctl -w vm.max_map_count=262144 + +before starting the ES docker container. + +Enable symfony debugging panel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As of AtoM 2.10.1, you can run the symfony debugging panel by opening +``index.php`` in AtoM root directory and change (Line 5) from: + +.. code:: php + + $configuration = ProjectConfiguration::getApplicationConfiguration('qubit', 'prod', false); + +to + +.. code:: php + + $configuration = ProjectConfiguration::getApplicationConfiguration('qubit', 'dev', false); + +This will enable the symfony debugging panel in AtoM. Remember to change +it back before you commit any code! + +Also note that changing the last parameter to ‘true’ enables php +warnings: + +.. code:: php + + $configuration = ProjectConfiguration::getApplicationConfiguration('qubit', 'dev', true); + +Note: this debugging panel was broken between AtoM v2.8 and v2.10 + +AtoM PHP logger +--------------- + +This function allows printing log messages directly into Docker container logs, +usually into `atom` or `atom_worker` container logs. This can be added to any class, +or add to `config/ProjectConfiguration.class.php` for global use. + +.. code:: php + + function log_docker($message, $value = "") + { + if (is_string($value)) { + $val = $value."\\n"; + } else { + $val = json_encode($value)."\\n"; + } + + if ($value != "" && $message != "") { + $message = $message.": "; + } + + file_put_contents('php://stdout', ($message)); + file_put_contents('php://stdout', ($val)); + } + Connect to AtoM ===============