Configuration, etc.

Last updated on
6 May 2018

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' or comment'.
  • 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 work
  • originalAttributionText: The name of the author of original that is adapted
  • originalAttributionUrl: 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

Page status: No known problems

You can: