/ UI

A lightweight about screen library to allow quick but customizable attribution in Android

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
img img img img

Implementation (using the CLI)

img

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 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.
email 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.

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)
email 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.
email 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.

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)

GitHub