Skip to content

Update docker and themeing docs #369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
melaniekung wants to merge 1 commit into
base: 2.10
Choose a base branch
from
Open

Update docker and themeing docs #369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 189 additions & 3 deletions admin-manual/customization/theming.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
$ <?php decorate_with('layout_homepage'); ?>


plugins/arCustomB5Plugin/templates/layout_homepage.php:

.. code-block:: bash

$ <?php echo get_partial('layout_start'); ?>


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

<div id="carousel" class="carousel carousel-fade slide">
<div class="carousel-inner">
<?php foreach ($carouselItems as $key => $item) { ?>
<div class="item<?php if (0 == $n++) echo " active" ?>">
<?php echo image_tag('/plugins/arXyzB5Plugin/carousel/' . $key) ?>
<?php if ($item['fr'] && $sf_user->getCulture() == 'fr') { ?>
<div class="carousel-caption">
<p>
<?php echo $item['fr'] ?>
</p>
</div>
<?php } else { ?>
<div class="carousel-caption">
<p>
<?php echo $item['en'] ?>
</p>
</div>
<?php } ?>
</div>
<?php } ?>
</div>
</div>

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

<section id="newest-additions" class="card mb-3">
<h2 class="h5 p-3 mb-0">
<?php echo __('Newest additions'); ?>
</h2>
<div class="list-group list-group-flush">
<?php foreach ($newestAdditions as $item) { ?>
<?php $object = QubitObject::getById($item); ?>
<a
class="list-group-item list-group-item-action d-flex justify-content-between align-items-center text-break"
href="<?php echo url_for([$object]); ?>">
<?php echo render_title(esc_entities($object->__toString())) ?>
</a>
<?php } ?>
</div>
</section>

`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

<?php echo get_component('default', 'newest', [
'limit' => 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
Expand Down
117 changes: 117 additions & 0 deletions dev-manual/env/compose.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/artefactual-labs/am/tree/master/compose#elasticsearch-container>`__.

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
===============

Expand Down
Loading