From a25db62c62230721d6479d083b978f130a072c1e Mon Sep 17 00:00:00 2001 From: James Fenn <18jafenn90@gmail.com> Date: Wed, 19 Sep 2018 13:46:41 -0400 Subject: [PATCH 1/7] switched file names to lowercase --- docs/README.md | 34 +-- docs/{RESOURCES.md => resources.md} | 38 +-- docs/{SUBWEDGING.md => subwedging.md} | 266 +++++++++--------- docs/{THEMING.md => theming.md} | 82 +++--- docs/utils/{CROWDIN.md => crowdin.md} | 0 docs/wedges/{APP.md => app.md} | 0 .../wedges/{CONTRIBUTOR.md => contributor.md} | 0 .../{CONTRIBUTORS.md => contributors.md} | 0 docs/wedges/{LICENSE.md => license.md} | 0 docs/wedges/{LICENSES.md => licenses.md} | 0 docs/wedges/{LINK.md => link.md} | 0 docs/wedges/{TEXT.md => text.md} | 0 docs/wedges/{TRANSLATOR.md => translator.md} | 0 .../wedges/{TRANSLATORS.md => translators.md} | 0 14 files changed, 210 insertions(+), 210 deletions(-) rename docs/{RESOURCES.md => resources.md} (99%) rename docs/{SUBWEDGING.md => subwedging.md} (97%) rename docs/{THEMING.md => theming.md} (98%) rename docs/utils/{CROWDIN.md => crowdin.md} (100%) rename docs/wedges/{APP.md => app.md} (100%) rename docs/wedges/{CONTRIBUTOR.md => contributor.md} (100%) rename docs/wedges/{CONTRIBUTORS.md => contributors.md} (100%) rename docs/wedges/{LICENSE.md => license.md} (100%) rename docs/wedges/{LICENSES.md => licenses.md} (100%) rename docs/wedges/{LINK.md => link.md} (100%) rename docs/wedges/{TEXT.md => text.md} (100%) rename docs/wedges/{TRANSLATOR.md => translator.md} (100%) rename docs/wedges/{TRANSLATORS.md => translators.md} (100%) diff --git a/docs/README.md b/docs/README.md index 9c284d8..3cc1428 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,26 +2,26 @@ Welcome to Attribouter's in-depth documentation page! It provides several exampl ## Tutorials -- [The Configuration File](./CONFIGURATION.md) -- [Overriding Resources and Providing Translations](./RESOURCES.md) -- [Extending A Wedge](./SUBWEDGING.md) -- [Custom Themes](./THEMING.md) +- [The Configuration File](./configuration) +- [Overriding Resources and Providing Translations](./resources) +- [Extending A Wedge](./subwedging) +- [Custom Themes](./theming) ## Docs -- [AppWedge](./wedges/APP.md) -- [ContributorsWedge](./wedges/CONTRIBUTORS.md) - - [ContributorWedge](./wedges/CONTRIBUTOR.md) -- [LicensesWedge](./wedges/LICENSES.md) - - [LicenseWedge](./wedges/LICENSE.md) -- [TranslatorsWedge](./wedges/TRANSLATORS.md) - - [TranslatorWedge](./wedges/TRANSLATOR.md) -- [TextWedge](./wedges/TEXT.md) -- [LinkWedge](./wedges/LINK.md) - - [EmailLinkWedge](./wedges/LINK.md#email) - - [LicenseLinkWedge](./wedges/LINK.md#license) - - [PlayStoreLinkWedge](./wedges/LINK.md#play-store) +- [AppWedge](./wedges/app) +- [ContributorsWedge](./wedges/contributors) + - [ContributorWedge](./wedges/contributor) +- [LicensesWedge](./wedges/licenses) + - [LicenseWedge](./wedges/license) +- [TranslatorsWedge](./wedges/translators) + - [TranslatorWedge](./wedges/translator) +- [TextWedge](./wedges/text) +- [LinkWedge](./wedges/link) + - [EmailLinkWedge](./wedges/link#email) + - [LicenseLinkWedge](./wedges/link#license) + - [PlayStoreLinkWedge](./wedges/link#play-store) ## Automation -- [Fetching CrowdIn Translations](./utils/CROWDIN.md) by [@deletescape](https://github.com/deletescape) +- [Fetching CrowdIn Translations](./utils/crowdin) by [@deletescape](https://github.com/deletescape) diff --git a/docs/RESOURCES.md b/docs/resources.md similarity index 99% rename from docs/RESOURCES.md rename to docs/resources.md index 7605363..9f83ec1 100644 --- a/docs/RESOURCES.md +++ b/docs/resources.md @@ -1,19 +1,19 @@ ---- -title: Overriding Resources and Providing Translations ---- - -# Overriding Resources and Providing Translations - -## Problem - -Currently, Attribouter fetches its information from two different locations: the configuration file that you write, and the GitHub API. However, there will occasionally be some information that is provided by both the file and GitHub. Because Attribouter gets the information from the GitHub API shortly after processing the configuration file, the obvious behavior would be to simply replace the information from the configuration file with its GitHub counterpart. However, that isn't a perfect solution, as shown in the following situations: - -- one [`ContributorWedge`](./wedges/CONTRIBUTOR.md) in a [`ContributorsWedge`](./wedges/CONTRIBUTORS.md) does not have a GitHub counterpart, but all of the others do; it would disappear -- a [`ContributorWedge`](./wedges/CONTRIBUTOR.md) has an `email` attribute, but its GitHub counterpart does not provide one; it would disappear -- the [`AppWedge`](./wedges/APP.md)'s `description` attribute is a string resource that is translated into several languages, but the GitHub repositories description is in English; it would always display in English - -## Solution - -In order to work around these situations, rather than simply replacing duplicate information, Attribouter "merges" them together. Using this method, if an attribute is in the configuration file that doesn't have a GitHub counterpart, it is kept, but all others are overwritten. Likewise, [`ContributorWedge`](./wedges/CONTRIBUTOR.md)s inside of a [`ContributorsWedge`](./wedges/CONTRIBUTORS.md) are merged if their `login` attributes match, and are left alone if they do not (ex: contributors in the config file not present on GitHub are left in the list, and contributors not in the config file but present on GitHub are added as well). - -However, you may notice that this solution does not account for the last situation, as it isn't possible to detect this automatically. As a workaround, Attribouter looks for a "^" character at the start of an attribute before merging it. If present, it will ignore its GitHub counterpart. In other words, if the translated string was `@string/app_desc`, the `description` attribute can be set to `^@string/app_desc` to prevent it from being overwritten by the GitHub data. +--- +title: Overriding Resources and Providing Translations +--- + +# Overriding Resources and Providing Translations + +## Problem + +Currently, Attribouter fetches its information from two different locations: the configuration file that you write, and the GitHub API. However, there will occasionally be some information that is provided by both the file and GitHub. Because Attribouter gets the information from the GitHub API shortly after processing the configuration file, the obvious behavior would be to simply replace the information from the configuration file with its GitHub counterpart. However, that isn't a perfect solution, as shown in the following situations: + +- one [`ContributorWedge`](./wedges/CONTRIBUTOR.md) in a [`ContributorsWedge`](./wedges/CONTRIBUTORS.md) does not have a GitHub counterpart, but all of the others do; it would disappear +- a [`ContributorWedge`](./wedges/CONTRIBUTOR.md) has an `email` attribute, but its GitHub counterpart does not provide one; it would disappear +- the [`AppWedge`](./wedges/APP.md)'s `description` attribute is a string resource that is translated into several languages, but the GitHub repositories description is in English; it would always display in English + +## Solution + +In order to work around these situations, rather than simply replacing duplicate information, Attribouter "merges" them together. Using this method, if an attribute is in the configuration file that doesn't have a GitHub counterpart, it is kept, but all others are overwritten. Likewise, [`ContributorWedge`](./wedges/CONTRIBUTOR.md)s inside of a [`ContributorsWedge`](./wedges/CONTRIBUTORS.md) are merged if their `login` attributes match, and are left alone if they do not (ex: contributors in the config file not present on GitHub are left in the list, and contributors not in the config file but present on GitHub are added as well). + +However, you may notice that this solution does not account for the last situation, as it isn't possible to detect this automatically. As a workaround, Attribouter looks for a "^" character at the start of an attribute before merging it. If present, it will ignore its GitHub counterpart. In other words, if the translated string was `@string/app_desc`, the `description` attribute can be set to `^@string/app_desc` to prevent it from being overwritten by the GitHub data. diff --git a/docs/SUBWEDGING.md b/docs/subwedging.md similarity index 97% rename from docs/SUBWEDGING.md rename to docs/subwedging.md index 2b457d6..f17c86c 100644 --- a/docs/SUBWEDGING.md +++ b/docs/subwedging.md @@ -1,133 +1,133 @@ ---- -title: Extending a Wedge ---- - -# Extending a Wedge - -Since the wedges used in the layout file are referenced by their corresponding class name, you may have guessed that it is possible to create your own wedge similarly to how one would create a custom view. You would be correct in that assumption. That said, because there are so many different use cases for this, I'm not going to provide a full "tutorial", but rather explain the basics of how wedges can be created. - -## Creating the Class - -The absolute minimum requirements for a wedge class are that they must extend `me.jfenn.attribouter.wedges.Wedge` and have a public constructor that accepts an `android.content.res.XmlResourceParser`. However, there are several additional suggestions that can affect... things... if they are not followed: - -- Because wedges are added to a `RecyclerView`, they can have a subclass extending `me.jfenn.attribouter.wedges.Wedge$ViewHolder`, though this is not required. This class can be defined as a generic type of the `Wedge` class that your wedge class is extending, if that makes any sense (I don't know what I'm saying, just look at the example below and you'll see what I mean). -- Inside the constructor, you must call `super()` with the resource of the layout file that you want your wedge to use. -- You can then use the instance of `XmlResourceParser` to collect any XML arguments you want. -- After this, your constructor should end with a call to `addChildren(XmlResourceParser)`, which will parse and add any child wedges to a list that you can access (if your element has child wedges and there is not a call to this method in your constructor, it is very likely that you will encounter several issues as a result). - -Here is a basic example of what has been described so far: - -```java -public class MyWedge extends Wedge { - - public MyWedge(XmlResourceParser parser) { - super(R.layout.my_wedge_layout); - //get attributes - addChildren(parser); - } - - //other methods - - public static class MyViewHolder extends ViewHolder { - - public MyViewHolder(View v) { - super(v); - } - - } - -} -``` - -## Implementing Methods - -There are also several abstract methods in `Wedge` that must be defined. Rather than explain all of them, I will simply implement them all in the above example along with comments explaining what should happen where. - -```java -public class MyWedge extends Wedge { - - //define information in your Wedge class - - public MyWedge(XmlResourceParser parser) { - super(R.layout.my_wedge_layout); - //instantiate attributes - addChildren(parser); - } - - @Override - public MyViewHolder getViewHolder(View v) { //"v" is the inflated layout file that you passed the resource of in your call to super() - return new MyViewHolder(v); //yep, that's all you really need - } - - @Override - public void bind(Context context, MyViewHolder viewHolder) { - //here you bind the data in your wedge class to the views in the MyViewHolder instance - } - - public static class MyViewHolder extends ViewHolder { - - //define views in your layout - - public MyViewHolder(View v) { - super(v); - //instantiate views - "view = v.findViewById(...);" - } - - } - -} -``` - -## GitHub Requests - -If you wish to make a request to the GitHub API from your wedge, simply call `addRequest(GitHubData)` with an instance of one of the [classes extending GitHubData](../attribouter/src/main/java/me/jfenn/attribouter/data/github/), or you can create your own. Thanks to [GSON](https://github.com/google/gson)'s magic, this is ridiculously simple, and if you've gotten this far you can probably figure it out yourself just by looking at the source code. - -After calling `addRequest()` with an instance of `GitHubData`, Attribouter will obtain and parse the data itself (as well as caching, combining duplicate requests, and other complicated things), and will pass it back to the `onInit(GitHubData)` method - which you should probably extend - of your wedge class, where you can modify any of your wedge's data with the information you have obtained. Once `onInit` has been called, Attribouter will notify the RecyclerView of a change to your wedge, and you wedge's `bind()` method will be called shortly afterwards. - - As an example, here is a wedge based on the previous examples that initially displays my name in a TextView as "James Fern", then makes a request to GitHub, correcting it to "James Fenn": - - ```java -public class MyWedge extends Wedge { - - private String myName; - - public MyWedge(XmlResourceParser parser) { - super(R.layout.this_is_a_textview); - - myName = "James Fern"; - addRequest(new UserData("TheAndroidMaster")); - - addChildren(parser); - } - - @Override - public MyViewHolder getViewHolder(View v) { - return new MyViewHolder(v); - } - - @Override - public void bind(Context context, MyViewHolder viewHolder) { - viewHolder.textView.setText(myName); - } - - @Override - public void onInit(GitHubData data) { - if (data instanceof UserData) { - UserData user = (UserData) data; - myName = user.name; - } - } - - public static class MyViewHolder extends ViewHolder { - - TextView textView; - - public MyViewHolder(View v) { - super(v); - textView = (TextView) v; - } - - } - -} -``` +--- +title: Extending a Wedge +--- + +# Extending a Wedge + +Since the wedges used in the layout file are referenced by their corresponding class name, you may have guessed that it is possible to create your own wedge similarly to how one would create a custom view. You would be correct in that assumption. That said, because there are so many different use cases for this, I'm not going to provide a full "tutorial", but rather explain the basics of how wedges can be created. + +## Creating the Class + +The absolute minimum requirements for a wedge class are that they must extend `me.jfenn.attribouter.wedges.Wedge` and have a public constructor that accepts an `android.content.res.XmlResourceParser`. However, there are several additional suggestions that can affect... things... if they are not followed: + +- Because wedges are added to a `RecyclerView`, they can have a subclass extending `me.jfenn.attribouter.wedges.Wedge$ViewHolder`, though this is not required. This class can be defined as a generic type of the `Wedge` class that your wedge class is extending, if that makes any sense (I don't know what I'm saying, just look at the example below and you'll see what I mean). +- Inside the constructor, you must call `super()` with the resource of the layout file that you want your wedge to use. +- You can then use the instance of `XmlResourceParser` to collect any XML arguments you want. +- After this, your constructor should end with a call to `addChildren(XmlResourceParser)`, which will parse and add any child wedges to a list that you can access (if your element has child wedges and there is not a call to this method in your constructor, it is very likely that you will encounter several issues as a result). + +Here is a basic example of what has been described so far: + +```java +public class MyWedge extends Wedge { + + public MyWedge(XmlResourceParser parser) { + super(R.layout.my_wedge_layout); + //get attributes + addChildren(parser); + } + + //other methods + + public static class MyViewHolder extends ViewHolder { + + public MyViewHolder(View v) { + super(v); + } + + } + +} +``` + +## Implementing Methods + +There are also several abstract methods in `Wedge` that must be defined. Rather than explain all of them, I will simply implement them all in the above example along with comments explaining what should happen where. + +```java +public class MyWedge extends Wedge { + + //define information in your Wedge class + + public MyWedge(XmlResourceParser parser) { + super(R.layout.my_wedge_layout); + //instantiate attributes + addChildren(parser); + } + + @Override + public MyViewHolder getViewHolder(View v) { //"v" is the inflated layout file that you passed the resource of in your call to super() + return new MyViewHolder(v); //yep, that's all you really need + } + + @Override + public void bind(Context context, MyViewHolder viewHolder) { + //here you bind the data in your wedge class to the views in the MyViewHolder instance + } + + public static class MyViewHolder extends ViewHolder { + + //define views in your layout + + public MyViewHolder(View v) { + super(v); + //instantiate views - "view = v.findViewById(...);" + } + + } + +} +``` + +## GitHub Requests + +If you wish to make a request to the GitHub API from your wedge, simply call `addRequest(GitHubData)` with an instance of one of the [classes extending GitHubData](../attribouter/src/main/java/me/jfenn/attribouter/data/github/), or you can create your own. Thanks to [GSON](https://github.com/google/gson)'s magic, this is ridiculously simple, and if you've gotten this far you can probably figure it out yourself just by looking at the source code. + +After calling `addRequest()` with an instance of `GitHubData`, Attribouter will obtain and parse the data itself (as well as caching, combining duplicate requests, and other complicated things), and will pass it back to the `onInit(GitHubData)` method - which you should probably extend - of your wedge class, where you can modify any of your wedge's data with the information you have obtained. Once `onInit` has been called, Attribouter will notify the RecyclerView of a change to your wedge, and you wedge's `bind()` method will be called shortly afterwards. + + As an example, here is a wedge based on the previous examples that initially displays my name in a TextView as "James Fern", then makes a request to GitHub, correcting it to "James Fenn": + + ```java +public class MyWedge extends Wedge { + + private String myName; + + public MyWedge(XmlResourceParser parser) { + super(R.layout.this_is_a_textview); + + myName = "James Fern"; + addRequest(new UserData("TheAndroidMaster")); + + addChildren(parser); + } + + @Override + public MyViewHolder getViewHolder(View v) { + return new MyViewHolder(v); + } + + @Override + public void bind(Context context, MyViewHolder viewHolder) { + viewHolder.textView.setText(myName); + } + + @Override + public void onInit(GitHubData data) { + if (data instanceof UserData) { + UserData user = (UserData) data; + myName = user.name; + } + } + + public static class MyViewHolder extends ViewHolder { + + TextView textView; + + public MyViewHolder(View v) { + super(v); + textView = (TextView) v; + } + + } + +} +``` diff --git a/docs/THEMING.md b/docs/theming.md similarity index 98% rename from docs/THEMING.md rename to docs/theming.md index 56bdba4..92fe603 100644 --- a/docs/THEMING.md +++ b/docs/theming.md @@ -1,41 +1,41 @@ ---- -title: Custom Themes ---- - -## Activity / Dialog Themes - -By default, Attribouter uses an extension of `Theme.AppCompat.Light.NoActionBar` as its activity theme. The contributor and license dialogs use `ThemeOverlay.AppCompat.Dialog`, and fullscreen dialogs (overflow screens) use an extension of the activity theme with a window animation. - -There are multiple ways that you can change these themes, but I know that this one works, so I am going to do this. If you are using Attribouter as a fragment, you can skip the first part since it will use whatever theme you have set for the activity that the fragment is in. - -### Overriding the Activity Theme - -First, add a new style resource to your `styles.xml` titled "AttribouterTheme". This will override the theme defined by Attribouter that it uses by default. The theme's parent should be "Theme.AppCompat.something", preferably ending with ".NoActionBar" since Attribouter's activity has one of its own. For example, if you wanted to use a dark theme, you would use `Theme.AppCompat.NoActionBar` as follows: - -```xml - - - - + +