A lightweight about screen library to allow quick but customizable attribution in Android
Attribouter
A lightweight "about screen" library to allow quick but customizable attribution in Android apps.
Attribouter is a lightweight "about screen" for Android apps, built to allow developers to easily give credit to a project's contributors and open source libraries, while matching the style of their app and saving the largest amount of time and effort possible.
It is meant to use GitHub's REST API to fetch and display information about open source projects and contributors, but it allows you to define some or all of its data in its configuration file in your app as well.
Screenshots
This is just sample data. It is not real. Though Jahir is lazy, so that part is (joking).
| Contributors | Contributor | Licenses | License |
|---|---|---|---|
Implementation (using the CLI)
APK
For demonstration and experimentation, an apk of the sample project can be downloaded here.
Usage
Setup
The Gradle dependency is available through jCenter, which is used by default in Android Studio. To add the dependency to your project, copy this line into the dependencies section of your app's build.gradle file.
compile 'me.jfenn:attribouter:0.0.7'
Starting an Activity
This is pretty simple.
Attribouter.from(context).show();
Creating a Fragment
This is also pretty simple.
Fragment fragment = Attribouter.from(context).toFragment();
Request Limits
This library does not use an auth key for the GitHub API by default. It does cache data for up to 10 days to avoid crossing GitHub's rate limits, but if your project has more than a few contributors and libraries or you want it to have access to a private repository, you will need to provide an auth token by calling .withGitHubToken(token) on your instance of Attribouter.
Quick Configuration
If you simply want to create/update a configuration file based on a GitHub repository as quickly as possible, then the Attribouter CLI is an easy solution.
Configuration
By default, Attribouter will use the configuration file at res/xml/attribouter.xml. You can either name your configuration file "attribouter.xml" to override the resource, or name it differently and call .withFile(R.xml.[name]) on your instance of Attribouter instead.
The configuration file consists of a single root element, <about>, with several possible child elements that can be added any amount of times in any order. You can either make one by looking at the configuration file of the sample app for an example, or by using the list below.
<appInfo>
Displays the app icon, name, version, and links to the project on github and its website if available.
| Attribute | Type | Description |
|---|---|---|
| repo | String (name/repository) | The github repository to fetch data from. |
| icon | String (URL) / Drawable Resource | The app icon to display. |
| description | String / String Resource | A short description of the app/project. |
| playStoreUrl | String / String Resource (URL) | The URL of the app on the Play Store (generated from the package name by default). |
| websiteUrl | String / String Resource (URL) | The website of the project. |
| gitHubUrl | String / String Resource (URL) | The URL for the open source GitHub project. You do not need to define this if it is the same as repo. |
<link>
Link tags can exist inside of the <appInfo>, <contributor>, or <project> tags. A few links are generated by default, such as links to the github profile of contributors for which the login attribute has been specified, and so on. App info links are displayed below the app description, contributor links are displayed in a dialog (that only appears if the contributor has a bio), and project links are displayed below the project description. See issue #12 for more information about this tag.
| Attribute | Type | Description |
|---|---|---|
| id | String | The id of the link, to prevent duplicate links from being created. |
| name | String / String Resource | The name/title of the link. |
| url | String | The url of the link. |
| icon | String (URL) / Drawable Resource | The icon to display next to the link. |
| priority | Integer | Defines how the links should be sorted - the highest priority appears first in the list, and/or is opened when the whole item is clicked. |
| hidden | Boolean | Whether to hide the link. This is useful for removing automatically generated links that you do not want to display (example: removing the 'playStore' link generated by <appInfo> using the package name if your app is not published on the play store). |
Auto-generated links for the <appInfo> tag are as follows:
| ID | Description | Required Attributes |
|---|---|---|
| github | The github repository of the project. | repo or gitHubUrl |
| website | The website of the project. | repo (if the repo has a website assigned) or websiteUrl |
| playStore | A 'rate' button that opens the app in the play store. | playStoreUrl or repo (if the repository url is the play store url) |
<text>
A block of text.
| Attribute | Type | Description |
|---|---|---|
| text | String / String Resource (HTML) | A string or string resource, can be formatted in html (links work too) that defines the text to display. |
| centered | Boolean | Whether the text should be centered. |
<contributors>
Shows a list of the contributors of a project on github, merged with a list of child <contributor> elements defined in the configuration file. For example, if a user with the login "TheAndroidMaster" is both in GitHub and the configuration file, its attributes will be merged so that any attributes beginning with a "^" character will override the information from GitHub, and any attributes not beginning with a "^" character will be used while the GitHub information is loading, or if the information from GitHub is not present or unavailable.
| Attribute | Type | Description |
|---|---|---|
| repo | String (name/repository) | The GitHub repository to fetch contributors from. |
| title | String / String Resource | The title to show above the contributors (defaults to @string/title_attribouter_contributors / "Contributors"). |
| overflow | Integer (>= -1) | The maximum number of contributors to display in the list. Additional contributors are displayed in a dialog. If the number is 0, the entire list is replaced with a button titled "View %s" ('%s' being the title attribute). If the number is -1, all of the contributors are displayed. |
| showDefaults | Boolean | Whether or not to show the default contributors in this list (me and the contributors to this repository). |
<contributor>
| Attribute | Type | Description |
|---|---|---|
| login | String | The GitHub username/login of the contributor (especially useful for overriding specific attributes of certain contributors. |
| name | String / String Resource | The name of the contributor. |
| avatar | String (URL) / Drawable Resource | The "profile picture" of the contributor. |
| task | String / String Resource | A short phrase describing the contributor's role in the project ("Icon Designer", "Founder", etc). |
| bio | String / String Resource | The biography of the contributor. |
| blog | String / String Resource (URL) | The contributor's website. |
| String / String Resource | The email of the contributor. | |
| position | Integer | If this attribute is given to three contributors with values between 1 and 3 (one each), they will be displayed in a row at the top of the list (1 in the middle, slightly bigger, 2 on the left, 3 on the right). |
| hidden | Boolean | Whether to remove the contributor from the list. This is only really useful if you want to remove certain contributors that are fetched from GitHub. Default value is 'false', obviously. |
<link>
Attributes for this tag are the same as the ones described under the <appInfo> tag above.
Auto-generated links for the <contributor> tag are as follows:
| ID | Description | Required Attributes |
|---|---|---|
| github | The github profile of the contributor. | login |
| website | The website of the contributor. | blog or login (if the user has a blog defined on their GitHub profile) |
| The email of the contributor. | email or login (if the user has a public email on their GitHub profile) |
<translators>
A list of the translators of this app, sorted into sections by the language(s) that they have translated. Child elements are <translator> tags.
| Attribute | Type | Description |
|---|---|---|
| title | String / String Resource | The title to show above the translators (defaults to @string/title_attribouter_translators / "Translators") |
| overflow | Integer (>= -1) | The maximum number of translators to display in the list. Additional translators are displayed in a dialog. If the number is 0, the entire list is replaced with a button titled "View %s" ('%s' being the title attribute). If the number is -1, all of the translators are displayed. |
<translator>
| Attribute | Type | Description |
|---|---|---|
| login | String | The GitHub username/login of the translator. |
| name | String / String Resource | The name of the translator. |
| avatar | String (URL) / Drawable Resource | The avatar/profile picture of the translator. |
| locales | String, comma-separated | Locales that have been translated by the translator, separated by a single comma with no whitespace, ex: "en,es,zh". |
| blog | String | The website of the translator. |
| String | The email of the translator. |
<licenses>
A list of the open source licenses used by the project. Child elements are <project> tags with attributes that function similar to the <contributor>s ("^" overrides GitHub values, otherwise they're replaced by the GitHub data), except the repository is defined by a repo attribute (starting a value with "^" is obsolete if the repo attribute is not defined).
| Attribute | Type | Description |
|---|---|---|
| title | String / String Resource | The title to show above the licenses (defaults to @string/title_attribouter_licenses / "Open Source Licenses") |
| overflow | Integer (>= -1) | The maximum number of projects to display in the list. Additional projects are displayed in a dialog. If the number is 0, the entire list is replaced with a button titled "View %s" ('%s' being the title attribute). If the number is -1, all of the projects are displayed. |
| showDefaults | Boolean | Whether or not to show the default projects in this list (this library and the projects used by it). |
<project>
| Attribute | Type | Description |
|---|---|---|
| repo | String (name/repository) | The GitHub repository to fetch the license's information from. |
| title | String / String Resource | The name of the project (will be generated from the repository name if not present, ex: "TheAndroidMaster/ColorPickerDialog" -> "Color Picker Dialog"). |
| description | String / String Resource | A description of what the project contains. |
| website | String / String Resource | A URL of the website for the project. |
| license | String | The "key" of the license the project is under. This will cause Attribouter to fetch information from the GitHub Licenses API. |
| licenseName | String / String Resource | The name of the license. |
| licenseBody | String / String Resource | The content of the license. |
| licenseUrl | String / String Resource | The URL of the license. |
<link>
Attributes for this tag are the same as the ones described under the <appInfo> tag above.
Auto-generated links for the <project> tag are as follows:
| ID | Description | Required Attributes |
|---|---|---|
| github | The github repo of the project. | repo |
| website | The project's website. | website or repo (if the project has a website defined on their GitHub repo) |
| license | Information about the license that the project is under. | license, licenseUrl, or repo (if the repo's license is supported by the GitHub API) |