You are here

How to use the Favorites API

This tutorial describes how to use the methods that were added in SDK 1.2 for working with favorite nodes, documents and folders.

This tutorial assumes you are familiar with the content of previous tutorials. It is also assumed that you are using Eclipse.

In version 1.2 of the SDK, methods were added for dealing with favorite nodes, documents and folders. These methods allow you to determine whether a node is a favorite or not, add a favorite, remove a favorites and also retrieve lists of favorite nodes, documents and folders. In this tutorial you create and run some code to test these new APIs.
  1. In Share navigate to the Repository and upload a selection of sample documents. Add two documents as favorites.
  2. In Share create a public site to work with called Harry's Site (harrys-site).
  3. Upload some files into Harry's Site (about 15 files should be more than enough)
  4. In Share, add any six files to favorites.
  5. Create three sub-folders in Harry's site.
  6. Moves a few files, including some favorited files into each of the folders created in Harry's Site.
  7. In Share, select two of the folders in Harry's Site and add them as favorites.

    At this point you should have a test site to work with, and a selection of favorited files and folders.

  8. In Eclipse create a new Android SDK project called FavoritesTest. It should be in the package com.alfresco.tutorials.favoritestest. You should use a minimum API level of 14. If you are not sure how to do this see the tutorial How to create an SDK application. Don't forget to update connection details as required and add the correct permissions to the Android Manifest.
  9. Now in the Eclipse Package Explorer, locate the FavoritesTest project and expand it to locate MainActivity.java.
  10. Replace the code with the following:

    						
    package com.alfresco.tutorials.favoritestest;
    
    import org.alfresco.mobile.android.api.exceptions.AlfrescoSessionException;
    import org.alfresco.mobile.android.api.model.Document;
    import org.alfresco.mobile.android.api.model.Folder;
    import org.alfresco.mobile.android.api.model.Node;
    import org.alfresco.mobile.android.api.model.RepositoryInfo;
    import org.alfresco.mobile.android.api.model.Site;
    import org.alfresco.mobile.android.api.services.DocumentFolderService;
    import org.alfresco.mobile.android.api.services.SiteService;
    import org.alfresco.mobile.android.api.session.RepositorySession;
    
    import android.app.Activity;
    import android.os.AsyncTask;
    import android.os.Bundle;
    import android.util.Log;
    import android.widget.Toast;
    
    public class MainActivity extends Activity {
    
    	@Override
    	public void onCreate(Bundle savedInstanceState) {
    		super.onCreate(savedInstanceState);
    		setContentView(R.layout.activity_main);
    
    		// Modify to suit your Alfresco server installation
    		String url = "http://10.0.2.2:8080/alfresco";
    		String username = "admin";
    		String password = "admin";
    
    		new ConnectToRepo().execute(url, username, password);
    
    	}
    
    	class ConnectToRepo extends AsyncTask<String, Integer, String> {
    
    		private static final String TAG = "ConnectToRepo";
    
    		@Override
    		protected String doInBackground(String... params) {
    
    			Log.d(TAG, "doInBackground");
    			Log.d(TAG, params[0] + ":" + params[1] + ":" + params[2]);
    
    			String url = params[0];
    			String username = params[1];
    			String password = params[2];
    
    			// HelloRepo
    			try {
    				// connect to on-premise repo
    				RepositorySession session = RepositorySession.connect(url,
    						username, password);
    
    				if (session != null) {
    
    					// Get some repository information
    					Log.d(TAG, "baseUrl: " + session.getBaseUrl());
    					Log.d(TAG, "rootFolder: "
    							+ session.getRootFolder().getName());
    
    					// Obtain a repository information object
    					RepositoryInfo repoInfo = session.getRepositoryInfo();
    
    					Log.d(TAG, "repoId: " + repoInfo.getIdentifier());
    					Log.d(TAG, "repoName: " + repoInfo.getName());
    					Log.d(TAG, "repoDescription: " + repoInfo.getDescription());
    					Log.d(TAG, "repoVersion: " + repoInfo.getVersion());
    					Log.d(TAG, "repoEdition: " + repoInfo.getEdition());
    
    					// Get document folder service
    					DocumentFolderService documentFolderService = session
    							.getServiceRegistry().getDocumentFolderService();
    
    					// Get test site
    					final String siteShortName = "harrys-site";
    					SiteService siteService = session.getServiceRegistry().getSiteService();
    					Site testSite = siteService.getSite(siteShortName);
    					Folder documentLibrary = siteService.getDocumentLibrary(testSite);
    
    					// CODE TO BE ADDED BELOW HERE
    					
    					
    					
    				} else {
    
    					Log.d(TAG, "No Session available!");
    
    				}
    
    			} catch (AlfrescoSessionException e) {
    				Log.e(TAG, "Failed to connect: " + e.toString());
    			}
    
    			Log.d(TAG, "doInBackground Complete");
    			return "doInBackground Complete";
    		}
    
    		@Override
    		protected void onPostExecute(String result) {
    			super.onPostExecute(result);
    			Log.d(TAG, "onPostExecute");
    			Toast.makeText(MainActivity.this, result, Toast.LENGTH_LONG).show();
    		}
    
    		@Override
    		protected void onProgressUpdate(Integer... values) {
    			super.onProgressUpdate(values);
    			Log.d(TAG, "onProgressUpdate");
    
    		}
    
    	}
    
    }
    						
    						
    					
    Attention: You may get some compile warnings at this point as you are not using all variables. These can be ignored for now.

    This provides a skeleton program to which you will add code in the following parts of this tutorial.

  11. Rebuild and run your project to test everything is in order.
  12. Now, just below the comment that says CODE TO BE ADDED BELOW HERE, in MainActivity.java add the following code:

    						
    	// get All folders and find if any are favorites
    	for (Folder folder : documentFolderService.getFolders(documentLibrary)){
    		
    		if (documentFolderService.isFavorite(folder)){
    			
    			Log.d(TAG, "Found favorite folder: "+folder.getName());
    		}
    	}						
    						
    					

    This code fetches all folders in the test site's document library. Each folder returned is checked to see if it is a favorite using the new isFavorite() method.

  13. Build and run the project.
  14. Check the LogCat output is as expected. You should see the repository information, and then a list of found favorites.
  15. Now replace the previously added code with the following:

    						
    	// get All documents and find if any are favorites
    	for (Document document : documentFolderService.getDocuments(documentLibrary)){
    		
    		if (documentFolderService.isFavorite(document)){
    			
    			Log.d(TAG, "Found favorite document: "+document.getName());
    		}	
    	}
    						
    						
    					

    This code performs a similar operation to the previous step, however, this code returns all documents in the site's document library. It then uses isFavorite() to check if each document is a favorite and then print out details accordingly.

  16. Build and run your program and check the LogCat output is as expected. You should see a list of several favorite documents.
  17. Now replace the previously added code with the following:

    						
    	// Toggle favorite on sample folder
    	final String testFolderName = "Sample Folder";
    	Folder testFolder = (Folder) documentFolderService.getChildByPath(documentLibrary, testFolderName);
    	Log.d(TAG, "1. Test folder is favorite: "+documentFolderService.isFavorite(testFolder));
    	if (documentFolderService.isFavorite(testFolder)){
    		documentFolderService.removeFavorite(testFolder);
    	}
    	else {
    		documentFolderService.addFavorite(testFolder);
    	}
    	Log.d(TAG, "2. Test folder is favorite: "+documentFolderService.isFavorite(testFolder));						
    						
    					

    If necessary change the value of testFolderName to that of a suitable folder in your test site. Or simply create the Sample Folder in your site's (harrys-site) document library.

    This code toggles the favorite status of the specified folder. It demonstrates the use of the isFavorite(), addFavorite(), and removeFavorite() methods.

  18. Build and run your code and check the LogCat output is as expected. You should see the favorite status of the target folder switch to the opposite state.
  19. Now replace the previously added code with the following:

    						
    	// get favorite documents
    	for (Document document : documentFolderService
    			.getFavoriteDocuments()) {
    		if (!document.hasAllProperties()) {
    			// if hasAllProperties() returns false then refresh
    			// Node
    			document = (Document) documentFolderService.refreshNode(document);
    		}
    		Log.d(TAG, "title: " + document.getTitle());
    		Log.d(TAG, "description: " + document.getDescription());
    		Log.d(TAG, "name: " + document.getName());
    		Log.d(TAG, "isDocument: " + document.isDocument());
    	}						
    		
    					

    This shows a convenient way to retrieve all favorite documents for the current user, using the getFavoriteDocuments() method. This retrieves all favorite documents for the current user, regardless of where the documents are located within the repository.

    Attention: You will notice the use of two very important methods: hasAllProperties() and refreshNode(). It is necessary to check if the node has its properties populated before trying to work with those properties. If the properties of a node are not populated the values will be null. To ensure that the node's properties are populated use the hasAllProperties() method as shown. If the properties are not populated, you can use the refreshNode() method to populate the node's properties.
  20. Run the project and check the LogCat output is as expected. You should see all documents that you added as a favorite, no matter where they are located in the repository.
  21. Now replace the previously added code with the following:

    	
    	// get Favorite folders
    	for (Folder folder : documentFolderService.getFavoriteFolders()) {
    		if (!folder.hasAllProperties()) {
    			// if hasAllProperties() returns false then refresh
    			// Node
    			folder = (Folder) documentFolderService.refreshNode(folder);
    		}
    		Log.d(TAG, "title: " + folder.getTitle());
    		Log.d(TAG, "description: " + folder.getDescription());
    		Log.d(TAG, "name: " + folder.getName());
    		Log.d(TAG, "isFolder: " + folder.isFolder());						
    	}						
    	
    					

    This code is similar to the code added in the previous step, however this code retrieves a list of favorite folders for the current user, using the getFavoriteFolders() method, no matter where they are located in the repository.

  22. Run the project and check the LogCat output is as expected. You should see a list of all folders that have been added as favorites by the current user, regardless of where they are located within the repository.
  23. Now replace the previously added code with the following:

    
    	// get Favorite Nodes
    	for (Node node : documentFolderService.getFavoriteNodes()) {
    		if (!node.hasAllProperties()) {
    			// if hasAllProperties() returns false then refresh
    			// Node
    			node = (Node) documentFolderService.refreshNode(node);
    		}
    		Log.d(TAG, "title: " + node.getTitle());
    		Log.d(TAG, "description: " + node.getDescription());
    		Log.d(TAG, "name: " + node.getName());
    		Log.d(TAG, "isFolder: " + node.isFolder());						
    		Log.d(TAG, "isDocument: " + node.isDocument());						
    	}
    
    					

    This code obtains a list of all nodes (documents and folders) that have been added as favorite by the current user, using the getFavoriteNodes() method.

  24. Run your code and check the LogCat output is as expected. You should see a list of all documents and folders that you have added to your list of favorites.
In this tutorial you have see how to use the new Favorite API introduced in version 1.2 of the SDK.

Sending feedback to the Alfresco documentation team

You don't appear to have JavaScript enabled in your browser. With JavaScript enabled, you can provide feedback to us using our simple form. Here are some instructions on how to enable JavaScript in your web browser.