

buzztouch v1.5 for iOS - Early Release

This document is intended to help anyone interested in exploring buzztouch v1.5 understand how
it's put togther, how it works, how it can be configured in hundreds of different ways
to create lots and lots of different types of apps. Review this document while you 
explore the Xcode project. 

PLEASE VISIT THE FORUM at buzztouch.com to add comments, questions, or feedback about this
early release. Your help is greatly appreciated. Technical feedback is good, promotional
plugs are better! Tweeting, Blogging, or linking to us from your website is the single
biggest way you can help. We consider each and every one of our supporters to be our 
biggest asset and as such, depend on their helping us improve, promote, and publicize
our exciting project. Thank you in advance for this. 

Before you get started, ensure you have the latest release of the iOS SDK installed on your
computer. The latest release as of this writing is iOS 4.2

Getting Started:

1) 	Review the Directory Structure

	Open the Xcode project and expand the Groups and Files section to expose the directory
	structure of the project. The directory structure is as follows:
		
		buzzTouch (top-level project name)
			/BT_config
			/BT_Screens
			/BT_Html
			/BT_Docs
			/BT_Sound
			/BT_Plugins
			/BT_Images
				/Backgrounds
				/Icons
				/Gui
				/QuizImages
			/BT_Layout
			/BT_Objects
			/Framworks
			/Products
			
2) 	Setting the Base SDK in the Project Properties Window
	
	Select the buzzTouch project in the Groups and Files pane. After selecting it, click
	the blue Info button in the toolbar. This will open the Project Properties window. Scroll
	down and set the Base SDK to the latest iOS SDK release you have installed - it should 
	be iOS 4.2. If you do not have iOS 4.2 installed, it should work with older SDK's 
	going back to iPhone 3.1, select the newest one you have. Also, be sure you are 
	setting the Base SDK for the Debug and Release configurations. Change the 
	configuration you are working with in the top-left corner of the Properties Window. 
	
3)	Setting the Code Signing Identity

	Still in the project Property Settings, scroll down to the Code Signing Identity section. 
	Set it "Do Not Code Sign" while working in the Simulator. Set this for Debug and Release
	configurations (top left dropdown). If you are running the software on an actual device, 
	you'll need to select a Provisioning Profile you downloaded from the Apple Developer Portal. 
	This document assumes you are working with the Simulator.
	
4)	Build and Run on Simulator (choose iPhone, not iPad while you work with this document)

	Select Debug > Simulator from the top left drop down list in Xcode (you already closed the
	Project Properties window). Next, click Build and Run from the toolbar. The simulator should
	launch and the included sample application will display. Explore the sample application as
	you continue to review this document. Also, be sure to open the "Debug Console" while you run
	the app in the Simuator. The console will output all kinds of useful information. We spent
	countless hours adding this run-time information in an effort to make the software easier
	to understand. 
	
5) 	Launch Icons / Artwork: Expand the BT_Images folder and preview the images in the /root of
	this directory. Default.png, Default-Landscape.png, Icon_57.png, etc. These are the images
	the Simulator, iPhone or iPad uses on the springboard - before you release your application you
	will need to update them. When updating them, do not change the file names. Create new 
	images and over-write these images. You do not need to do this while exploring but you will 
	need to do this before distributing your application.
	
6) 	Application CFBundleName, CFBundleIdentifier

	Open the BT_info.plist file inside the BT_Config folder. This file is used so Xcode can
	identify your application uniquely from all others. Set the CFBundleName to whatever
	you want. The value you enter for the CFBundleName will display under the icon on the 
	iPhone or iPod or iPad's home screen (springboard). Change the CFBundleIdentifier to
	your name. com.yourDomain.com is typical.
	

7)  Exploring the BT_config.txt file

	Expand the BT_Config folder and select the BT_config.txt file. This is the main
	configuration file for your application. Adding screens, removing screens, and updating
	the way the app looks and feels is all done by making changes to this file.
	

8) BT_config.txt details


	This text file is a JSON formatted file. It is editable with any text editor and is 
	human-readable. Web-Developers may recognize the format because it is commonly 
	used in web-applications. The principal behind JSON is "keys and values." If you 
	spend a few minutes reviewing the data it will become easier to understand. 
	
	Keys in the config file are things such as "itemId", "themeName" and "listStyle"
	and values are things such as "my cool theme", "22939", and "round"
	Wrap these in curly braces and you have a well formed JSON stucture, like this:
	
	{"itemId":"22939", "themeName":"my cool theme", "listStyle":"round"}
	
	NOTE: Keys and Values are ALWAYS surrounded with double quotes. A key with an empty
	value still uses the double quotes but nothing is in between them. 
	
	Example empty Key/Value:
	
		"backgroundColor":""
		
	Example non-empty Key/Value:
	
		"backgroundColor":"#FFFFFF"
		
	Multiple JSON structures are wrapped in square brackets and each structure is 
	separted with a comma, like this:
	
	[
		{"itemId":"1", "themeName":"my cool theme", "listStyle":"round"},
		{"itemId":"2", "themeName":"another theme", "listStyle":"plain"},
		{"itemId":"3", "themeName":"my favorite", "listStyle":""}
	]
	
	Note: The last item does not have a comma because it is "last in the list." 


	The core configuration sections of data in BT_config.txt are
	
	"appConfig"
	"themes"
	"tabs"
	"screens"
	
	appConfig:
		Application level properties for your application.
	
		appConfig:buzztouchAppId
			A unique id connecting your app to an online control panel. This is unused in 
			this pre-release. There is no back-end support for the pre-release version.
		
		appConfig:buzztouchAppAPIKey
			Same as above, usused without backend support.
		
		appConfig:dataURL
			When backend support is used (an online system that provides data to your
			applications), this is the URL to the system that powers your app. 
			This URL could point to a file on your website or the buzztouch control panel. 
			Again, backend support is not available in this pre-release.
		
		name					
			The name of your application. Unused in the pre-release but could be useful if the
			name of the app needs to be presented to a user, included in an email, etc.
		
		version					
			The version of your application. This is for organizational purposes. Incrementing
			this could help you with version control.
								
		themeItemId				
			If used, this points to the themeItemId for a theme configured in your 
			configuration data (themes are discussed next).
								
		modifiedUTC				
			Used in conjuction with the dataURL. This value is used to determine if your 
			app's configuration file has changed on the remote server. 
			Unused if a dataURL is unused.
								
	themes: An array of themes from zero to many in length, you may have zero themes.				
			If a theme is used, the values in the theme are used in every screen. 
			Example: If your theme has a navBarBackgroundColor set, every screen 
			in your app will use this color unless it has over-ridden the value.
			
		theme:itemId
			A unique value identifying the theme. Themes must have a unique itemId.
			
		theme:splashScreenItemId
			If this theme uses a splash screen. This is the itemId of the splash screen. 
			
		theme:navBarBackgroundColor
			A hexidecimal value for the color to use, including the # character.
			Example; #000000 is black, #FFFFFF is white, #FFCC66 is a weird orange.
			You can also use some special key-words for colors. "clear" or "stripes" to 
			make the background color. Note: "stripes" does not work in the nav bar but
			does work for screen background colors.
			
		theme:textOnBackroundColor
			The color of the text that may be displayed on some screens. Balance the 
			textOnBackroundColor with the screens background color.
			
		theme:backgroundColor
			Setting a solid color (hex value) or "clear" or "stripes" will set the background
			color for all the screens in the app (unless a screen overrides it).
	
		theme:backgroundColorOpacity: 
			In some cases it's useful to make the background color "transparent" or "clear"
			but not totally invisible. 0 - 100, 0 is invisible.
			
		theme:backgroundColorGradientTop
			Combining this value with backgroundColorGradientBottom will create a linear gradient
			from top-to-bottom on the screen. Looks great!
			
		theme:backgroundColorGradientBottom
			Combine this with backgroundColorGradientBottom for just the right look.
			
		theme:backgroundImageNameSmallDevice
			The name of the image to use for small devices
			
		theme:backgroundImageURLSmallDevice
			The URL to an image on a remote server. Unused if the backgroundImageName exists
			in the projects bundle (drag it into Xcode).
			
		theme:backgroundImageNameLargeDevice
			The name of the image to use for large devices
		
		theme:backgroundImageURLLargeDevice
			The URL to an image on a remote server. Unused if the backgroundImageName exists
			in the projects bundle (drag it into Xcode).

		theme:backroundImageOpacity
			Background images are positioned "on top" of background colors and gradients. This
			means an image with opacity 100 will totally hide a background color. Use this in
			combination with the backround color to achieve the desired results.
			0 - 100, zero is invisible
			
		theme:listStyle
			This changes the style of the list on "list screens" such as menus. Valid
			values are "plain" or "round", "plain" is default.
			
		theme:listBackgroundColor
			The background color of the list itself. Balance the screens background color
			with the lists background color.
		
		theme:listRowBackroundColor
			The background color of the individual items in a list.
			
		theme:listRowFontColorLabel1
			The color of the text in "label1" in lists. Some lists have two labels.

		theme:listRowFontColorLabel2
			The color of the text in "label2" in lists. Some lists have two labels.
			
		theme:listRowSparatorColor
			The color of the line in between items in a list.
			
		theme:listWhiteIcons
			If a list item uses an icon, it's name is entered in the configuration file. 
			Example: bird.png would show a cool bird icon. If your color scheme is dark you
			could show the white version of the same icon. This approach allows two different
			themes to use the same "icon names" but look entirely different.
			
		theme:listRowSelectionStyle
			When a list item is selected. Valid values are "blue", "gray" or "none"
			
		theme:listIconWidthSmallDevice
			Changes the width of the "box" the icons sits in. Setting this large will also
			move the text in a list to the right. If you use custom icons, set this accordingly.
			
		theme:listIconWidthLargeDevice
			Changes the width of the "box" the icons sits in. Setting this large will also
			move the text in a list to the right. If you use custom icons, set this accordingly.

		theme:listRowHeightSmallDevice
			The height of the rows in lists or menus
			
		theme:listRowHeightLargeDevice
			The height of the rows in lists or menus
		
		theme:listRowFontSizeSmallDevice
			The size of the font in list items. 20 is common, make it smaller to fit more 
			text on the same line. Text does not wrap in menu items or lists.
		
		theme:listRowFontSizeLargeDevice
			The size of the font in list items. 20 is common, make it smaller to fit more 
			text on the same line. Text does not wrap in menu items or lists.

	tabs:
		Up to 5 tabs. If a list of tabs is provided, the app will have a tabbed interface. 
		If no list of tabs is provided, the app will use the first screen
		it it's list of screens	as the home screen. Hint: If you use a splash screen, 
		put it in the end of your list, not the beginning. Crazy stuff happens when 
		the app animates the splash screen over and over again because it's your splash 
		screen and your home screen!
		
		tab:itemId
			A unique id for the tab, all tabs must have unique ids
			
		tab:textLabel
			The text to display under the icon
		
		tab:iconName
			The name of the icon to display. This icon must exist in the BT_Images/Icons folder.
			
		tab:homeScreenItemId
			The itemId of the screen (from the list of screens) to set as this tabs home screen.
			
	screens:
		The main list of screens to use in your application. Some screens use many settings
		and properties while others use only a few. There are some core settings common to
		every screen that you may or may not include. Example: There are settings to control which
		button is added to the right side of the nav bar, some screens will use this, some will not.
		
		Example:

		This screen has no button in the nav bar on the right side
		{"itemId":"9999", "screenType":"BT_screen_settingsDevice", "navBarTitleText":"Device"}
		
		This is the same screen but includes a right side navigation button that launches another
		screen with an animation.
		{"itemId":"9999", "screenType":"BT_screen_settingsDevice", "navBarTitleText":"Device",
		
		}
		
		
		
		Optional Properties For All Screens
		------------------------------------
		screen:hideBottomTabBarWhenScreenLoads
			In tabbed apps, it normal to have the bottom tabs hide when a new screen tranistions
			in. This is default "1". Set it to "0" to keep the tabs visible when a new
			screen loads. Again, only applicable to tabbed apps.
			
		screen:loginRequired
			Values are 1 to require a login, 0 to not require a login. Use this setting to 
			protect any screen. See BT_screen_settingsLogIn for more info about password
			protecting screens.
			
		screen:navBarBackButtonText
			Set this to over-ride the standard "back" text. Note: The back text comes from 
			the Localizable.strings file in BT_config. This means you can create as many
			localized versions as you want.
			
			
		screen:navBarRightButtonType
			To include a button in the nav bar on the right side. Most applications include an
			info button in the nav bar on the home screen to allow users to learn about the app. 
			
			Valid values are:
			"infoLight", "infoDark", "details", "addBlue", "done", "cancel", "edit", 
			"save", "add", "compose", "reply", "action", "organize", "bookmark", 
			"search", "refresh", "camera", "trash", "play", "pause", "stop", 
			"rewind", "fastForward"
			
			The button you choose depends on which screen you want to load when it's tapped. 
			
		screen:navBarRightButtonTapLoadScreenItemId
			This is used in conjuction with the right side navigation bar button. Enter the
			itemId of the screen you want to load when the button is tapped. 
			
		screen:navBarRightButtonTapTransitionType
			When the right button loads the screen, what type of transition should be used?
			
			Valid value are:
			"curl", "flip", "fade", "grow", "slideUp", "slideDown"
		
		ENTERING THESE VALUES FOR A SCREEN WILL OVER-RIDE THE APP'S THEME
		
		screen:navBarBackgroundColor
		screen:textOnBackroundColor
		screen:backgroundColor
		screen:backgroundColorOpacity: 
		screen:backgroundColorGradientTop
		screen:backgroundColorGradientBottom
		screen:backgroundImageNameSmallDevice
		screen:backgroundImageURLSmallDevice
		screen:backgroundImageNameLargeDevice
		screen:backgroundImageURLLargeDevice
		screen:backroundImageOpacity
	
		

The information provided beyond this is for individual screens and each screens
option. There are many screens that are not included in the pre-release version of the
software and we look forward to introducing them. Scroll down to the end of the list to 
see how to extend the software and create your own custom screens.

BT_screen_menuList
---------------------
	
	//propertes
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_menuList",
		"listHeaderHeightSmallDevice":"10",
		"listHeaderFooterHeightSmallDevice":"10",
		"listHeaderHeightLargeDevice":"10",
		"listHeaderFooterHeightLargeDevice":"10",
		"headerImageNameSmallDevice":"myheader_iphone.png",
		"headerImageNameLargeDevice":"myheader_ipad.png",
		"headerImageURLSmallDevice":"http://www.yourdomain.com/images/myheader_iphone.png",
		"headerImageURLSmallDevice":"http://www.yourdomain.com/images/myheader_ipad.png",
		"headerImageTopPosSmallDevice":"10",
		"headerImageTopPosLargeDevice":"10",
		"headerImageHeightSmallDevice":"150",
		"headerImageHeightLargeDevice":"150",
		"headerImageWidthSmallDevice":"300",
		"headerImageCornerRadiusSmallDevice":"10",
		"headerImageCornerRadiusSmallDevice":"10",
		"headerImageWidthLargeDevice":"300",
		"headerImageTapLoadScreenGuid":"0001",
		"headerImageTapLoadScreenTransitionType":"flip",
			menuItems[
					{
					"itemId":"1", 
					"loadScreenWithItemId":"0001", 
					"labelText":"Call Us", 
					"iconName":"phone.png", 
					"rowAccessoryType":"arrow", 
					"soundEffectFileName":"", 
					"transitionType":""
					},
					{
					"itemId":"2", 
					"loadScreenWithItemId":"0002", 
					"labelText":"Email Us", 
					"iconName":"envelope.png", 
					"rowAccessoryType":"arrow", 
					"soundEffectFileName":"tink.mp3", 
					"transitionType":""
					}
			]
	}	

	Comments: 

	The BT_screen_menuList serves as a menu, a launching pad for other screens.
	The list properties in the app's theme can be over-ridden to adjust
	the style of individual menus. The headerImage properties allow you
	to add an image. The image is "tappable" and will load the screen identified by the
	headerImageTapLoadScreenGuid property. Adjust he headers image properties, along with
	the lists listHeaderHeight to get the image positioned properley. A large headerHeight
	value will move the list "down" leaving room above the list for an image. A short list
	of three or four items could be used, along with a large "header height" property to 
	place the image under the list intead of above. Header and Footer "heights" are ignored
	for "plain" lists. Use "round" lists to do move the table down the screen by adjusting
	the headerHeight.
	
	Menu Items: Each menu item represents an item in the list. When an item is tapped
	it will load the screen with the loadScreenWithItemId and use the transition set for
	transitionType. 
	
	Valid values for transition types are:
	"curl", "flip", "fade", "grow", "slideUp", "slideDown"

	
	Sound effects: To play a sound when a menu items is tapped, enter the file name of the 
	sound. The sound must be an .mp3 file and must reside in the BT_Sounds folder.
	Add sounds as needed. IMPORTANT: These sounds are meant to be VERY SMALL in file size.
	Short, one second (or less) sound effects are appropriate. It's	important to understand
	that the Sound Effect Files are loaded into memory when the app launches to prevent 
	an annoying "delay" when it's time to play the sound. Because of this, 
	large sound files consume a large amount of memory and may overload the device. Do not
	use large sound effect files. 



BT_screen_menuButtons
---------------------
	
	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_menuButtons",
		"buttonLayoutStyle":"grid",
		"buttonLabelLayoutStyle":"above",
		"buttonOpacity":"100",
		"buttonDropShadow":"1",
		"buttonShadowColor":"#000000",
		"buttonSizeSmallDevice":"65",
		"buttonPaddingSmallDevice":"10",
		"buttonCornerRadiusSmallDevice":"10",
		"buttonSizeLargeDevice":"60",
		"buttonPaddingLargeDevice":"0",
		"buttonCornerRadiusLargeDevice":"0",
		"buttonLabelFontColor":"#000000",
		"buttonLabelFontSizeSmallDevice":"15",
		"buttonLabelFontSizeLargeDevice":"13",
			menuItems[
				{
				"	itemId":"1", 
					"loadScreenWithItemId":"0101", 
					"labelText":"Call Us", 
					"iconName":"gears.png", 
					"useWhiteIcon":"1", 
					"backgroundColor":"#91A2B8", 
					"imageNameSmallDevice":"", 
					"imageURLSmallDevice":"", 
					"imageNameLargeDevice":"", 
					"imageURLLargeDevice":"", 
					"transitionType":"curl"
				},
				{
					"itemId":"2", 
					"loadScreenWithItemId":"0101", 
					"menuItemType":"BT_menu_buttonItem", 
					"labelText":"Settings", 
					"iconName":"gears.png", 
					"useWhiteIcon":"1", 
					"backgroundColor":"#91A2B8", 
					"imageNameSmallDevice":"", 
					"imageURLSmallDevice":"", 
					"imageNameLargeDevice":"", 
					"imageURLLargeDevice":"", 
					"transitionType":"curl"
				}
			]
	}	

	Comments: 

	The BT_screen_menuButtons screen is a grid, a stripe, or a bar of buttons. Like the items
	in a list menu, each button launches a screen. The properties in the button's screen
	data apply to all the buttons in the list (like the size and the corner roundness, etc)
	
	buttonLayoutStyle
		Valid Values: "grid", "veritcalLeft", "verticalRight", "horizontalTop", "horizontalBottom"
			
	buttonLabelLayoutStyle
		Valid Values: "above", "top", "middle", "bottom", "below"

	
	Menu Items: Each button represents an item in the list. When a button is tapped
	it will load the screen with the loadScreenWithItemId and use the transition set for
	transitionType. 
	
	Valid values for transition types are:
	"curl", "flip", "fade", "grow", "slideUp", "slideDown"


	Button Color / Images / Opacity:
	Buttons can be images, colors, icons, etc. If an icon name is provided it must reside
	in the BT_Images/Icons folder. Images are background images and can be loaded from
	a remote data source. If an icon name is provided the icon will be placed "top top" of the
	buttons background color and / or background image.

	
	Sound effects: To play a sound when a button is tapped, enter the file name of the 
	sound. The sound must be an .mp3 file and must reside in the BT_Sounds folder.
	Add sounds as needed. IMPORTANT: These sounds are meant to be VERY SMALL in file size.
	Short, one second (or less) sound effects are appropriate. It's	important to understand
	that the Sound Effect Files are loaded into memory when the app launches to prevent 
	an annoying "delay" when it's time to play the sound. Because of this, 
	large sound files consume a large amount of memory and may overload the device. Do not
	use large sound effect files. 


BT_screen_error
---------------------

	//properties
	There are no configuration properties for this screen. It's only used if your
	app trys to load a screen that it can't find. When a menu item or button is tapped, 
	the app locates the screen using that menu items "loadScreenWithItemId". If this 
	screen doesn't exist or can't be found (typo?) the error screen is displayed instead.
	


BT_screen_splash
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_splash",
		"backgroundColor":"#000000",
		"backgroundColorOpacity":"100",
		"backgroundImageOpacity":"100",
		"backgroundImageNameSmallDevice":"buzztouchSplash.png",
		"backgroundImageURLSmallDevice":"http://www.buzztouch.com/images/buzztouchSplash.jpg",
		"backgroundImageNameLargeDevice":"buzztouchSplash.png",
		"backgroundImageURLLargeDevice":"http://www.buzztouch.com/images/buzztouchSplash.jpg",
		"transitionType":"fade",
		"startTransitionAfterSeconds":"2",
		"transitionDurationSeconds":"1"
	}	
	
	Comments: 

	Allowed transition types: "fade", "shrink", "curl"
	Opacity Values: 0-100, zero is transparent
	Background color: A hexidecimal color code like #000000 for black. Or, "clear" or "stripes"
	for the native iPhone striped background look.

	To use a splash screen, your application must be using a theme and that theme
	must have a splashScreenItemId set. The splashScreenItemId in the app's theme points to
	the itemId of the screen to use as the splash. 
	
	Example: "splashScreenItemId":"0001" (0001 would be the itemId of the splash screen) 
	
	The background image is "on-top" of the background color. This means an image with
	"backgroundImageOpacity":"50" would show the underlying "backgroundColor" beneath it. 



BT_screen_call
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_call",
		"number":"(839) 333-2222"
	}
	
	Comments: This is not an actual "screen" but does use the same data format for consistency. 
	Enter the number to call when the menu item or button is pressed.



BT_screen_email
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_email",
		"emailSubject":"My Email Subject",
		"emailToAddress":"fans@buzztouch.com",
		"emailMessage":"Please call me about your app..."		
	}
	
	Comments: This screen uses the devices native email compose sheet. Because of this, 
	custom transition types are not supported for "Email Us" menu items.


BT_screen_smsText
---------------------
	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_smsText",
		"textToNumber":"123456789",
		"textMessage":"My SMS message"
	}
	
	Comments: This is not an actual "screen" but does use the same data format for consistency.
	Enter the number to send an SMS / Text message to when the menu item or button is pressed.



BT_screen_customURL
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_customURL",
		"navBarTitleText":"Custom URL",
		"dataURL":"http://www.mywebsite.com/mywebpage.php",
		"localFileName":"mywebpage.html",
		"showBrowserBar":"1",
		"showBrowserBarRefresh":"1",
		"showBrowserBarStop":"1",
		"showBrowserBarBack":"1",
		"showBrowserBarForward":"1",
		"showBrowserBarLaunchInNativeApp":"1"
	}

	Comments: This screen loads a web-page from a remote server, or from within
	the app's cache. The behavior of this screen depends on what you enter 
	as the localFileName.
	
	a)	No saveAsFileName is entered.
		The web-page is downloaded (refreshed) everytime the screen loads.
	b) 	You enter a localFileName ending in .html, or .pdf
		The app's cache will be checked for a version it downloaded the last time
		the screen was refreshed. If it's found in the cache, it will load it.
		This means you will want to be sure to include the browser navigation bar
		with a refresh button.
		
	If you're using a localFileName it must end with .html, or .pdf but the 
	dataURL does not. Example: To load and save a .PHP file from your server, it would be:
	"dataURL":"http://www.myserver.com/mypage.php",
	"saveAsFileName":"mypage.html"
	
	DOWNLOADING AND SAVING HTML FILES FOR OFFLINE USE IS DESIGNED TO HELP YOU IMPROVE
	THE EXPERIENCE FOR YOUR END USERS. IT MEANT TO ALLOW YOU TO SAVE FILES YOU DOWNLOAD
	FROM YOUR WEBSITE. DON'T EXPECT GOOD RESULTS IF YOU	SAVE SOMEBODY ELSES FILE LOCALLY, 
	LIKE "GOOGLE" or "YELP" or "LINKED IN" THEN LOAD IT. THESE PUSLISHERS MAKE EXTENSIVE
	USE OR EXTERNAL JAVASCRIPT FILES THAT WILL RARLEY WORK. IF YOU'RE POINTING TO A FILE
	YOU DID NOT AUTHOR, LEAVE THE localFileName PROPERTY BLANK.
	


BT_screen_localHTML
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_localHTML",
		"navBarTitleText":"Local HTML",
		"localFileName":"mywebpage.html"
		"showBrowserBar":"1",
		"showBrowserBarRefresh":"1",
		"showBrowserBarStop":"1",
		"showBrowserBarBack":"1",
		"showBrowserBarForward":"1"
	}

	Comments: This screen loads a web-page from within
	your project's BT_HTML folder (drag it into xcode). 
	
	b) 	You enter a localFileName ending in .html, or .pdf
		The bundle will be checked to see if you included this file in your
		Xcode project (names are case sensitive). If it's found in the bundle, it 
		will load it. This type of screen is useful in many cases but it's important to
		remember that the file will not be "updatable" remotely. You will need to
		re-compile your application if you change the contents of the file.

	IMPORTANT: IF YOU INCLUDE Javascript FILES IN YOUR XCODE PROJECT YOU MAY SEE THIS
	WARNING WHEN COMPILING. THE Javscript FILE MAY NOT BEHAVE AS EXPECTED UNTIL YOU FIX THIS.
		
	"warning: no rule to process file '$(PROJECT_DIR)/sample.js' of type sourcecode.javascript 
	for architecture i386"

	TO FIX THIS, YOU MUST TELL XCODE NOT TO COMPILE THE .JS SOURCE CODE FILE, DO THIS BY:
	
	a)	Expand your target in the Groups and Files list
	b)	Remove the JavaScript file from the Compile Sources build phase
	c)	Add it to the Copy Bundle Resources build phase.



BT_screen_localDoc
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_localDoc",
		"navBarTitleText":"My PDF File",
		"localFileName":"sample.pdf"
		"showBrowserBar":"1",
		"showBrowserBarRefresh":"1",
		"showBrowserBarStop":"1",
		"showBrowserBarBack":"1",
		"showBrowserBarForward":"1"
	}

	Comments: This screen loads a document from within
	your project's BT_DOCS folder (drag it into xcode).
	
	Supported Doc Types:
	
	Adobe PDF (.pdf)
	MS Word (.doc, .docx)
	MS Excel (.xls, .xlsx)
	MS PowerPoint (.ppt, .pptx)
	Text (.txt)
	
	
	Enter a localFileName to load. The projects bundle will be checked to see if you 
	included this file in your Xcode project (names are case sensitive). If it's 
	found in the bundle, it will load it. This type of screen is useful in 
	many cases but it's important to remember that the file will not be "updatable" 
	remotely. You will need to re-compile your application if you change the contents of 
	the file. Use a BT_screen_customURL screen if you want to provide a dataURL




BT_screen_settingsLogin
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_settingsLogin",
		"navBarTitleText":"Login / Logout",
		"navBarTitleText":"Login", 
		"labelLogInId":"Username:", 
		"labelPassword":"Password:", 
		"dataURL":"http://www.yourdomain.com/authenticate.php?logInId=[userLogInId]&logInPassword=[userLogInPassword]"
	}
	
	Comments: Every screen can be login protected by adding ""loginRequired":"1" in the
	screens configuration data. Authentication is handled by a remote server at the
	dataURL. The username/password entered will be merged into the dataURL so the server
	can process the entries and allow or dissallow access to a login protected screen.
	The authentication script must return a "fail" or a "success" value, 
	JSON formatted like this (all on one line):
	
	//if failed
	{"result":"failed"}
	
	//if passed
	{"result":{"status":"valid", "userGuid":"uniqueIdOfUserFromYourDatabase", 
		"userDisplayName":"Your users name", "userEmail":"usersEmail"}
	
	Example:
	If a user failed authentication, and you use a .PHP backend, your script would output
	the message on the very first line - it's the only thing printed to the screen:
	
	echo "{\"result\":\"failed\"}";
	
	If a user passed authentication, and you use a .PHP backend, your script would output
	the message on the very first line - it's the only thing printed to the screen:

	echo "{\"result\":{\"status\":\"valid\", \"userGuid\":\"0000000\", 
		\"userDisplayName\":\"Joe Smith\", \"userEmail\":\"joe@domain.com\"}}";
		
		
		
BT_screen_settingsTheme
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_settingsTheme",
		"navBarTitleText":"Themes"
	}
	
	Comments: This screen allows a user to select a theme from the list of themes
	configured in your applications config file. If a user selects a theme, it's 
	remembered and used each time the app launches on that persons device.
	
	
BT_screen_settingsLocation
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_settingsLocation",
		"navBarTitleText":"Location"
	}
	
	Comments: This screen allows a user to "prevent" or "allow" the device to report
	it's location. If a user turns this of, and you "merge" the devices location
	information in a URL (for backend reporting purposes), latitude and longitude
	will equal zero or an empty string.
	
	

BT_screen_settingsDevice
---------------------

	//properties
	{
		"itemId":"uniqueIdForThisScreen",
		"screenType":"BT_screen_settingsDevice",
		"navBarTitleText":"Device"
	}
	
	Comments: This screen shows some information about the users device. There are no
	selections for the user to make, just information to review.


End Of Individual Screen
/////////////////////////

More Notes:

Where are other "screen types" like videos, maps, music, etc? We have intentionally left
these and other screens out of the pre-release. We are working very hard to instroduce new
screens and features but feel it's best to get our early adopters "up to speed" on the
new version and how it's configured before creating more and more complexity. Stay tunes, it's
all coming fast!

Where to image come from:
	a) 	File exists in bundle. Use this image, ignore a possible download URL
	b) 	File DOES NOT exist in bundle, but does exist in writeable data directory: 
		Use it. (it was already downloaded and cached)
	c) 	File DOES NOT exist in bundle, and DOES NOT exist in writeable data directory 
		and an imageURL is set: Download it, save it for next time, use it.


Plugins:
	Creating your own screens, or having a developer help you create "just the right screen"
	is easy. buzztouch v1.5 supports creating new screens easily. We call these plugins.
	To create your own plugin, start with the sample plugin in the BT_Plugins directory then
	"point" a menu item or button to it by entering it's itemId in the loadScreenWithItemId.
	
	We are working toward developing the beste eco-system on the planet for iOS and Android
	Developers. Easily creating and SELLING plugins is in the very near future. Stay tuned and
	look for changes on the site that focus on helping developers (new and experienced) find 
	new and exiciting ways to earn some serious income.  

---------------
End of Document








	
	
	

