support section variable in manual url

[wangf1122]

The manual url can be more flexible. In some places, the url can be like https://something/subsection?lang=eng ect. So I am adding section variable as part of the url pattern and the front end Javascript will handle this pattern as well.

Checklist

• I have read the contribution guidelines
• Pull request provided for main branch, backports managed with label
• Good housekeeping of code, cleaning up comments, tests, and documentation
• Clean commit history broken into understandable chucks, avoiding big commits with hundreds of files, cautious of reformatting and whitespace changes
• Clean commit messages, longer verbose messages are encouraged
• API Changes are identified in commit messages
• Testing provided for features or enhancements using automatic tests
• User documentation provided for new features or enhancements in manual
• Build documentation provided for development instructions in README.md files
• Library management using pom.xml dependency management. Update build documentation with intended library use and library tutorials or documentation

[ianwallen]

I wonder if we want to make {{section}} optional and if it does not exists then append section at the end. (Which seem to be the current logic)

Of if we just want to treat is as required if want to use it.
i.e. should we support url like http://example.com?lang=en that would not include the section.
Otherwise, the current implementation will always append the section so http://example.com?lang=en would turn into http://example.com?lang=en/section which would cause issues. And to get around this we would need to add http://example.com?lang=en&dummy={{section}} to add a dummy section that is not used.

If we do want {{section}} to be mandatory to be used then I suspect that the section will need to be added to existing urls

UPDATE Settings SET value = CONCAT(value, '{{section}}') WHERE name = 'system/documentation/url';

Also you will need to update the following.

INSERT INTO Settings (name, value, datatype, position, internal) VALUES ('system/documentation/url', 'https://docs.geonetwork-opensource.org/{{version}}/{{lang}}', 0, 570, 'n');
To

INSERT INTO Settings (name, value, datatype, position, internal) VALUES ('system/documentation/url', 'https://docs.geonetwork-opensource.org/{{version}}/{{lang}}/{{section}}', 0, 570, 'n');

What do other think?

[josegar74]

@ianwallen I think it is fine if the placeholder is optional

[josegar74]

The change works, but with the current code this kind of URL doesn't work:

https://something/subsection?lang=eng

The lang placeholder replacement checks for /{{lang}} instead of {{lang}}. This is not changed in the PR, but not sure why the original code has the /.

---

The official manual adds the language as part of the URL path, not as a parameter:

https://docs.geonetwork-opensource.org/4.4/fr/overview/

I assume you have some customised documentation that uses language as a parameter?

[wangf1122]

The change works, but with the current code this kind of URL doesn't work:

https://something/subsection?lang=eng

The lang placeholder replacement checks for /{{lang}} instead of {{lang}}. This is not changed in the PR, but not sure why the original code has the /.

The official manual adds the language as part of the URL path, not as a parameter:

https://docs.geonetwork-opensource.org/4.4/fr/overview/

I assume you have some customised documentation that uses language as a parameter?

@josegar74

The original has / is because it doesn't like to parse English into the default document.

For example:

https://docs.geonetwork-opensource.org/4.2/user-guide/describing-information/creating-metadata/

vs French version

https://docs.geonetwork-opensource.org/4.2/fr/user-guide/describing-information/creating-metadata/.

Now if we ignore that "/" logic, we will end up with default English url as:
https://docs.geonetwork-opensource.org/4.2//user-guide/describing-information/creating-metadata/ which seems to be fine. I could make such logic by ignoring such slash

[ianwallen]

Why add the "/"?

[wangf1122]

This was the default original code.

core-geonetwork/web-ui/src/main/resources/catalog/components/common/needhelp/NeedHelpDirective.js

Line 160 in 97bdd7b

var helpPageUrl = baseUrl + "/" + page;

The default manual.json of each section contains was appended at the end of the url and they contain no such "/". So the Javascript has to add them

core-geonetwork/web/src/main/webapp/WEB-INF/data/data/resources/config/manual.json

Line 2 in 97bdd7b

"creating-metadata": "user-guide/describing-information/creating-metadata/",

[ianwallen]

I think this should be "."

i.e. there are 2 urls.

• If lang !== "en" i.e. fr
  • https://docs.geonetwork-opensource.org/4.2/{{lang}}/api/search/
    will be changed to
  • https://docs.geonetwork-opensource.org/4.2/fr/api/search/
• else
  • https://docs.geonetwork-opensource.org/4.2/{{lang}}/api/search/
    will be changed to
  • https://docs.geonetwork-opensource.org/4.2//api/search/
    which does not look as pretty but still works. The double // in the url remains but if you put it as a "." then you get
  • https://docs.geonetwork-opensource.org/4.2/./api/search/
    and the browser will replace this with
  • https://docs.geonetwork-opensource.org/4.2/api/search/

[ianwallen]

Now that I think about it, it does not make sense to user "." either because someone could use ?lang={{lang}} and it would be odd to add "." and ?lang=. would not make sense!
So I guess "" is better in this case.
Maybe there could be another replace on the url after the replace to remove all the double "//"

As for why there is a odd case where lang = ""
What if it treated gnGlobalSettings.lang !== "en" as if gnGlobalSettings.lang = null?
Then {{lang?en}} could mean that if lang is null then default to en
So you could add another replacement for the following.
baseUrl = scope.helpBaseUrl.replace("{{lang?en}}", "");

So gn could use
https://docs.geonetwork-opensource.org/4.2/{{lang}}/api/search/
And other sites that always want to have a language value for language could use
https://example.com/{{lang?en}}/api/search/?lang={{lang?en}} and it would result to en value.
But this would still be odd logic.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[josegar74]

I would keep the replacement to empty string and replace // in the URL path.

Please check this change to apply it in your code:

          /**
           * Processes an URL removing // characters in the URL path.
           *
           * @param url
           * @returns {string}
           */
          var processUrl = function(url) {
            var urlToProcess = new URL(url);
            urlToProcess.pathname = urlToProcess.pathname.replace(/\/\//g, "/");
            return urlToProcess.toString();
          }

          scope.showHelp = function () {
          ...
           var helpPageUrl;
            if (baseUrl.includes("{{section}}")) {
              helpPageUrl = baseUrl.replace("{{section}}", page);
            } else {
              helpPageUrl = baseUrl + "/" + page;
            }

            helpPageUrl = processUrl(helpPageUrl);

            testAndOpen(helpPageUrl).then(
              function () {},
              function () {
                var baseUrl = scope.helpBaseUrl
                  .replace("{{lang}}", "")
                  .replace("{{version}}", scope.applicationVersion);
                var helpPageUrl;
                if (baseUrl.includes("{{section}}")) {
                  helpPageUrl = baseUrl.replace("{{section}}", page);
                } else {
                  helpPageUrl = baseUrl + "/" + page;
                }

                helpPageUrl = processUrl(helpPageUrl);

                testAndOpen(helpPageUrl);
              }
              ...

[wangf1122]

@josegar74

This approach works fine. I did apply this into the code, please check