SeshIn: Documentation By Christopher Castillo, Sherief Shahin, Steven Wright, and Farhan Zaki Requirements Statement This mobile app will show locally posted social events on a map within a certain radius of the user’s location. The user base will mainly be college students, but can be used by anyone. The user can check into events, host their own events, and post comments and pictures on the event pages. The app will notify the user when an event they are going to is starting or has other updates. The user can subscribe to certain user accounts, such as campus organizations and individuals, and be notified when that account posts an event. The events will show the number of people marked as going/not going/can’t go and will show the number of people currently at the event when it is happening. Timeline and Milestones ● Timeline: o Sept 11-22: learn Xamarin, completely sketch out what the whole app will look like o Sept 23 – 30: implement event list screen UI and deploy onto devices for testing. Then work out C# internals. This will be the first actual deliverable of our project o Oct 1 – 14: Have most of the main features implemented. Test as we go o Oct 15 – 31: Have all main features implemented, begin usage testing o Nov 1 – 11: Refine UI, fix bugs discovered from usage testing o Nov 12 – End of semester: revise and improve app through testing and feedback ● Milestones: o come up with name for app o finish design + sketching o create first prototype with main features and maybe map at least o revise prototype to be operational (have main features) o improve UI o revise until done Cost Estimate Approximately the next four months of time and effort. Probably an average of 8-10 hours a week over the next 12 weeks. Also $200 for developer fees. $100 for Apple Appstore, $25 for Google Play Store, $45 for Windows. Also $25 for a domain name for marketing. Hardware, software, etc. and Who Will Supply Them o Hardware : Windows and Mac computers. A Mac computer is required to compile and build iOS apps. Also iPhones and Android phones to actually deploy and test the app o Software : Visual Studio 2017 and Xamarin, Google Maps API Non-Functional Requirements Our two biggest non-functional requirements are security and user feedback. Credential security is important for many obvious reasons, as the app will have a login that will need to be protected. There will be no transactions of any kind in this app, so there is no financial security needed. User feedback (collected through the surveys and whatnot detailed in the next section) is critical because we need to know what users find good and bad about the app in order to improve it and resolve any issues it has. We will also be using GitHub for version control and that way our code will be safely backed up and can be distributed to all of our computers. Plan for Communication Our project does not necessarily have a “client”, in that there is no customer that is expecting specific features. We will design this app with the students of Denison in mind as our customer. To communicate with them we will ask around Denison what features they would like in this kind of app through surveys, Facebook, email and word of mouth. We can also ask campus event planning organizations like CLIC how they might use the app and what features they would like to see. Plan for Assessment We will deploy the app to select groups of beta testers who will explore the app and tell us about their experience. This way we can work out as many issues as possible before subjecting the app to a large scale audience. This will ensure that our app will be as functional as possible when it is assessed at the end of the semester and should have no issues. Our criteria for a “good app” are smooth and painless user experience, ease of use, and functionality Plan for Training Users We plan to design some instructional screens upon opening the app for the first time, with nice graphics showing the users where everything is. The app should be intuitive enough that the user won’t need much training or guidance. Test Plan We will use the last month of the semester to go through the app and make it as bug-free as possible. There will be a “report bug” feature so users can notify us via email of problems that arise while using the app. We can fix the problems, update the app and push the update through the app stores that the user downloaded the app from. Each update would have proper documentation of what was done. Design Overview We seek to create this app specifically for Denison University’s student body due to a problem we see with the way campus events are being advertised. Everyone on campus uses their phones to keep up with their social lives, and campus events are apart of that. Posters around campus aren’t cutting it, because we are seeing events where not enough people are showing up. We are designing an app with a very easy to follow list view and map view. Posting events on the app should be easy and familiar (like posting a tweet, or status update on Facebook). The goal of this app is to provide Denison students information about campus events through a simple and fun interface. It will increase awareness of events around campus and allow the student body to become more aware of what is going on around them. We want the app to be easy to use, so there will be a tutorial at the very beginning of the app’s opening. Advanced functionality will include Apple’s Force Touch and iMessage features, and Android Widget features. In terms of personalization, we will have a simple account that allows users to customize their profile picture, bio, and general profile. This is a cross-platform app that will be developed using Xamarin for Visual Studio 2017. This allows the app to run on both Android and iOS while using the same codebase. The programming language is C# for the application layer and XAML for the user interface. Our mobile application is designed to run on all types of mobile devices. By leveraging Xamarin’s screen adaptability features, our app will be compatible with all screen sizes (including tablets) and with both the portrait and landscape Implementation Each screen of the app has two main code files that define the implementation. The user interface is in the XAML file, which is similar to HTML and XML. This is where we develop the buttons, text, layout, etc. for each each screen. The other main file is a C# file with a .xaml.cs extension. This is what gives the UI (defined in the .xaml file) its functionality. Each possible screen action is implemented in that screen’s xaml.cs file. The majority of actual programming is in the C#, as that is the functional, logical layer of the application. The xaml just dictates how the app will look, whereas the C# actually makes the app do what it is supposed to do. The entire app uses this property to keep the UI, Business, and Data layers separate. This makes the code very portable and easy to deploy on both major mobile OSes. By keeping these layers separate, user interface can be developed in parallel with functionality (business layer), as opposed to both of them being hard-coded into each other and being developed in succession. The diagram above illustrates this. This is how every page of our app will be designed. We can make the UI first, and then implement the features under it. There are many other aspects that support and play into these two main files. For each C# file, there are many libraries and resources that we can use to aid our development. Xamarin itself is a massive library that has many functions that facilitate interaction between Android and iOS. There are also APIs which tie into our C# code. These allow us to use already made products, like Google Maps, in our code. APIs act like libraries that have much higher functionality and are external to the development environment. Developmental Goals There are three major milestones to the completion of this app. Upon first creating a basic shell of an app that has multiple screens and can be deployed to a device, a database must be set up. Next, interaction between the app and the database must be achieved. This entails the user inputting information, it being sent to the database, then be able to be recalled and manipulated later. This is the foundation of all the app’s functionality, as all the events’ information will be stored in the database and displayed to all users. The database will also contain all the user profiles, past events, comments, and pictures. As these are all core features, completion of this step is major progress and a solid foundation towards a working product. The second major goal is to secure a Google Maps API key and implement a Google Maps screen. This entails essentially recreating the main screen of the Google Maps app. Having a fully functional and interactive map that the user can pan and zoom with intuitive controls will be the center of the app. This is where all the events will appear. This will be the main screen of the app where the user will spend the most time, so it needs to be functional and free of errors. This is the most important screen of the app, but it can’t actually do anything without the database to store the things displayed on it. This is why the database must be setup as soon as possible. The third goal is to combine the previous two goals. Once the map screen has been fully implemented and the database is operational, the main features of the app can be implemented. This will involve interacting with the map to create an event whose information (location, time, description, etc.) will be stored and recalled in the database. The event will then be displayed on the map as a pin or some other marker to indicate its existence. This is how other users will be able to see and interact with events. At this stage, the major features of the app are implemented, and all the details must be added, as well as the UI refined. This is the basic architecture of the development process for this project. Initial Structural Overview Mockup (Architecture/Navigation/Graphic Design) Final Design Images Test Plan: Compatibility Team Contact: Christopher Castillo Team Tester: Christopher Castillo Type of test (white box or black box,? unit, integration, validation, or system?): Black box testing and system testing. Purpose of test: The purpose of testing compatibility is, first, to check whether the software works with certain operating system versions, old or new. Our priority is to check if the application works with the current operating systems that Apple and Android have released (iOS11 and Oreo). From there, we’d like to test for backwards compatibility. We understand that not everyone updates their phones to the latest operating system, so we’d like to have the application available for previous versions of the Apple and Android operating systems (at backwards compatibility to three previous versions). Lastly, testing compatibility allows us to check whether the code we’ve written translates well to both Apple and Android operating systems. The biggest concern we have is with the formatting of certain UI elements, since Apple and Android have different formatting constraints. If black box, what specifications are being used? We will use simulators and our own personal devices to test compatibility. Test inputs: We will use the various operating system simulators given to us in the Xamarin framework to test our software. Expected outcomes from each input: We expect our software to work on each version of the operating system with no formatting issues. Results from each input: Test Input: Expected Outcome: Outcome: Android 5.0 Everything runs smoothly Android 6.0 Everything runs smoothly Android 7.0 Everything runs smoothly Location bar doesn’t come up, which does not allow the user to post a new event. Android 8.0 Everything runs smoothly iOS 9 Everything runs smoothly iOS 10 Everything runs smoothly iOS 11 Everything runs smoothly Proposed changes: The Google Maps API key for the location bar needs to be updated. Push a software update to the Google Play Store. Retest plan for this item and for affected items: Test Input: Expected Outcome: Outcome: Android 7.0 Everything runs smoothly Test Plan: Database Team Contact: Chris Castillo Team Tester: Steven Type of test (white box or black box,? unit, integration, validation, or system?): Stress testing and white box testing Purpose of test: The purpose of testing the database is to check whether or not the correct information is being stored, and if it being stored in the correct location. We want to ensure that the correct information is being stored because we would be dealing with user information such as usernames and passwords that would need to be accessed every time the user wants to log in. We want to ensure that the information is being stored in the correct location to allow the system to easily access the information it needs for the user. Lastly, we want to test the database in order to see how much traffic it can take at a time. This is especially important when posting events, since we want to make sure the database isn’t overloaded. If white box, what paths are being covered? Login information in to the database, event information in to the database, presenting the user’s previous events by retrieving that information from the database. Test inputs: Usernames, events, event information. Expected outcomes from each input: We expect the information to be stored in the correct locations. We expect the database to withhold a good amount of information before it crashes. Results from each input: Test Input: Expected Outcome: Outcome: Date Goes to appropriate part of the of the data base Description Goes to appropriate part of the of the data base End Timestamp Goes to appropriate part of the of the data base Going Goes to appropriate part of the of the data base Host Name Goes to appropriate part of the of the data base Interested Goes to appropriate part of the of the data base Latitude Goes to appropriate part of the of the data base Longitude Goes to appropriate part of the of the data base Start Time Goes to appropriate part of the of the data base Stop Time Goes to appropriate part of the of the data base Title Goes to appropriate part of the of the data base Test Plan: Interface Team Contact: Chris Castillo Team Tester: Sherief Type of test (white box or black box,? unit, integration, validation, or system?): White box testing and system testing. Purpose of test: The purpose of testing the interface is mainly to check if all the UIelements (buttons, text fields, toggles, etc.) work. We’d also like to check that all of our screens transition correctly. Lastly, we want to ensure that there aren’t any formatting bugs or glitches that might impede on ease of use for an individual. If white box, what paths are being covered? We want to make sure that each page is correctly linked between one another. Test inputs: Various clicks and keystrokes that manipulate UI elements. Expected outcomes from each input: Our expected outcome for each input is that the UI element produces the correct output. For example, when clicking on the map/list toggle button, we’d expect the app to make the transition from the map view to the list view or vice versa. Additionally, if we press the settings button it should go to the settings page and not the past events page. Results from each input: Test Input: Expected Outcome: Outcome: Master Detail View Button Pulls out the master detail view New Button Pulls up the “new event” form Event Pinpoint Pulls up the event details page Map View Button Pulls up the map view List View Button Pulls up the event list view Help Button Pulls up the help page Contact Button Pulls up the contact page L0cation Button Pulls up matching locations as you type, and disappears once selected. Pulls up matching locations as you type, but doesn’t disappear once selected Proposed changes: The Google Maps API key for the location bar needs to be updated. Push a software update to the Google Play Store. Retest plan for this item and for affected items: L0cation Button Pulls up matching locations as you type, and disappears once selected. Pulls up matching locations as you type, and disappears once selected. Code Structure Every screen you see in the app has two files that control it. A .xaml file that controls the UI, and .cs file that defines the functionality behind the UI. All the pages are managed by the Master Detail pages. MasterDetailPage1 is the page that coordinates the slideout menu (three lines button on top left). MasterDetailPage1Master is the slideout menu itself, which contains the names of the menu items that will then open the map, list, about, and help pages. The file App.xaml.cs is where the default first page is defined. This must be set to MasterDetailPage1, or the slideout menu will not happen. The MasterDetail page will open the map page by default. This is defined in MasterDetailPage1.xaml and MasterDetailPage1MenuItem.cs. The rest of the pages are independent things, they just get called by the Master Detail page. See the file structure to the left. There are three projects in the solution. App1 (Portable) is where almost all the work is done. This is where all of the files described in this document are kept, and they are cross-platform, meaning everything defined here creates both the Android and iOS versions of the app. Only a few specific things are done within the platform specific projects. The Pages folder is where all the app screens that you see are kept. The .xaml files are the ones visible in the picture to the left, and their corresponding .cs files are children of them in the directory structure. Outside of the Pages folder are the helper classes DynamoService.cs and EventsTable.cs, as well as the Master Detail files as described above. App.xaml is the first file that is run when the app is deployed, which is why it defines the what the first page should be. Implementation Main Functionality Files: 1. EventsTable.cs – class that defines Event objects to be stored and retrieved from database 2. DynamoService.cs – defines functions to communicate with database 3. MapPage.xaml.cs – gets all Events from DB, populates map with pins for all the events 4. NewEvent.xaml.cs – creates and saves new events to database 5. EventInfo.xaml.cs – gets and displays event info from database when event is tapped 6. EventsList.xaml.cs – populates a list view with event info EventsTable.cs This is a simple C# class that defines what an Event object is for the entire app, and mainly for the DyanmoDB table to recognize what objects are being stored. Each attribute of this class is defined as a specific property of the DynamoDB table it corresponds to. This table is specified in the line above the constructor. Lines 6 and 7 are [DynamoDBTable("Events")] and public class Event, which are telling the database to put objects of Event type into the table named “Events”. The fields of the Events class are all either DynamoDBHashKey, DynamoDBRangeKey, or DynamoDBProperty values. In the Events table, the name of the host is the hash key, and the title of the event is the range key, thereby uniquely defining each event by its host and title. The only restriction to this is that the same host cannot have more than one of the same event titled the same thing at the same time, as that would case a duplicate key combination. The rest of the fields in this class are just other Event attributes, like date, description, etc. These Event objects are the type that all the templated DynamoService operations wil be operating on. DynamoService.cs ● public DynamoService() – constructor. First creates a AmazonDynamoDBClient object using your AWS credentials, then creates a DynamoDBContext object using the Client object. All the following functions in this class are essentially wrapper functions for existing functions of the DynamoDBContext class, which are part of the AWS SDK NuGet package. These operations are what actually interact with the database. ● public async Task Store<T>(T item) - Initiates the SaveAsync<T> method of the DynamoDBContext class. Returns a Task<T> because it is an async method, meaning execution will continue while this operation completes. It takes an object of whatever type is being stored. In our case, it is an Event object. ● public List<Document> GetAll<T>() - Gets the entire table of the specified type, and returns a List of Documents, which contain all the information for each type object they represent. This is used in the Map and List pages code to populate the screen with all the events. ● public Task<T> GetItem<T>(object hashkey, object rangekey) – Returns a Task of the specified type whose result is the requested object, specified by the hashKey and rangeKey parameters. These correspond to the primary (hash) and secondary (range) keys of the object being search for. The returned Task can be used to get the value of the requested object, in order to access its information. ● public void UpdateItem<T>(T item) - Loads the T object, item, in the same way as GetItem<T>. A change can then be made to the retrieved object, and then it is stored again in the same way as Store<T>(T item). ● public void DeleteItem<T>(T item)- Loads the T object, item, instead of changing it and re-saving it, it just deletes it using the DynamoDBContext operation DeleteAsync. MapPage.xaml.cs ● public MapPage() – constructor for the MapPage. 90% of the creation of the map page happens within the contructor. Very first, it checks for internet connection. If there is none, it will not do anything but tell you that you don’t have intenet. Without this check, it would try and access the database even if there is no internet connection and fail, crashing the app. Upon passing the connection check, it will then create a Map object, which is defined by the Xamarin.Forms.Maps plugin. A Google Maps API key is required for this to work on Android. It must be stored in AndroidManifest.xml, within the Android project. It is currently set to initialize the map to open at Denison, but future versions will make it open wherever the user is. Next, an instance of the DynamoService class is initialized, which is the used to get all the Events from the database. The GetAll<Event> method is used to get the entire Events table. The list of Event Documents returned is then iterated over and all the necessary information to create map pins for the events is collected. At every iteration of this loop, the current timestamp is taken in Unix epoch form (number of seconds since Janauary 1, 1970). This is compared to the end timestamp that is saved within each event in the same format. If more than two hours have passed between the end of that event and the execution of this code, the event is deleted and it is not added to the lists that are used to populated the map with pins. Once all these events have been checked for expiration and accumulated into lists, a for loop creates and places a pin for each event. The title, host, latitude, and longitude are stored in the pin. The default Xamarin map pin objects are very limited. The only information they can store are Label, Address, and latitude & longitude. Label is the bolded text that displays the name of the event, and address is the line below it. Throughout the project, we use the Address field to hold the host name and the Label field to hold the event name. These fields are named by Xamarin not us, which is why they are confusing. Using the pins this way was necessary because it was the only way we could populate the map with indicators that contained all the information necessary to look up that specific event in the database when it is clicked. ● private bool CheckConnectivity() – checks internet connection using the Connectivity plugin. Simply returns a boolean indicating whether or not the device has an internet connection when the function is called. ● async void NewEvent(object sender, EventArgs e) – handles new event button pressed. This function is automatically called whenever the NEW button at the top right of the map is clicked. Every function whose parameters are object sender and EventArgs e in this project are event handlers. They execute whenever specific actions happened. The sender parameter is the object that was tapped or interacted with and the e parameter is the object that contains the data for the systyem events that occurred when that item was tapped. These roles apply to all similar functions in this project. Event handlers never return anything because they simply make other things happen when triggered. They are not to be called to create or return any values, they only trigger new processes to happen as a result of their corresponding item being interacted with. The object they correspond to is defined in the xaml. NewEvent.xaml.cs ● public NewEvent() – constructor, first checks for internet connection with CheckConnectivity() in the same way as the MapPage. It then sets the necessary arguments for the search bar, which is defined using the DurianCode.PlacesSearchBar NuGet package to automatically query the Google Places API for results for the input from the user. It is the same thing as using the search bar in the Google Maps app. The Google Places API key is defined at the beginning of the file. The Type for the search bar is set to All, which will suggest cities, areas, establishments, and addresses. This can be changed to be more restrictive if desired. Search_Bar_PlacesRetrieved is an event handler for when the search bar retrieves results for the entered text. TextChanged is the same thing but for the text changing instead. MinimumSearchText is the minimum number of characters to be entered until the results list appears. Results_List_ItemSelected is the event handler for when an item is selected from the results list. ● private bool CheckConnectivity() – same function as MapPage.CheckConnectivity() ● async void Results_List_ItemSelected(object sender, SelectedItemChangedEventArgs e) – This function is called when an item in the results list is tapped. First, the itemTapped boolean is set to true. This is used to hide the results list after the item is selected. It then gets the place information from