Make the CC license field component configurable in DSpace 8.0

[abelgomez]

References

This PR does not directly address an open issue, but improves PR #3010 that addressed #3002.
Requires: DSpace/DSpace#9882

Description

The ItemPageCcLicenseFieldComponentimplemented in #3010 has some configuration properties that, however, are hardcoded in the component itself and require manual modifications of the typescript code.

Since at least two configuration properties are indeed easily configurable in the back end (license URI field and license name field), makes sense that the front-end allows to configure them too.

This PR adds these configuration options (and some others) to the application config, so that no more modifications are required at the code level.

Instructions for Reviewers

1. Run the front-end with the default DSpace 8.0 configuration.
2. Create an item, and set its dc.rights.uri and dc.rights to a valid value (e.g., https://creativecommons.org/licenses/by-nc-nd/4.0/ and CC BY-NC-ND 4.0 respectively) and see the Creative Commons badge to appear.
3. Delete the dc.rights metadata value and refresh the item. The CC badge will not show (the ItemPageCcLicenseFieldComponent requires both the CC uri and CC name to be set).
4. Create a new dc.rights.license metadata value with the value CC BY-NC-ND 4.0. Refresh the item, and the badge will still not be shown (since only dc.right.uri will be found with the default configuration).
5. Shutdown the front-end, and add the following configuration to your app config:

ccLicense:
  # Field name containing the CC license name, as configured in the back-end, in the 'dspace.cfg' file, property 'cc.license'
  # Defaults to 'dc.rights'
  nameField: dc.rights.license

6. Start the front-end, and the CC badge will now appear in the item.

Other properties that ca be configured are:

# Creative Commons metadata fields
ccLicense:
  # Icon variant:
  # 'full' variant shows image, a disclaimer (optional) and name (always), better for the item page content.
  # 'small' (default) variant shows image and name (optional), better for the item page sidebar
  variant: small
  # Field name containing the CC license URI, as configured in the back-end, in the 'dspace.cfg' file, property 'cc.license.uri'
  # Defaults to 'dc.rights.uri'
  uriField: dc.rights.uri
  # Field name containing the CC license name, as configured in the back-end, in the 'dspace.cfg' file, property 'cc.license'
  # Defaults to 'dc.rights'
  nameField: dc.rights
  # Shows the CC license name with the image. Always show if image fails to load
  showName: true
  # Shows the disclaimer in the 'full' variant of the component
  showDisclaimer: true

Checklist

This checklist provides a reminder of what we are going to look for when reviewing your PR. You need not complete this checklist prior to creating your PR (draft PRs are always welcome).
However, reviewers may request that you complete any actions in this list if you have not done so. If you are unsure about an item in the checklist, don't hesitate to ask. We're here to help!

• My PR is small in size (e.g. less than 1,000 lines of code, not including comments & specs/tests), or I have provided reasons as to why that's not possible.
• My PR passes ESLint validation using yarn lint
• My PR doesn't introduce circular dependencies (verified via yarn check-circ-deps)
• My PR includes TypeDoc comments for all new (or modified) public methods and classes. It also includes TypeDoc for large or complex private methods.
• My PR passes all specs/tests and includes new/updated specs or tests based on the Code Testing Guide.
• My PR aligns with Accessibility guidelines if it makes changes to the user interface.
• My PR uses i18n (internationalization) keys instead of hardcoded English text, to allow for translations.
• My PR includes details on how to test it. I've provided clear instructions to reviewers on how to successfully test this fix or feature.
• If my PR includes new libraries/dependencies (in package.json), I've made sure their licenses align with the DSpace BSD License based on the Licensing of Contributions documentation.
• If my PR includes new features or configurations, I've provided basic technical documentation in the PR itself.
• If my PR fixes an issue ticket, I've linked them together.

[selensoftr]

It doesn't work on Publication, it only works on item. Why?
I wish it was added to 7.6.2, it would be great if it worked in both publcaiton and item.

[abelgomez]

The publication.component.html (the component that renders Publications) does not use the ds-item-page-cc-license-field.

ds-item-page-cc-license-field is, currently, only used by untyped-item.component.html.

Thus, it is not related to this PR.

IMHO, whether publications should (or should not) use ds-item-page-cc-license-field must be discussed in a different issue (or PR).

[abelgomez]

Thinking about the licensing of untyped items and publications... maybe you're right, and it should be added to the default templates. To be fair, it seems a bit arbitrary that it is only shown for untyped items and only when selecting a CC license.

Feel free to post a new issue. If the community thinks it's worth implementing, I volunteer to do so.

[selensoftr]

Dear Abelgomez, thank you very much for reply.

I added the relevant values ​​in the untyped-item.component.html and .ts file to the publication.component.hmtl and .ts file and ran the build, but it resulted in an error. (not: version DSpace 8.0)

publication.component.ts

import { ItemPageCcLicenseFieldComponent } from '../../field-components/specific-field/cc-license/item-page-cc-license-field.component';

@Component({
  selector: 'ds-publication',
  styleUrls: ['./publication.component.scss'],
  templateUrl: './publication.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
  standalone: true,
  imports: [
  ItemPageCcLicenseFieldComponent,

publication.component.html
<ds-item-page-cc-license-field [item]="object" [variant]="'full'"> </ds-item-page-cc-license-field>

yarn start:dev

Result:
Error: src/app/item-page/simple/item-types/publication/publication.component.html:104:52 - error NG8002: Can't bind to 'variant' since it isn't a known property of 'ds-item-page-cc-license-field'.

1. If 'ds-item-page-cc-license-field' is an Angular component and it has 'variant' input, then verify that it is included in the '@Component.imports' of this component.
2. If 'ds-item-page-cc-license-field' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@Component.schemas' of this component to suppress this message.
3. To allow any property add 'NO_ERRORS_SCHEMA' to the '@Component.schemas' of this component.

104 <ds-item-page-cc-license-field [item]="object" [variant]="'full'">
~~~~~~~~~~~~~~~~~~
src/themes/custom/app/item-page/simple/item-types/publication/publication.component.ts:42:16
42 templateUrl: '../../../../../../../app/item-page/simple/item-types/publication/publication.component.html',
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Error occurs in the template of component PublicationComponent.

[abelgomez]

Again, the error you have posted is unrelated to this PR (you would get the same error with the unmodified DSpace 8.0 code base).

It is caused because the file src/themes/custom/app/item-page/simple/item-types/publication/publication.component.ts references the template at src/app/item-page/simple/item-types/publication/publication.component.html.

Thus, you must also add ItemPageCcLicenseFieldComponent to the component imports in src/themes/custom/app/item-page/simple/item-types/publication/publication.component.ts as you did in src/app/item-page/simple/item-types/publication/publication.component.ts.

It also took me a couple of minutes to notice that the error was coming from the "custom" theme, rather than from the "base" app 😉

[selensoftr]

Dear @abelgomez thank you very much.
I did as you said and it worked.
Thank you very much.

[github-actions]

Hi @abelgomez,
Conflicts have been detected against the base branch.
Please resolve these conflicts as soon as you can. Thanks!

[tdonohue]

@abelgomez : Thanks for this work! Apologies for the delayed response, but we did a team code review of this PR in today's Developer Meeting. Overall, the feedback was positive & this PR seems like a nice improvement. Just a few things we noticed:

1. First, this PR has code conflicts which need to be resolved so that it's mergeable again.
2. Second, the new configs are really useful. But, for uriField and nameField, you could just read these values from the REST API (if you enable them to be read as I describe below). This would make this improvement even easier to use, as you can configure these fields in one place (on the backend) instead of in two places.

Overall though, only a rebase (to fix merge conflicts) is required. But, we'd still recommend considering reading these two settings from the backend as it will make this much easier to use.

[tdonohue]

This line should say cc.license.name as that's the property in dspace.cfg that it should match

[tdonohue]

Because this setting should always match the cc.license.uri setting in dspace.cfg, it'd be better to just have the backend share that setting with the user interface. This is what we do in other areas of the application as well.

For example, the backend already does this with cc.license.jurisdiction setting in dspace.cfg. In order to tell the backend to make that setting available, you just need to add it to the list of rest.properties.exposed in rest.cfg like this: https://github.com/DSpace/DSpace/blob/main/dspace/config/modules/rest.cfg#L54

Then, the UI code is able to request that setting from the REST API, like this:
https://github.com/DSpace/dspace-angular/blob/main/src/app/submission/sections/cc-license/submission-section-cc-licenses.component.ts#L310

So, this PR could be simplified if you removed the uriField setting here, and instead made a call to:

 this.configService.findByPropertyName('cc.license.uri')

In general, this PR does seem like a step in the right direction. So, if you feel you cannot update it to read these values from the REST API, we still can move this forward. But, I wanted to point out how easy it is to just read these settings from the REST API instead of duplicating them to the UI configs.

[tdonohue]

Similar to the note above, we also could remove this config and instead configure the REST API to expose cc.license.name and then call ``

this.configService.findByPropertyName('cc.license.name')

Again, your approach here will work too...but it would require users to make sure these two settings are duplicated into both dspace.cfg and config.yml.

[abelgomez]

Hi @tdonohue , thanks for the feedback. Reading the configuration from the backend seems the way to go.

Sorry for not noticing it could be done 🤦‍♂️🤦‍♂️ I still need to learn a lot about the codebase...

I'll work on the rebase, and I'll implement the improvements (since they also affect the implementation of other PRs I'm working on. Unfortunately, as I said some weeks ago in another PR, I'm a bit busy this season so that fixes will take some weeks.

Cheers!

[tdonohue]

@abelgomez : No worries on your timelines. We expect that not all developers are able to get back to PRs immediately at all times. But, whenever you are able to get back to this, please feel free to ping me for another (hopefully final) review. Overall, the idea here is very good though & we appreciate your effort in making CC licenses more configurable.

[abelgomez]

Hi @tdonohue ,

I think that the code is ready. It now retrieves the cc.license.uri and cc.license.name from the backend if they are exposed.

Since these two properties do not hold any sensitive information, I'll open a PR in the backend to expose both of them by default.

I acknowledge that I have introduced a bit of confusion in the commits, but, in the end, the final code didn't change too much w.r.t. my previous proposal, so I hope it's easy to review.

The thing is that I initially removed all the configuration options (because I forgot about variant, showName and showDisclaimer), and then I realized that not only uriField and nameField were configurable, so I restored the part the dealt with variant, showName and showDisclaimer.

I also initially decided to remove the ccLicenseUriField and ccLicenseNameField configurable properties from the component, but I later thought that it could be useful to override the backend configuration at the template level. Thus, I also decided to restore those properties.

Sorry for the indecisiveness.

On a side note, it's also noteworthy to mention that I wrapped part of the properties inside Observables, since now their values depend on the back-end configuration that is retrieved when the component is initialized.

Now, since the URI and license name are retrieved from the backend, the initial description and title of the PR are not fully accurate.

Here is an updated version:

Description

The ItemPageCcLicenseFieldComponentimplemented in #3010 has some configuration properties that, however, are hardcoded in the component itself and require manual modifications of the typescript code.

Two configuration properties are configurable in the back end (license URI field and license name field), and other are only specific to the front-end (icon variant, show name, and show disclaimer).

This PR:

1. Retrieves the license URI field and license name field from the back-end (if the properties are exposed).
2. Adds configuration options for the icon variant, name visibility , and disclaimer visibility to the application config, so that no more modifications are required at the code level.

In any case, the component can still be used in angular templates as before. If a developer explicitly sets the ccLicenseUriField and ccLicenseNameField properties when using it, the configuration of the back-end will be ignored and the issued values will be used instead.

Instructions for Reviewers

1. Run the front-end with the default DSpace 8.0 configuration.
2. Create an item, and set its dc.rights.uri and dc.rights to a valid value (e.g., https://creativecommons.org/licenses/by-nc-nd/4.0/ and CC BY-NC-ND 4.0 respectively) and see the Creative Commons badge to appear.
3. Delete the dc.rights metadata value and refresh the item. The CC badge will not show (the ItemPageCcLicenseFieldComponent requires both the CC uri and CC name to be set).
4. Create a new dc.rights.license metadata value with the value CC BY-NC-ND 4.0. Refresh the item, and the badge will still not be shown (since only dc.right.uri will be found with the default configuration).
5. Shutdown the back-end, and add the following configuration to your local.cfg:

rest.properties.exposed = cc.license.name
cc.license.name = dc.rights.license

6. Start the back-end, and the CC badge will now appear in the item.

The properties that may be read from the back-end are:

cc.license.name = dc.rights.license
cc.license.uri = dc.rights.uri
# In order to be exposed via the REST API, the following properties are also required:
rest.properties.exposed = cc.license.name
rest.properties.exposed = cc.license.uri

The properties that can be configured in the front-end are:

# Creative Commons metadata fields
ccLicense:
  # Icon variant:
  # 'full' variant shows image, a disclaimer (optional) and name (always), better for the item page content.
  # 'small' (default) variant shows image and name (optional), better for the item page sidebar
  variant: small
  # Shows the CC license name with the image. Always show if image fails to load
  showName: true
  # Shows the disclaimer in the 'full' variant of the component
  showDisclaimer: true