This post could get lengthy. No, it will get lengthy! Read on if you're tinkering with the Plugin Creator tool and wondering about using Dynamic values from the JSON data for each screen. Bascis: When a plugin loads, and is showing in the app, it has access to the JSON data for that screen configured in config.txt file in the project (or downloaded from a URL). In iOS, this property is called self.screenData and in Android it's called this.screenData (different semantics, same thing). This is the "screenData" property of this "class file" and this is same concept in iOS and Android. Objective C and Java are NOT that much different - really - they are both Object Oriented but use different syntax. I'm getting off track! Back to JSON... The screen data for a screen will look like.... {"itemId":"unique id of screen in control panel", "itemType":"the class file name of the plugin", "navBarTitleText":"the title", "backgroundColor":"#000000", "someOtherProperty":"someOtherValue", "yetAnotherProperty":"yetAnotherValue"} There is no limit to the number of properties allowed in this JSON for any given screen. All screens will have the first two values (itemId and itemType) but none of the others are required. It's up to the plugin to use or ignore anything in it's JSON data. So, you may have a plugin with a dozen or so items in the JSON or only a few or only the required two. Have a look at the config.txt file for an app, you'll see that each screen uses a different set of JSON properties depending on the purpose of the screen. An example of how this data is passed around can be seen near the top of each plugin. For iOS, have a look at this line in a plugin you made with the tool: [BT_viewUtilities configureBackgroundAndNavBar:self:[self screenData]]; For Android it's: BT_viewUtilities.updateBackgroundColorsForScreen(this, this.screenData); Nearly the same thing huh. I'll convince you eventually that Objective C and Java are THE SAME! Anyway, in english this means: "Hey BT_viewUtilities class, update the background and the nav bar for this screen" BT_viewUtilities could only know how to do this if it knew what screen to do it for - right? You'll notice in that method call that we are TELLING BT_viewUtilities what screen we are on by passing in all the JSON data for this screen. If the JSON data has some background or nav bar "rules" included, they will be found and used to configure the background and the nav bar. Easy eh. OK, so screenData is a bunch of JSON available in your plugin. You may ask two other things. Q1: "how can I access some random value in my screen's JSON" Q2: "how can I allow a user of my plugin to alter the JSON for one of their screens (like the name of a song or something)" Answer 1: You could write a bunch of code to find and read in the value from the JSON in your screen. Or, you could use the handy-dandy-already-built-and-used-all-the-time method called: getJsonPropertyValue in the BT_strings class. It's a method I wrote 100 years ago to help us. The method has the same name in iOS project and Android projects. It's purpose is to help you find a value for some random JSON property you're looking for. When used in iOS it looks like: myValue = [BT_strings getJsonPropertyValue:self.screenData.jsonVars:@"nameOfJsonKey":@""]; When used in Android it looks like: myValue = BT_strings.getJsonPropertyValue(this.screenData.getJsonObject(), "nameOfJsonKey", ""); myValue will now hold the value of the JSON property in that screen's data. myValue could be blank. It will be blank if the key does not exist in the JSON values for the screen. If you want to return a default value (if the screen doesn't have it setup), use the "" at the end. Insert a value in those empty quotes to return IF the JSON key doesn't exist. Whoo, bad ass eh! So, easy to get values from JSON data using the fancy-pants getJsonPropertyValue in the BT_strings class. Answer 2: How the heck can users modify the JSON data. A few ways. --By hand after downloading the project. Not fun and not easy but possible. --Using the control panel. Much easier on users, more difficult on developers. In most cases you'll ALWAYS want to allow users of your plugin to use the control panel to manipulate it's properties and behavior. This means you'll need to access the buzztouch.com database (or the self hosters database) and you'll need to give them controls to do this. This is the purpose of the /index.php file and companion /save_JSON.php file that ships with each plugin you make using the Plugin Creator tool. /index.php is what the user sees and interacts with in the control panel. The /save_AJAX.php file actually saves their entries to the database. There are no rules about how these files work. If you've worked with PHP before they are very very simple. Most folks haven't. We get that. There are really two ways to do this. The way you're used to where all the individual properties for a plugin are listed nicely with a text box and a save button. Or, plopping all the JSON values in a big box in "raw" format so the user can see them and a save button. This gets kinda' ugly but is useful. In fact, we may change the Plugin Creator tool to just default to a box with a save button to allow easy JSON changes. This would allow tons of flexibility but would also confuse users, not sure. Anyway, make the HTML controls needed to display and change the values, send them to /save_AJAX.php to commit to database or just create something of your own :-) Last thing (promise): The reason we have to inspect and approve plugins you make for your buzztouch.com control panels is that you COULD do a serious amount of harm to our backend using the /index.php and /save_AJAX.php files. You could do this intentionally or unintentionally, doesn't matter. It would be much easier if we didn't allow anyone access to user databases but we've decided that we'll be able to get efficient at inspecting plugin uploads and it's necessary for maximum flexibility. Hope this helps... UPDATE: I created a simple lesson / tutorial about how the HTML is setup in the /index.php file. And how to add additional JSON properties to you custom plugin. See this: http://www.buzztouch.com/resources/index-plugin-sample-property.txt

So awesome, this is just what I needed. I've actually been using this method to grab JSON data (iOS): NSDictionary *element = [self.screenData.jsonVars objectForKey:@"myJSONElement"]; This way you can retrieve a Dictionary of information and you can pretty much make dictionaries that are accessible via JSON. Very fun stuff. Anyways, there's still one thing I'm a little confused on. How do we "send the entries from the index.php file to the save_AJAX.php?" It would be absolutely amazing if you could make a quick tutorial on that. If not that's ok, I know your busy and I'm sure I can figure it out and whip up a tutorial for you if you would like :) This alone was very helpful. THANKS DAVID!

No worries. For sure this stuff needs documented. Hate that part, just want to create things! I posted the following info here, download and save it? http://www.buzztouch.com/resources/index-plugin-sample-property.txt NOTE: DO NOT COPY AND PASTE THIS HTML, THIS FORUM REMOVED SOME CHARACTERS and FORMATTING. USE THE .TXT FILE AT THE URL ABOVE TO COPY / PASTE FROM. 1) Open the index.php file for a plugin. This will be much easier if this is already installed on a self hosted box somewhere so you can test it? Anyway, open /index.php for a test plugin. 2) Copy and Paste this HTML snippet in to the /index.php file. Add it under the nickname property section (see notes in HTML of index.php): <div class='cpExpandoBox colorLightBg'> <a href='#' onClick="fnExpandCollapse('box_myCustomProperty');return false;"><img src='<?php echo APP_URL;?>/images/arr_right.gif' alt='arrow' />Custom Property</a> <div id="box_myCustomProperty" style="display:none;"> <div style='padding-top:10px;'> <b>Enter a Value</b><br/> <input type="text" name="json_myCoolProperty" id="json_myCoolProperty" value="<?php echo fnGetJsonProperyValue("myCoolProperty", $jsonVars);?>" /> </div> <div style='padding-top:5px;'> <input type='button' title="save" value="save" class="buttonSubmit" onClick="saveAdvancedProperty('saveResult_myCustomProperty');return false;" /> <div id="saveResult_myCustomProperty" class="submit_working">&nbsp;</div> </div> </div> </div> 3) Save, Upload to your server. Load this plugin in an app, you'll see your new "Custom Property" section to manipulate. Enter value, click Save, cool eh! Comments: -- The "box" around the section for your custom value (the one that expands and collapses) is called "box_myCustomProperty" in the HTML. id="box_myCustomProperty" The link that expands / collapses this box has an onClick method to open / close the box. See onClick="fnExpandCollapse('box_myCustomProperty') The fnExpandCollapse method is included in the index.php page near the top. -- The HTML input element has id="json_myCoolProperty" Because it has "json_" appended to the start of it's name (and id) the /save_AJAX.php file knows that you want this value included in the JSON data when the user clicks Save. -- The HTML input element uses value="<?php echo fnGetJsonProperyValue("myCoolProperty", $jsonVars);?>" This means that when the page loads (the index.php page), the value for "myCoolProperty" will show in the entry box IF it exists in the previously saved JSON. In other words, the value the person entered then saved. -- The Save button uses: onClick="saveAdvancedProperty('saveResult_myCustomProperty');return false;" The saveAdvancedProperty() method (also in the index.php file higher up) takes one parameter / argument. The name of the HTML element to show the save results in. In this case, we're saying "save these values then put the results in the "saveResult_myCustomProperty" box. This is the <div> we created in the HTML under the save button in this section. save_AJAX.php returns the results of the save.

Holy Crap. That all makes sense (A thing to note, I hate Web stuff but love higher dev platforms). Ahhh it's moments like this when it's the best to be a programmer. I was looking in the example index.php file for a sample custom plugin i made and couldn't figure out for the life of me why it only had one parameter. Well all is fantastic now and I can't wait to release my first plugin (it's gonna be pretty awesome) I'm actually almost done with it. We'll back to work. Sorry to keep you and THANKS again David!

Very nice. Fred

Hi David, Thanks for this wonderfull documentation. It for sure will help us developing cool plugins. Really excited about all of this and can't wait to see what kind of plugins people are developing. Best Regards, Danny

Excellent. That is exactly what I figured out yesterday. Very cool (and a little scary) to see that I was doing exactly what you outlined here :) I got my plugin CP screen set-up to take in the new values. I was borrowing the HTML from another field and changing the variables and adding it. The fields like the BKG color and ones that have "drop down' options are a little trickier, but cool to have some pre-set values. Now to use those values in my plug-in. It looks like you just gave us that critical piece of knowledge and steps. Excited to study these posts and the notes more and keep at it. This really is the Magic of BT. To be able to learn to use it and manipulate it the way you intended with custom controls/fields/screens is amazing. No other APP making software/tools can compare to that type of functionality. That 'old' code you wrote is CUTTING EDGE today! Can't thank you enough for these posts and info and the great vids of late. KEY STUFF. Just need time to absorb and tinker with it all. THANK YOU!!

Whoa.. that's some heavy documentation! I've bookmarked this thread for later, this should go under resources in the how to's no doubt! Thanks David! Cheers, David buzztouchmods.com