add mmoda-help-page.md to mmoda help page

[volodymyrss]

first use case is this one

[volodymyrss]

@burnout87 can help if needed

[dsavchenko]

So the help text itself can be embedded rather easily, the whole html is written into the php array as a string. (There are two fields: value and safe_value, but the only difference I see is the line termination '\r\nvs\n`). We can use external images there, as the repos we convert to services are always public.

What's not clear is all these ids (vid, uid, vuuid, nid etc).

array(
  (object) array(
      'vid' => '4713',
      'uid' => '1',
      'title' => 'Gravitational wave analysis',
      'log' => '',
      'status' => '1',
      'comment' => '1',
      'promote' => '0',
      'sticky' => '0',
      'vuuid' => '8d695fcf-ee53-412e-8efe-8abdd46db83c',
      'nid' => '2784',
      'type' => 'mmoda_help_page',
      'language' => 'und',
      'created' => '1681904053',
      'changed' => '1681983388',
      'tnid' => '0',
      'translate' => '0',
      'uuid' => '19d03e6d-f7a9-4a64-8c03-1a7aa0566be1',
      'revision_timestamp' => '1681983388',
      'revision_uid' => '8',
      'body' => array(
        'und' => array(
          array(
            'value' => "<h2>Scope</h2>\r\n\r\n<p>EDITED</p>\r\n",
            'summary' => '',
            'format' => 'full_html',
            'safe_value' => "<h2>Scope</h2>\n\n<p>EDITED</p>\n",
            'safe_summary' => '',
          ),
        ),
      ),
...

[burnout87]

What's not clear is all these ids (vid, uid, vuuid, nid etc).

Those are specific ids of drupal: for example, to identify a node, nid, a user uid.

Those usually are assigned by Drupal the moment a node is generated

[dsavchenko]

I'm not really into Drupal. Here I will need help. Do I understand correctly: given that these ids are generated by one instance (Mohammed's dev instance), written to a php file and then can be ingested by other instances, most of the ids can be randomly assigned (just being unique) ?

[burnout87]

So, this part I have never tried.

But I guess that those ids are not randomly assigned. I have to understand how this ingesting part works.

[burnout87]

So, each help page is a node of the type mmoda_help_page, to create a new one you have to generate a nope of that type (node/add/mmoda-help-page), I have to figure out the exporting part though.

[burnout87]

BTW

@motame has made a very nice video-series specific for the creation of help pages. https://github.com/oda-hub/mmoda-frontend-module#create-or-modify-help-pages

Then, once the help pages are created, there are a number of hooks inside the frontend module that take care certain aspects like certain images properties (eg uri_scheme), and help pages nodes.

Those hooks are implemented in https://github.com/oda-hub/mmoda-frontend-module/tree/master/help_book_content_type

Finally, within the mmoda.module there is the hook that triggers the exporting of the help page once this is created, those will be exported as php files within the help_book subdirectory of the dedicated submodule (eg mmoda_isgr)

This is the function I am talking about: https://github.com/oda-hub/mmoda-frontend-module/blob/3d6ee66289a9865ef83315aeb4da4c788412a1a6/mmoda.module#L693C1-L738C2

[dsavchenko]

What we are interested in is the process of importing of the pages. We can prepare the php object mimicking the one export function is creating.

What I don't realise is how node id and node uuid interact. Does one have some precedence over the other? Could we skip one of them? Here https://github.com/oda-hub/mmoda-frontend-module/blob/3d6ee66289a9865ef83315aeb4da4c788412a1a6/mmoda.module#L597C1-L692C2 hooks deal with id, completely ignorant of uuid. But the drupal internal machinery can have some additional behaviour.

The id of the parent node is fixed, as all the book is coming from the git repo. Therefore, all we need is to generate the ids of the inserted page. Two tricky parts are:

• how to ensure that id is unique (easy for uuid by its nature) on new node creation
• when updating help page we can't generate the new one and need to know its id

Both require interaction with frontend db. Probably, the way is not to prepare the .php file but to use drush/api/etc?

[volodymyrss]

• how to ensure that id is unique (easy for uuid by its nature) on new node creation
• when updating help page we can't generate the new one and need to know its id

This can be achieved if UUID is made from hash of something identifying the instrument, e.g. it's name. Does this not work if you try?

Using drush could be principle not a bad way if another way does not work. It's less favorable since it introduces a difference in how instruments are installed which might end up having some effects in the future. It would be another step after installing instrument I guess?..

[volodymyrss]

note that it's somewhere tracked that the added book has a large parent.

[burnout87]

What we are interested in is the process of importing of the pages. We can prepare the php object mimicking the one export function is creating.

What I don't realise is how node id and node uuid interact. Does one have some precedence over the other? Could we skip one of them? Here https://github.com/oda-hub/mmoda-frontend-module/blob/3d6ee66289a9865ef83315aeb4da4c788412a1a6/mmoda.module#L597C1-L692C2 hooks deal with id, completely ignorant of uuid. But the drupal internal machinery can have some additional behaviour.

Those ids are generated by the Drupal engine, it's not under our control. uuid is an id that remains unique for a given node, whereas nid is used for external references of the node itself (eg you can use it to access a specific node page inside the drupal website), but this might change in case you export/import the node to/from another drupal instance.

Using drush could be principle not a bad way if another way does not work. It's less favorable since it introduces a difference in how instruments are installed which might end up having some effects in the future. It would be another step after installing instrument I guess?..

drush is the approach I was indeed considering, providing a dedicated cli. Otherwise there are the PHP api (at least for Drupal 9, not sure for Drupal 7).

[dsavchenko]

This can be achieved if UUID is made from hash of something identifying the instrument, e.g. it's name.

That's the way, if page installation relies on the uuid. But it seems that the related hooks in the mmoda module don't deal with uuids, but with ids instead. And the logic in these hooks is so far a bit obscured to me.

note that it's somewhere tracked that the added book has a large parent.

Could you clarify? I don't understand what you mean.

but this might change in case you export/import the node to/from another drupal instance

Currently, help_pages are generated in one instance (Mohamed's dev), gets exported with all ids generated there, and then they are installed in different instances from these exported files. Either Drupal somehow takes care of possible id duplication, or all current approach to the help_page could fail at some point.

[burnout87]

Currently, help_pages are generated in one instance (Mohamed's dev), gets exported with all ids generated there, and then they are installed in different instances from these exported files. Either Drupal somehow takes care of possible id duplication, or all current approach to the help_page could fail at some point.

I have to investigate this part as I don't know how it'd work.

[volodymyrss]

What we are interested in is the process of importing of the pages. We can prepare the php object mimicking the one export function is creating. What I don't realise is how node id and node uuid interact. Does one have some precedence over the other? Could we skip one of them? Here https://github.com/oda-hub/mmoda-frontend-module/blob/3d6ee66289a9865ef83315aeb4da4c788412a1a6/mmoda.module#L597C1-L692C2 hooks deal with id, completely ignorant of uuid. But the drupal internal machinery can have some additional behaviour.

Those ids are generated by the Drupal engine, it's not under our control.

In our case ids are generated by one instance (dev) and imported in another one (prod). It means that prod instance is not in control of these ids. Ideally we could generate these uuids and ids in compatible way to what dev instance does and insert them into prod instance. It's not clear what are the restrictions there, maybe they can be just arbitrary.

uuid is an id that remains unique for a given node, whereas nid is used for external references of the node itself (eg you can use it to access a specific node page inside the drupal website), but this might change in case you export/import the node to/from another drupal instance.

so this does not contradict our default plan - to synthese ids ourselves.

Using drush could be principle not a bad way if another way does not work. It's less favorable since it introduces a difference in how instruments are installed which might end up having some effects in the future. It would be another step after installing instrument I guess?.. drush is the approach I was indeed considering, providing a dedicated cli. Otherwise there are the PHP api (at least for Drupal 9, not sure for Drupal 7).

This makes sense only if it is not possible to create arbitrary ids in a way which will be accepted by staging drupal. staging drupal accepts ids produced by dev drupal, so these ids do not need to be generated by the instance where the pages are shown.

note that it's somewhere tracked that the added book has a large parent. Could you clarify? I don't understand what you mean.

help pages can be opened from instrument tab, but also from top right, where you can see then as part of the larger book, this https://www.astro.unige.ch/mmoda/help/mmoda

Currently, help_pages are generated in one instance (Mohamed's dev), gets exported with all ids generated there, and then they are installed in different instances from these exported files. Either Drupal somehow takes care of possible id duplication, or all current approach to the help_page could fail at some point.

at some point but like in 1e9 years :) also uuid often contains time or so, so that it never repeats.

That's the way, if page installation relies on the uuid. But it seems that the related hooks in the mmoda module don't deal with uuids, but with ids instead. And the logic in these hooks is so far a bit obscured to me.

exact logic is unclear to me too, but it might be that we do not need to care too much. we just need to generate the module php in a way which is similar to that produced by dev drupal instance and tweak it if it does not work. Could you try some variations and see if it works?

[dsavchenko]

help pages can be opened from instrument tab, but also from top right, where you can see then as part of the larger book, this https://www.astro.unige.ch/mmoda/help/mmoda

This relation is also encoded in the exported array. As far as I understand, here https://github.com/oda-hub/mmoda-frontend-module/blob/3d6ee66289a9865ef83315aeb4da4c788412a1a6/help_book/connect-my-mmoda-account-github.php#L166C1-L167C64 there are references to the book uuid and the direct parent uuid (which coincide in this case).

at some point but like in 1e9 years :) also uuid often contains time or so, so that it never repeats.

Bit not uid, which is just a sequential int, I think.

Could you try some variations and see if it works?

There are so many types of ids there. Without at least some understanding of what is what, it's not easy even to try. I suspect I will break the frontend.

[burnout87]

Bit not uid, which is just a sequential int, I think.

uid is the id of the user, relatively easy to control actually . but yes there are several others to manage

[volodymyrss]

help pages can be opened from instrument tab, but also from top right, where you can see then as part of the larger book, this https://www.astro.unige.ch/mmoda/help/mmoda

This relation is also encoded in the exported array. As far as I understand, here https://github.com/oda-hub/mmoda-frontend-module/blob/3d6ee66289a9865ef83315aeb4da4c788412a1a6/help_book/connect-my-mmoda-account-github.php#L166C1-L167C64 there are references to the book uuid and the direct parent uuid (which coincide in this case).

That's clear then.

at some point but like in 1e9 years :) also uuid often contains time or so, so that it never repeats.

Bit not uid, which is just a sequential int, I think.

ok, so if we start adding nid they will have to be added in dev drupal. Or, do they really have to be sequential? can we use some reserved 100000+1000 range?

Could you try some variations and see if it works?

There are so many types of ids there. Without at least some understanding of what is what, it's not easy even to try. I suspect I will break the frontend.

could you check which ids differ between different already existing instruments? uid might not always differ for example.

In any case before trying it'd be advisable to backup.

[dsavchenko]

@motame we had some discussion here

[dsavchenko]

Resolved via https://github.com/oda-hub/oda-bot/pull/28