CUSTOMIZATION.md

ChangeLog Library Customization and Tips

There are many ways you can customize the changelog view.

• Custom Header Layout
• Custom Row Layout
• Layouts with Material Specs
• Custom ChangeLog XML
• Bullet Point
• Html Text Markup
• Customize Strings
• Use an url to download the changelog.xml file
• Bug and improvement tags
• Emtpy view

Custom Header Layout

Library uses res/layout/changelogrowheader_layout.xml XML layout for each header.
You can use your own xml layout with chg:rowHeaderLayoutId attribute in ChangeLogListView element.

    <!-- Custom xml file Example and custom header layout -->
    <view xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:chg="http://schemas.android.com/apk/res-auto"
          class="it.gmariotti.changelibs.library.view.ChangeLogListView"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          chg:rowHeaderLayoutId="@layout/demo_changelogrowheader_layout"
    />

The quickest way to start with this would be to copy the changelogrowheader_layout.xml layout resource file from this project into your own and modify its contents.
There's a specific set of views you need to have in your layout:

1. A TextView with the ID chg_headerVersion that display the Version Number
2. A TextView with the ID chg_headerDate that display the Version Date

You can find an example in demo_changelogrowheader_layout.xml

Custom Row Layout

Library uses res/layout/changelogrow_layout.xml XML layout for each row.
You can use your own xml layout with chg:rowLayoutId attribute in ChangeLogListView element.

    <!-- Custom xml file Example and custom header layout -->
    <view xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:chg="http://schemas.android.com/apk/res-auto"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          class="it.gmariotti.changelibs.library.view.ChangeLogListView"
          chg:rowLayoutId="@layout/demo_changelogrow_layout"
    />

The quickest way to start with this would be to copy the changelogrow_layout.xml layout resource file from this project into your own and modify its contents.
There's a specific set of views you need to have in your layout:

1. A TextView with the ID chg_textbullet that display the bullet point
2. A TextView with the ID chg_text that display the actual text that will be displayed as a change in your List

You can find an example in demo_changelogrow_layout.xml

Layouts with Material Specs

Library contains also 2 layouts with Material specs and metrics:

• res/layout/changelogrow_material_layout.xml l XML layout for each row.
• res/layout/changelogrowheader_material_layout.xml l XML layout for each header.

You can use them with a simple:

    <!-- Material layout -->
     <view
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        class="it.gmariotti.changelibs.library.view.ChangeLogListView"
        android:id="@+id/view"
        android:paddingBottom="8dp"
        android:paddingTop="8dp"
        android:clipToPadding="false"
        android:scrollbarStyle="outsideOverlay"
        chg:rowHeaderLayoutId="@layout/changelogrowheader_material_layout"
        chg:rowLayoutId="@layout/changelogrow_material_layout"
        android:layout_gravity="center"
        />

You can find an example in demo_changelogrow_fragment_material.xml You can find a screenshot here.

Custom ChangeLog XML

Library uses res/raw/changelog.xml. You can use your own file with chg:changeLogFileResourceId attribute in ChangeLogListView element.

    <!-- Custom xml file Example and custom header layout -->
    <view xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:chg="http://schemas.android.com/apk/res-auto"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          class="it.gmariotti.changelibs.library.view.ChangeLogListView"
          chg:changeLogFileResourceId="@raw/custom_changelog"
    />

You can find an example in demo_changelogrow_fragment_customlayout.xml

Bullet Point

The quickest way to customize this character is to specify this resource in your strings.xml.

   <string name="changelog_row_bulletpoint">\u2022"</string>

If you don't want a bullet list you can specify it in changelog.xml file with bulletedList="false" attribute.

    <?xml version="1.0" encoding="utf-8"?>
    <changelog bulletedList="false">
        .....
    </changelog>

Html Text Markup

You can use some html text markup as bold and italic in your changelog.xml

   <changelogversion versionName="0.9" changeDate="Aug 11,2013">
        <changelogtext>[b]New![/b] Add new attrs to customize header and row layout</changelogtext>
        <changelogtext>Fixed log while [i]parsing[/i] </changelogtext>
        <changelogtext>performance &lt;b&gt;improvement&lt;/b&gt;</changelogtext>
        ....

You can use:

1. [b] text [/b] for a bold style, or <b> text </b>
2. [i] text [/i] for an italic style, or <b> text </i>

If you need a hiperlink you can obtain it with:

    <changelogbug>Fixed a [a href="http://www.google.it"]number[/a] of bugs with the
              Gmail and SMS extensions</changelogbug>

Of course you can use standard android notation:

     <changelogimprovement><![CDATA[Option to specify a <a href="http://www.google.it">manual</a>
                               location for weather]]></changelogimprovement>
     <changelogtext><![CDATA[<b><font color=red>New!</font></b> Translations for Greek,
                   Dutch and Brazilian Portuguese]]>
     </changelogtext>

Customize Strings

You can customize Version String in header.
The quickest way to customize this character is to specify this resource in your strings.xml.

<string name="changelog_header_version">"Revision "</string>

Use string with quotes if you want a space.

You can also customize other strings in the same way. See original res/string.xml in library.

Use an url to download the changelog.xml file

Library uses res/raw/changelog.xml. You can use a url link to download your xml file with chg:changeLogFileResourceUrl attribute in ChangeLogListView element.

    <!-- Custom xml file Example and custom header layout -->
    <view xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:chg="http://schemas.android.com/apk/res-auto"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          class="it.gmariotti.changelibs.library.view.ChangeLogListView"
          chg:changeLogFileResourceUrl="http://mydomain.org/changelog.xml"
    />

Pay attention: To use this feature you have to add these user-permissions to your app:

    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />

Bug and improvement tags

You can use 2 custom changelogtext tags that will pre-pend the change log text with Bug: and New: respectively.

   <changelogversion versionName="0.9" changeDate="Aug 11,2013">
        <changelogtext>[b]New![/b] Add new attrs to customize header and row layout</changelogtext>
        <changelogimprovement>Option to specify a manual location for weather</changelogimprovement>
        <changelogtext>performance &lt;b&gt;improvement&lt;/b&gt;</changelogtext>
        <changelogbug>Fixed a number of bugs with the Gmail and SMS extensions</changelogbug>
   </changelogversion>

You can customize the prefix text in your project overriding these values in strings.xml

    <!-- Prefix for Bug type change log -->
    <string name="changelog_row_prefix_bug">[b]Bug:[/b]</string>

    <!-- Prefix for Improvement type change log -->
    <string name="changelog_row_prefix_improvement">[b]New:[/b]</string>

You can use the same html text markup described above.

Empty view

If you are using a large xml file, or you are using an url to download the changelog file, it would be nice to display an empty view until the list is ready.

The ChangeLogListView extends a ListView and you can easy use the standard list.setEmptyView() method to provide your custom view.

For example:

        ChangeLogListView list = (ChangeLogListView) view.findViewById(R.id.myId);
        View empty= (View) view.findViewById(R.id.my_empty_view);
        list.setEmptyView(empty);

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
              xmlns:chg="http://schemas.android.com/apk/res-auto"
              android:orientation="vertical"
              android:layout_width="match_parent"
              android:layout_height="match_parent">

    <!-- Base Example -->
    <view
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            class="it.gmariotti.changelibs.library.view.ChangeLogListView"
            android:id="@+id/myId"
            android:layout_gravity="center"
            />

    <TextView
        android:layout_width="match_parent"
        android:id="@+id/my_empty_view"
        android:gravity="center"
        android:text="Loading data"
        android:layout_height="match_parent"/>

</LinearLayout>

For more detailed information and examples you can read this document: