Configuration, etc.
Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites
Configuration
After installing and enabling Attributions there will be an attribution block named Attributions block, and an attribution page when you visit the path /attributions
.
By default, only attributions specified by enabled modules and themes will be rendered. To render attributions from all modules and themes. set the boolean variable attributions_all
TRUE. You may do this with drush:
drush vset attributions_all TRUE
There is no adminsitrative GUI.
Attributions should be placed in a file named ASSETS.yml
, in the module's top directory, using the standard YAML.org data serialization format.
Attributions YAML format
YAML is a human-readable data serialization format.
For more information about this format, see:
Syntax
The data structure hierarchy in YAML is maintained by outline indentation. For attributions, each resource are represented by an unique (in this file) identifier, followed by colon+newline followed by an intented list of keys and values separated by colon+space:
identifier: key: value key: value …
For example, the resource identified by “images/griffin_head.jpg”, with associated keys and values, may look like this:
images/griffin_head.jpg: type: asset approved: allowed license title: Griffin Head attributionText: Paul Keller attributionUrl: http://flickr.com/people/paulk/ license: CC-BY-2.0 rights: http://creativecommons.org/licenses/by/2.0/deed.no source: http://flickr.com/photos/paulk/2062848161/
In general there is no need to put quotes around strings, but there are exceptions:
- Use quotes to force a string, e.g. if your key or value is
10
but you want it to return a String and not a Fixnum, write'10'
or"10"
. - Use quotes if your value includes special indicators, such as a colon (
:
) followed by a space or a newline, or{
,}
,[
,]
,,
,&
,*
,#
,?
,|
,+
,-
,<<
,>>
,=
,!
,%
,@
,\
. - Single quotes let you put almost any character in your string, and won't try to parse escape codes.
'\n'
would be returned as the string\n
. - Double quotes parse escape codes. For instance,
"\n"
will be returned as a line feed character. - If
>
is used to indicate a scalar, indicators are not interpreted (so no quotes are required).
Identifier
Each resource entry should be identified with an unique (in this file) string that identify the resource. This string should be the path (from the root of the repo) to an individual file, or the path to a directory. In the latter case the entry applies to all the files that live below the directory, unless overriden by more specific (single file) entries.
The path may contain the star wildcard *
(meaning any string, including the null string).
A hash character (#
), followed by an arbitrary string may be appended to the path to create multiple entries for the same directory or file. This can be used in the case where several assets or source code fragments, each associated with a different attributionText
, etc. is aggregated in a single directory or file.
This line must not be indented.
The following identifier says that the entry applies to all the files that lives below the “images”-directory:
images:
The following identifier says that the entry applies to the single file “griffin_head.jpg” that is in the “images”-directory:
images/griffin_head.jpg:
The following identifier says that the entry applies to all the files that lives in a directory named “originals”, located below the “images”-directory:
images/*/originals:
The following is used to attribute a file named “slider.js” that is made up of two different components, the first authored by “John Smith”, the second by “Dojo Inc”.
lib/slider.js#foo: attributionText: John Smith lib/slider.js#bar: attributionText: Dojo Inc
Administrative keys
Two keys are used for administrative purposes:
type
: Must be set to 'code
', 'asset
' orcomment
'.approved
: Must be a link to an issue tracker in the LWG issue queue (for an exception request) or the string 'allowed license
' (for own work made available under a whitelisted license).
The type
should have the value code
if the resource is program code, and asset
if the resource is a non-code asset (e.g. text, image, video, audio, font, icon).
The type
key must always be present in an entry. If the type
of the entry is comment
no other keys are required.
Metadata keys
The following set of keys may be used to document the source and license of a resource:
title
: A human readable string identifying the licensed work (recommended).source
: Source of licensed work. This may be an URL, or a plain text string explaining how to locate the source of the work.license
: License identifier from the SPDX License List (required). In the case of multi-licensing, you may list multiple licenses separated by commas/conjunctions as a single value assigned this key.copyrightNotice
: The copyright notice for the (possibly adapted) resource, or directions for finding such information provided by other means. If the asset is a protected logo (trademark or wordmark), this must be stated explicitly here.attributionText
: Author (person, project or organization) or authors to receive attribution. You may list multiple authors separated by commas/conjunctions as a single value assigned this key.attributionUrl
: URL to the author's profile or home page. The author may be an individual, an organization, or a project.rights
: URL to license or policy document for resource (required unless the license is one of our approved licenses, or it is a protected logo with no reuse rights).
Unless the type
of the entry is comment
, those marked “required” must be present in the entry. The other keys are optional. If they are present, they may help downstream recipients understand how to fulfill the attribution requirement of licenses such as the Creative Commons licenses, but it is OK for a project to provide for this by other means. If you do, it may be helpful to use text bound to the key copyrightNotice
to provide directions for finding such information.
Metadata keys for adaptions
If the work is an adapation, then the following additional keys may be used to document its origins. Only originalLicense
is required.
originalTitle
: A human readable string identifying the original of the adapted work.originalLicense
: Human readable name of license giving permission to adapt the work (required).originalCopyrightNotice
: The copyright notice for the original workoriginalAttributionText
: The name of the author of original that is adaptedoriginalAttributionUrl
: URL to profile or home page of author of original.originalRights
: URL to license or policy document for original.
Presentation keys
The Attributions module will use the values bound to the metadata keys to provide text and links for the automatically generated attribution page and block. In addution, the Attributions module recognizes the following keys that is only used to structure the presentation of the metadata:
template
: Defines a template string that may be used as a template for condtructing the attribution text.weight
: an optional integer that determines the weight of the resource.hide
: set to TRUE to hide the resource.path
: show the attribution block only on pages matching path (regexp)
The key template
can be used to specify a text template for a custom attribution. You may use metadata keys, prefixed with the sigil @
, to get the value of those keys inserted into the template. The string GPL-2.0-or-later
is quoted to escape the +
. There is no need to quote the template, even if it contains the YAML reserved indicator @
, because the >
indicates that this is a string.
sites/all/libraries/acmelib; type: code approved: https://www.drupal.org/node/123456 license: 'GPL-2.0-or-later' title: ACME Library attributionText: ACME Corporation template: > @title for PHP by @attributionText is relicensed for Drupal under GPL-2.0-or-later with permission from the authors.
The key weight
accepts an integer value. It can be used to indicate the placement of the resource relative to other resources. The default weight
value is 0, so you may a negative value to place the resource on top. In the example below, a comment in the Attributions Demo module's ASSETS.yml
is assigned a negative weight value to make sure it is displayed before any of the (bogus) attributions shown by that module:
comment: type: comment weight: -1 template: > The following list of attributions are only displayed for demo purposes. None of these resources are actually used by this module:
The key hide
with a value set to TRUE
can be used to indicate that the resource should not appear on the attribution page or in the attribution block. The use case for this key is to hide third party materials that one want to document using ASSETS.yml
, but need not not appear in an attribution block that is visible on the site (for example: third party resources without a attribution requirement, such as CC0-1.0, MIT, BSD-3-Clause, OFL-1.1, can be hidden). Example of use:
images/emptypurse.jpg: type: asset approved: allowed license hide: TRUE source: https://openclipart.org/detail/196212/empty-purse---portemonnaie license: CC0-1.0 rights: https://openclipart.org/share
The key path
may be used to specify a regular expression that must be matched for the attribution to appear in the attribution block. In this example, the attribution will only appear in the attribution block if the path to the page matches help_example/history
:
help/180px-Lerdorf.jpg: type: asset approved: allowed license attributionText: Jud Dagnall source: http://en.wikipedia.org/wiki/File:Lerdorf.jpg title: Rasmus Lerdorf license: CC-BY-CA-3.0 rights: http://creativecommons.org/licenses/by-sa/3.0/deed.en path: 'help_example\/history'
Note that since the value assigned to path
is a regular expression, the slash (/
) must be escaped.
Troubleshooting
If your YAML does not parse, you may use one of the following online tools to check the validity of your YAML syntax:
Attribution semantics
Multiple licenses
Some projects are made available under multiple licenses, typically by including more than one license files, or by listing more than one license separated by commas, or with a conjunction (“and”, “or”). Examples:
MIT, BSD-3-Clause MIT and GPL-2.0-or-later MIT or GPL-2.0-or-later MIT, BSD-3-Clause and GPL-2.0-or-later
If multiple licenses are listed, it is always assumed that the user can select any of them, not that they must accept all.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion