Introduction to IjoomerAdvance SDK for Joomla on Android

iJoomer Advance is an SDK which can be integrated into an existing project as well as be used as a stand-alone project. This SDK can be used as a CMS (Joomla CMS) as well as a Social Network (JomSocial component of Joomla). So, in all, you can have your very own Mobile CMS as well as Mobile Social Networking App of your own

To avoid you the hassle of developing stuff from scratch, we provide everything readymade so that you can easily use / re-use and extend it as per your needs.

Let us examine how iJoomer Advance for Android Native app is structured. Basically, it can be divided into three major parts as under:

  • Core Library
  • Data Provider Library
  • Implementation

Core Library

As name suggests, this is the core of the mobile cms application for Android.

Server Communication

Server Communication consists that part of the code which is responsible for communicate from the server to fetch data. While fetching data from the server, “server communication” handles sessions, security settings, verifies the network availability and validates the returned data.

Intelligent Data Caching

Once data is received, appropriate caching inside the sqlLite database is done. And depending upon the lifecycle of the data, it is cached and recycled.

In nutshell, the core library decides whether the data should be retrieved from the cached database or the live server.

What’s really interesting is that while the live data is being loaded from the server, cached data is automatically displayed on the screen so that your user doesn’t have to wait for a response and has something to read while data is loading.

Data Parsing

Once the data is received from the server, it has to be parsed in a way that your activities get it. So, the JSON data gets parsed and is further sent to the cache library for insertion process. On another thread, the parsed data is returned to the DataProvider Library which requested a response for a certain activity.

DataProvider Libraries

The Data Provider Library contains classes for web-service calls to the server. It contains multiple functions which are invoked by activities. Each function has certain arguments which need to be passed so as to process a request.

The simplest example would be to get the list of featured articles in iCMS.

In this case, no argument is passed, but the function creates the requested argument, sends it to the core part for data, and receives an object with the values which is then returned to your activity.

Some functions do have arguments present, like login/authentication; where your activity calls this function with username and password arguments and in return, receives full object of the user if authentication is through or an error message, if login credentials are wrong.

For each of your activity screens, there is a variety of readily available functions which are getting called; hence, you don’t have you write codes for making calls. These are read-only functions which cannot be modified so as to receive consistency.

But, if you need any additional data from the server which iJoomer Advance doesn’t provide by default, you can get it inside the custom data array which you can parse as per your requirements.

Each Joomla Component you use, has its own data provider library, like iCMS (Joomla Content) has its own data provider and JomSocial has its own. Depending upon the component you want to use in your Android Mobile Application, you can decide which one to include.

Implementation

This part consists of implementation of the java classes (Activities). As a developer, this is your playground and you can customize the app related to Branding, Color Theme, layout alterations, style edits, adding your own view/screen and attaching it to the already created classes.

Virtually, 80% of your customization part will be happening in this part and that’s the reason we have kept this part at the disposal of developer.

Installation Instructions

STEP 1: Install the Pre-requisite

You need Eclipse, the Android SDK and the ADT plugin.

Eclipse is the most popular choice for developing Android apps.

Eclipse is one of the most commonly used IDE for development of Android apps. 'Eclipse Classic' can be found on downloads page. You need Java v1.6 or later as well as using Eclipse v4.2 (Juno) or later.

After installing Eclipse, download the Android SDK, available from the Android Developers site, and install it.

You will be required to have the Android 2.2 (API 8) components installed in order to use the iJoomerAdvance SDK.

You should now see two new icons in your Eclipse toolbar and entries in its 'Window' menu to launch the Android SDK Manager and AVD Manager (for device emulators).

Android SDK

Though, you may have a real android device, but its always useful to have and Emulator configured. You can get to “AVD Manager” and create new “AVD” and fill in name and keep simple settings as it is.

Android SDK

You can now start the emulator from AVD manager now OR you can start it once you run your first iJoomerAdvance SDK for the first time.

STEP 2: Install the iJoomer Advance SDK for Android.

Download and extract the SDK ZIP. The resulting folder contains the SDK Project itself which you can use it as stand-alone project as well as Import into existing project.

A. Using it as a New Project.

You can see that there are two folders and one read me file. Two folders are “FacebookSDK” and “IjoomerAdvanceSDK”. We will have to import both of these SDK into your workspace. Make sure there are no old projects named “FacebookSDK” OR “IjoomerAdvanceSDK” in your current workspace, if one exists, then it will be pointing to older versions and can be removed. Alternatively, you can opt to create a new workspace and import the projects there.

To import the SDK project, go to Eclipse “File”->”Import” menu, and Select “General”/ “Existing Project” in project in workspace

Android SDK

Browse to select root of your SDK folder, in our case it will be “ijoomer-adv-joomla-master”. The list should have IjoomerAdvance along with FacebookSDK. Make sure “Copy Projects into Workspace” is Checked so that correct references are built.

Android SDK

Click on Finish. Now, you can see the project in project explorer. You must set compilation target of the project to Google API 3.2 (This is because in-built Admob has API 3.2 as dependency). Though, 3.2 is not a minimum target, but just a compilation target, your app would run with minimum target of Android version google api 2.2.

To set compilation target, right click on project->properties->Android

Android SDK

You are now ready to run iJoomerAdvance Mobile CMS for Joomla CMS.

B. Existing project

In order to add the follow the steps as above and in the last screen where you setup the compilation target, you need to get it setup as library project. To do so, just check “Is Library” checkbox and click okay.

Android SDK

Now you can see that the iJoomerSDK is added as a library project. Next is to attach this library to your exisiting project. To do so, right click on your existing project and click on “property” and then select “Android” tab. After that, you need to click on Add button just under “Library” section of box. From there, select the iJoomerAdvance and then click okay.

Android SDK

Now, check your exisiting project and you will see iJoomerAdvance available inside your own project and you can use it as a library project. In the below scenario com.demo was an existing project under which we added ijoomeradvance library project.

Android SDK

Configure the App

We need to configure the app so that it can connect to your own joomla website as well configure “Facebook” and “Twitter” related settings. To do so explore your project and expand folder “res”->”values”->config.xml [Need image for exploring this folder]

In this file, you can see few settings listed explained as under:

ID of your FB App.
Your Joomla website URL (eg.http://www.ijoomer.com/ijoomeradv/)
Your Twitter Consumer Key
Your Twitter Secret Key
Date Format of the app (eg. yyyy-MM-dd)
Date and time Format of the app(yyyy-MM-dd kk:mm:ss)
Time format of the app (kk:mm:ss)
Setting to allow uploading multiple photos (true/false)
Make Debug mode on or off, making it on will start logging of the app inside the sd card and you can trace for any errors (true/false)
Custom Font, make sure file is present(fonts/Helvetica_LT_55_Roman_0.ttf)
Enable or disable Cache of the application(true/false)

Integrate iJoomer Advance SDK in your existing app

Note:

If you are building new app on the basis of iJoomerAdvance SDK, then SKIP this section.

Integrate iJoomerAdvance in your existing Mobile App

By now, you know how to import the project and use iJoomer Advance for Android as a base to create a new Mobile CMS app. We will further modify the layout of the featured category page which is provided in default layout (listview) to new layout (grid view). This detailed tutorial will explain how to get this done.

Step1:

Lets start with copying the assets which are required. Copy assets folder data from iJoomerAdvance to your project assets folder

Android SDK

STEP 2: Setting up permission

There are certain permissions which are required for the application. So, we will copy those permissions from the Android's Manifest file to existing project. Copy all permission from iJoomerAdvance AndroidManifest.xml file to you project AndroidManifest.xml file (ignore those permissions which are already in your project AndroidManifest.xml file defined).

iJoomerAdvance
                    
                    
                    
                    
                    
                                
                    
                    
                    
        

Existing Project
                
                
                
                
            

STEP3: Extending your existing application to iJoomerAdvance

We need to make sure Application Classes are accessible across your existing app, so we will need to make further alteration in Android Manifest file. Edit existing project's AndroidManifest.xml. In there, look for the application tag under that, look for android:name attribute.

If you find don't find that attribute, just add up the attribute as under android:name="com.smart.framework.SmartApplication"

In case, if you already have that attribute setup, then we must extend the native class to iJoomerAdvance's class. To do so, open the class file of your existing class mentioned in the above tag. In that file, extend the class as under:

Existing Code
            public class MyApplication extends Application {
            /*  Your code  */
            }
            
New Code
            public class MyApplication extends SmartApplication {
            /*  Your code  */
            }
            

Now, you will be able to access iJoomer's classes across your own app without any trouble..

STEP 4: Inherit iJoomerAdvance Theme.

Now is the turn to import the theme part of the application. If your project have own themes defined then your theme must be extend iJoomerAdvance SDK so that it can work in coordination.

To do so, we will need to define "ijoomer_theme" as a parent of your existing theme. Open themes.xml file found under res/values/themes.xml file. To add up ijoomer_theme as a parent of your current theme, we will need to modify it as under:

Current

                
                
                
            

Change to:

            
            
            
            

Now, you must be thinking what happens to previous value in parent tag (i.e. parent="@android:style/Theme.Black.NoTitleBar"). Don't worry about it, ijoomer_theme already have parent="@android:style/Theme.Black.NoTitleBar"; hence, it will be included automatically.

If you have not defined any theme in your application, then simply adding "ijoomer_theme" in manifest.xml will do a trick. Just add the following line in your manifest.xml file under application tag. The resulting Application tag will be as under:

                            
                            
                

STEP 5: Maintaining Resume State

The another thing we would like to do is to make sure when user is running an app and a phone call comes up or user presses "home" button of android and then resumes back to the app, at that time, user can resume from the same state he left. To do so, we will add an attribute in application tag [android:allowTaskReparenting="true"].

STEP 6: Adding iJoomer Activities(Screens) to existing app.

By now, we are done with themes, resources and permissions. The last one is to get our actual screens accessible in the app. To do so, again open iJoomerAdvance's manifest.xml file and copy the codes mentioned between the following comments.

We will need to add up the entry point to the iJoomerAdvance. This is the main activity which gets called before any of the activity of iJoomerAdvance.

                        
                        
            

For eg. If you want to just use iCMS (for Joomla Articles only), then copy the activities tag mentioned between

                        
                        
            

If you want to also have access to JomSocial, you will find code something as under:

                        
                        
            

So, we are now done with the import things and the next step will be making design and branding related alterations in the app.

SHORT TUTORIAL: Changing Theme & Layout

Changing Background Image of the App

Let's begin with altering the background image of the mobile application. This is how it looks in default layout. Our first objective is change the background image of the iJoomer App.

Android SDK

As we need new background, we will copy the new background image and put it under /res/drawable folder. Also, to support all the resolutions, we will put this new png file to drwawable-hdpi, drawable-mdpi and so on.

The background image is set in the style file of the app. So, we will locate the folder /res/values/style.xml file and edit it. In there, we can see background image tag as under:


Now, we will give reference to the background image in this style.xml file as under:


Note:

You don't need to provide .png extenstion here because thats the default extension which Android understand

So, the new background is set, try running the application build and you will see the output as the image below.

Android SDK

Was super easy, isn't it?

Changing Layout of the Screen.

Next, we will be altering the way "Featured Articles" are listed by default in the app. What we want is to have a GridView of these articles instead of the ListView as of now.

This is how it looks as of now.

Android SDK

New Layout File for GridView

As it's a layout related alteration, we will have to edit the layout file of this screen. There are two approaches to this, we can either create our own New layout file OR can edit the current one.

Editing current one is pretty straight forward unless you have shared that layout file with other screen. So, we will take one step further and "Create New" layout file instead of editing the current one.

Locate folder /res/layout/ and in there, create a new layout file. We will name it "icms_my_featured_articles.xml". (Notice icms as prefix, this will make sure you don't get lost in the layout files and locate things you need at first instance).

We will copy the content of the previous layout file which was "/res/layout/icms_article.xml" to the newly created layout file and then start playing around with the same.

The content of the copied file will look as under:


    
    

Notice the tag "ListView ", we will alter it to GridView and then make some additional style related alterations. Resultant layout will be as under:


    
    
    
    


Linking Layout with Activity

Now, the new layout is ready but there is still some job to be done. We need to assign this layout to Screen/Activity. To do so, we will need to give reference of this layout in Activity. So, we will open the Class file named "IcmsFeaturedArticlesActivity.java" located under "src/com/ijoomer/components/icms".

First of all, we will set our new layout in this class file. Locate the "setLayoutId" function and should look something like under:

@Override
	public int setLayoutId() {
		return R.layout.icms_article;
	}

Instead of icms_article, we need to give reference of icms_my_featured_articles (we already created icms_my_featured_articles.xml layout file). So, the resultant code will be as under.

@Override
	public int setLayoutId() {
		return R.layout.icms_my_featured_articles;
	}

Renaming and Assigning Layout to Object

So, the initial layout is set to new one, but still, we need to create a GridView object instead of ListView object. So, edit the variable as under:

private ListView listArticle;

To

private GridView gridArticle; 

Now, we will assign the view/layout to this object. To do so, we will locate function initComponents function and assign this variable there.

listArticle = (ListView) findViewById(R.id.icmsListArticle); 

To

gridArticle = (GridView) findViewById(R.id.icmsGridArticle);

Adjusting item Layout for GridView

By now, our structure of layout is ready, but we still need to design what will come inside each of those boxes and how it will be displayed. To do so, we will open icms_featured_article_listitem.xml and copy the content of the same. Then create a new layout which will be for gridView. We will name this new layout file as icms_featured_article_griditem.xml.

Once you copy the content, the icms_featured_article_griditem.xml file will look something as under:



    
        
        
        
    

We will further edit this layout to make sure image is shown plus some intro text is shown. So, the final altered layout will be as under:


    
        
        
    

You can notice the android:id="@+id/icmsTxtTitle". This is the variable which will contain the title of the article and likewise other data are defined in layout. To find the list of all the variables returned for each activity, you can check the reference guide which has a list of all the activities and the object data available to the same from the server returned value.

Making Adapter Related Settings

The next step is to prepare data for adapter so that it can be assigned correctly. We will locate the function preparelist and then alter layout assigned to the new one. The change will be as under:

item.setItemLayout(R.layout.icms_featured_article_listitem);

To

item.setItemLayout(R.layout.icms_featured_article_griditem);

Now, the last step is to alter the adapter which assigns the data returned from the server to the layout file which we created newly. The original function looks as under:

public SmartListAdapterWithHolder getListAdapter(ArrayList< SmartListItem > listData) {

		SmartListAdapterWithHolder adapterWithHolder = new SmartListAdapterWithHolder(this, R.layout.icms_featured_article_listitem, listData, new ItemView() {

			@Override
			public View setItemView(int position, View v, SmartListItem item, ViewHolder holder) {

				holder.icmsTxtTitle = (IjoomerTextView) v.findViewById(R.id.icmsTxtTitle);
				holder.icmsTxtIntro = (IjoomerTextView) v.findViewById(R.id.icmsTxtIntro);
				holder.icmsImageThumb = (ImageView) v.findViewById(R.id.icmsImageThumb);
				// holder.icmsImageThumb.setVisibility(View.GONE);

				@SuppressWarnings("unchecked")
				final HashMap< String, String > value = (HashMap< String, String >) item.getValues().get(0);
				holder.icmsImageThumb.setVisibility(View.VISIBLE);
				androidAQuery.id(holder.icmsImageThumb).image(value.get(IMAGE), true, true, getDeviceWidth(), R.drawable.icms_article_default);
				holder.icmsTxtIntro.setText(Html.fromHtml(value.get(INTROTEXT)).toString().trim());
				holder.icmsTxtTitle.setText(value.get(TITLE).trim());
				return v;
			}

			@Override
			public View setItemView(int position, View v, SmartListItem item) {
				return null;
			}
		});
		return adapterWithHolder;
	}

Now, we will change the name of the layout defined and the data which are assigned. In our previous view, we were showing "intro text" of featured article, now, we are just showing image and title and need to remove "intro text". The resultant adapter function will be as under:

public SmartListAdapterWithHolder getListAdapter(ArrayList < SmartListItem > listData) {

		SmartListAdapterWithHolder adapterWithHolder = new SmartListAdapterWithHolder(this, R.layout.icms_featured_article_griditem, listData, new ItemView() {

			@Override
			public View setItemView(int position, View v, SmartListItem item, ViewHolder holder) {

				holder.icmsTxtTitle = (IjoomerTextView) v.findViewById(R.id.icmsTxtTitle);
				//holder.icmsTxtIntro = (IjoomerTextView) v.findViewById(R.id.icmsTxtIntro); We just commented this as we no longer want to display intro text.
				holder.icmsImageThumb = (ImageView) v.findViewById(R.id.icmsImageThumb);
				
				@SuppressWarnings("unchecked")
				final HashMap< String, String > value = (HashMap< String, String >) item.getValues().get(0);
				holder.icmsImageThumb.setVisibility(View.VISIBLE);
				androidAQuery.id(holder.icmsImageThumb).image(value.get(IMAGE), true, true, getDeviceWidth(), R.drawable.icms_article_default);
				//holder.icmsTxtIntro.setText(Html.fromHtml(value.get(INTROTEXT)).toString().trim()); Comment the assignment of intro text as we no longer require this.
				holder.icmsTxtTitle.setText(value.get(TITLE).trim());
				return v;
			}

			@Override
			public View setItemView(int position, View v, SmartListItem item) {
				return null;
			}
		});
		return adapterWithHolder;
         }

After making these simple alterations, it's time to check result. Run the build and check, the resultant screen will be like under:

Android SDK
Cron Job Starts