1<#--
2        Copyright 2013 The Android Open Source Project
3
4        Licensed under the Apache License, Version 2.0 (the "License");
5        you may not use this file except in compliance with the License.
6        You may obtain a copy of the License at
7
8        http://www.apache.org/licenses/LICENSE-2.0
9
10        Unless required by applicable law or agreed to in writing, software
11        distributed under the License is distributed on an "AS IS" BASIS,
12        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13        See the License for the specific language governing permissions and
14        limitations under the License.
15-->
16
17Steps to implement CardStream template:
18-in template-params.xml.ftl:
19    -add the following templates
20        <template src="base"/>
21        <template src="CardStream"/>
22    -add the following line to common imports
23        <common src="activities"/>
24        <common src="logger"/>
25
26-Add a Fragment to handle behavior.  In your MainActivity.java class, it will reference a Fragment
27 called (yourProjectName)Fragment.java.  Create that file in your project, using the "main" source
28 folder instead of "common" or "templates".
29   For instance, if your package name is com.example.foo, create the file
30   src/main/java/com/example/foo/FooFragment.java
31
32-Now it's time to deal with cards. Implement a method like this in your Fragment to access the CardStream:
33private CardStreamFragment getCardStream() {
34    if (mCards == null) {
35        mCards = ((CardStream) getActivity()).getCardStream();
36    }
37    return mCards;
38}
39
40
41-Create a instance of Card.Builder with a tag String that *must* be unique among all cards.
42
43	Card.Builder builder = new Card.Builder(UNIQUE_TAG_STRING);
44
45-Set the properties for your card in the builder. Some properties (title, description, progress type) can also
46be changed later.
47
48	builder.setTitle(String title)
49
50-Cards can also have more than one action that is shown as a button at the bottom of the card.
51All actions *must* be defined through the builder. They can be hidden or shown later again, but they must be defined
52in the builder before .build() is called.
53
54-To implement an action, use Builder.addAction with a label, id, type (Neutral/Positive/Negative) and
55 a CardActionCallback.
56 Actions can be distinguished by their id to avoid the use of a large number of unnamed callback instances.
57 For convenience, the tag of the card the action belongs to is also returned in the callback.
58
59        builder.addAction(actionLabel1, 0, Card.ACTION_NEUTRAL, new Card.CardActionCallback() {
60            @Override
61            public void onClick(int cardActionId, String tag) {
62		...
63            }
64        });
65
66
67-After finishing setup process, call Buidler.build() to return a new instance of a Card.
68
69        final Card card = builder.build(activity);
70
71-Inside your MainActivity.java class, call getCardStream() to get the instance of the CardStreamFragment through
72which cards are shown on screen.
73A card needs to be added to the CardStreamFragment first before it can be shown.
74Cards are identified by their unique tag.
75
76        Card myCard = ...
77        getCardStreamFragment().addCard(myCard);
78        getCardStreamFragment().show(myCard.getTag());
79        getCardStreamFragment().hide("MyCardTag");
80        getCardStreamFragment().show("MyCardTag",false); // can't be dismissed by user
81
82
83