Documentation and examples suggestions

[Voyz]

As a continuation of the conversation under this stackoverflow topic I'd like to suggest some improvements to documentation and examples.

1

• A couple of complete basic sample apps (separate from the existing examples) that implement the method A and method B in their simplest form, without headers, animations, fast scroller etc.
• (these should be given separate sample apps or implementation tutorials)

2

• Finish the examples Simple item selection, SINGLE selection mode and How to use.
• While they seem give a good start, they appear to cut off in half.
• The XML samples contain some inconsistencies, while the Java code is not sufficient to implement the item selection or single selection fully.
• There are small indications of what methods need to be used in text descriptions, yet Java code would be much easier to pick up.
• Without displaying code for the whole application, these first-step tutorials should cover all code necessary to implement Flexible Adapter in its simplest form, without needing to refer to example apps.
• I suggest going step by step by the tutorials starting from an empty activity, seeing where it leads to and what's missing to have a working product.

3

• A guide to what needs to inherit what.
• Fact that the model used by FlexibleAdapter is containing a ViewHolder is a significant change to how normal RecyclerView.Adapter works (where ViewHolder and model are separate entities) and should be outlined in detail.
• Also the Item Interfaces are not documented at all, whilst the classes are expected to implement them.

4

• Create library's API reference.

5

• The current example app could use refactoring. I understand its purpose of demonstrating various functionalities of the library, yet they are so heavily intertwined that it requires extensive study to distinguish which code is responsible for which feature.
• One of the most apparent examples is the SimpleItem.
• From reading the code I'm guessing it is used to demonstrate the following functionalities: serialisation, being draggable, swipeable, expandable, searchable, animation, filters, flip view (which also isn't mentioned anywhere in docs), handles, and containing the ViewHolder. That last thing was the only piece of information I was looking for, and I assume is the only required information from that list that would help to get started, while every thing else seems like an extra.
• Also there seem to be inconsistencies here too, where for instance SimpleItem suggests to extend directly from AbstractFlexibleItem, yet iteslf extends from AbstractModelItem. Surely, digging through you can see the first in turn extends the second, yet that's not very consistent there.

6

• Proofreading

Most importantly - I'm very positive about this project, I think it's great! Exactly because it is such a great library it is even more unlucky it lacks a good documentation. It does contain a ton of very useful code, simplifying and extending the RecyclerView. Linking the ViewHolder and the model seems like a great idea. Nonetheless, I gave up after a day of working around the example app and sparse docs to get simplest selection working, though it surely may be my deductive skills being below average.

Whilst the code seems to provide a great functionality, lack of supporting documentation may hide it from a far greater bunch of devs using it in their apps - and they should use it!

[davideas]

Hi @Voyz, what a long message :-) it means that you really want to help, I appreciate it.

Before I reply on the single points, please keep in mind that, in general, I had few time in the previous months, but I will try to modify the demo App, to make the code clearer to understand also for a newbie in Android. However, all these changes will take some months, because I am the only one working on it. Consider that 4 months ago the demo app was only a single activity. Then, lib grew and I decided to keep what I already had adding some fragments... I believe it is much better now.
But I also agree that now, the examples are too much linked each other's, that leads to a confusion for a person not familiar with Android (it's always difficult to read the code of others by the way).

Point 1) I agree, but instead of making 2 new separated apps to maintain, install and present around, I would prefer to keep the idea of the separating the examples in the same App, maybe 2-3 activities, but this time, independent from all the rest.

Point 2) I'm sorry that you commented the version 4.2 for the single selection. That part in the Wiki is well separated from 5.0 and I do not maintain it anymore. I'm focusing on the new version (I will remove 4.2 pages, when the new part is ready, I can't now).

If you check better I already started to update and add the new wiki pages for version 5.0. However your remarks for the Selection Tutorial will be taken into account when I will rewrite it.

Point 3-4) You will not believe but in these days I was thinking to that.

Point 5) It is linked to the point 1.

• I will try to make fragments more independent from the activity.
• FlipView is my other library, everything is in that project.
• The reason why SimpleItem extends AbstractModelItem is because I use the same object for multiple examples, so maybe I will create more items dedicated only for a single example, the reason is also written in the comment of the classes.
• Selection was clear and well easy to understand in the code with versions prior to 5, only because there were only 3-5 functionalities. Now, it is still simple, but it is not well visible as you suggested.

As your last consideration, I would like this library becomes a central reference for the Adapter for many developers, unfortunately I have few time to dedicate and to reorganize the code in such way. However, I don't give up, a step by step I will do it.

[Voyz]

Hey @davideas, thanks for your reply. It all seems I've joined in to the situation in an unlucky moment of transition between 4.x and 5.x. I understand your library has grown very quick which is great, and naturally needs time to get everything documented. I'm glad you agreed with me on some points and explained some of my questions. As for particular points:

1. Either way in fact, as long as the app demonstrates a basic implementation it should be a great starting point. In fact, it seems that Method A is sort of the way to go for FlexibleAdapter since 5.x, why not deprecate Method B entirely? And this way one example app will be even more specific and easy to understand.
2. Sure, I understand. I'd suggest maybe removing the misleading examples and wiki sections in that case. It's probably better to be left out with no information than with incorrect information.
3. Great
4. Great!
5. Once again, it all makes sense, I know the feeling of pushing the library forward, sometimes it gets a little out of hand. It's certainly good to have the examples of all the functionalities. Maybe once understanding the basics, the all-in-one example app is not that difficult to go through in order to learn the advanced features, yet like we noticed, the simple use case is not quite visible.

Best of luck and thanks for replying. If you come up with some simpler examples and more thorough tutorials I'd be happy to give them a test and give you feedback if you'd like that.

[davideas]

@Voyz, I started to review the documentation entirely, what do you think? :-)

[Voyz]

@davideas Hey mate, sorry for a delay, been away for a while.

The new documentation is a big step forward, well done!

I'm going through Setting Up page to try out the basic implementation and I have run into some compilation problems.

I think name ViewHolder is easily clashing with the RecyclerView.ViewHolder if import android.support.v7.widget.RecyclerView; is present. I changed it to MyViewHolder to make it non-ambiguous and the generic name to VH.

VH generic is required to extend RecyclerView.ViewHolder, which implies following class declaration

public class Item<VH extends Item.MyViewHolder> extends AbstractFlexibleItem<VH> 

But then, VH passed as a generic type of the Item class can not be instantiated in createViewHolder function:

@Override
public VH createViewHolder(FlexibleAdapter adapter, LayoutInflater inflater,
                                   ViewGroup parent) {
    return new VH(inflater.inflate(getLayoutRes(), parent, false), adapter);
}

which required casting MyViewHodler to VH like so

@Override
public VH createViewHolder(FlexibleAdapter adapter, LayoutInflater inflater,
                           ViewGroup parent) {
    return (VH) new MyViewHolder(inflater.inflate(getLayoutRes(), parent, false), adapter);
}

Why is MyViewHolder passed on as a generic type anyway? Wouldn't it be easier to just declare item as follows:

public class Item extends AbstractFlexibleItem<Item.MyViewHolder> 

I've modified the wiki page to reflect these changes along with a little more information to get started.

[davideas]

Hi @Voyz, thanks for the modifications, I've adapted a little, to have initialization explanation at the top.

The following class declaration is wrong, that is already final for the usage:

public class MyItem<VH extends MyItem.MyViewHolder> extends AbstractFlexibleItem<VH> 

What you have done is another user-level of Generic, you just need to have MyItem as following. Having this you don't need to cast, because VH is already defined as MyViewHolder:

public class MyItem extends AbstractFlexibleItem<MyItem.MyViewHolder> 

[Voyz]

@davideas Great! I'm glad I could help, I think the setting up page gives a clear indication on getting started

[7robertodantas]

A couple of complete basic sample apps (separate from the existing examples) that implement the method A and method B in their simplest form, without headers, animations, fast scroller etc.
(these should be given separate sample apps or implementation tutorials)

The XML samples contain some inconsistencies, while the Java code is not sufficient to implement the item selection or single selection fully.

That's really true. Since yesterday i am trying to import to my own project the instagram header sample and yet i could not finish it.

I am almost giving up to trying to use this library. I just want one feature that is the header stick in recycler view, but the sample project has a lot of stuff.

[davideas]

@7robertodantas, at the beginning of the review it might appear complex, Let me show you how is designed the demoApp (in the wiki there's a page dedicated to it).

1. We have the MainActivity which extends most of the listeners from the Adapter like clicks, undo and updates (etc.), the Activity also supports the ActionMode for multi selection. The instance of the Adapter is also received from the fragments for the current example displayed.
2. The Fragments represents the single examples (use cases) how the Adapter can be configured and they extend the AbstractFragment for the common functions.
3. Depends which use case is selected, the list of items is generated at run time using the DatabaseService, and yes, some items are reused in different examples.
4. Then we have the new ViewPagerActivity for the example of sticky headers with ViewPager.

For sticky headers, you need to prepare the items for Headers (IHeader or AbstractHeaderItem) and the normal item (ISectionable or AbstractSectionableItem) which has the header reference inside, (I suggest the abstract classes). Then you design the layouts for both of these items, which auto generate the R class.
Then you need something to generate these items in a list, that is your "database".
Then you setup the Adapter by passing the copy of that list. The rest of the configuration for sticky headers is in the Wiki page for Headers and Sections and in the fragment.
You only extend the FlexibleAdapter if you need more customization, otherwise you can use it directly.

Consider always that, there are the Wiki pages + the javaDoc of the classes for each method.
Consider also that this version is still in beta and that I'm alone, the wiki has to be completed and reviewed again a bit. If you need specific help, you can open a new issue.

[7robertodantas]

@davideas

Thank you so much!! This last comment was very helpful. Although I have looked at the wiki was still a little confused by some additional complexities of the sample project. But with this simple and straightforward comment I could understand better.

[rayliverified]

Setting Up section of the Tutorial does not provide complete code to set up project. For example, in the initializing code, the code snippet is provided without context.
// Initialize the RecyclerView and attach the Adapter to it as usual recyclerView.setAdapter(adapter);
Where should the initialization code be placed? How should "recyclerView" be declared? It would really help new users if all the code required to get Flexible Adapter up and running was included. All the user would need to do is copy and paste. Once a user understands the basic functionality and has something up and running, the more complex customizations and usage will start making sense a lot faster.

Thanks for reading this feedback and your work on this library. I hope to be able to use it soon!

[davideas]

@searchy2, I count that, the users of this library knows how RecyclerView works, if not they should read more about it, since it is an official component of Android, not mine.

[rayliverified]

@davideas I did not understand that this library was just an Adapter extension. I thought it was a complete RecyclerView replacement. My mistake!

[davideas]

With RC2 release the Method A has been deprecated and removed from wiki
Many the wiki pages have been reviewed, the remaining will be updated soon.
DemoApp has been revisited a bit, even if the basic architecture remains the same, but considering the period this issue was created, a lot has been done.

The new issue #380 is open for discussion.

PS. However, with RC3 I will try to simply again the examples, adding new ones and completely rewrite the demoApp, it is in the to do list, so I consider closed this issue.