iron-ajax… wat?! -- Polycasts #26

hey there polycasters Rob here many of you have written in and asked for an episode on the iron Ajax element there's a lot of questions around this element like when to use it and is it bad to mix your behavior with markup like that but in fact iron Ajax is one of the most useful elements you can have in your toolbox however its utility only becomes apparent when you combine it with data bindings anyway today on pocast I'm going to show you the power of working with Ajax using nothing but HTML let's check it out okay so today we're going to create an element that fetches GitHub issues and we're going to use iron ax to do that now I'm also going to use the Yen generator to scaffold out my element but if you don't want to use Yen you could use the seed element project which I will link to down in the show notes uh that will do the exact same thing as Yen Yen just goes a step further and it renames all the files for me which is pretty convenient so from my command line I'll type yo polymer l or sorry yo polymer seed GH issues to generate my element and once that's generated I can run poly serve which is our little local server and that'll let me preview the element as I'm developing it and you'll see here that it generates this URL that I can use to actually go look at my elements documentation so using the seed element it actually generates docs for us which is pretty cool it also has this demo link here which we can click on and that is going to show us uh sort of demo of the the boilerplate element that it has created so this is all just stuff that it has sort of sted out and we're going to replace all this in just a second now I mentioned we're going to use the GitHub API to fetch issues so going and looking at the API docs we can go down to the issues section and you'll see here that working with the GitHub API is pretty simple we just use get request to to fetch the issues for either like all the issues that are owned by a user or all the issues in a given organization right in our case what we're going to do is we're going to fetch all the issues for a particular repository so to do that we're going to need to install iron Ajax we'll go back to our terminal we'll split the panes and we will bow install iron aex passing the save flag so it gets written to our elements iron or our Elements by our Json file now that that is all good we can go look at the element that was stubbed out for us by yman so this is GH issues. HTML and if you browse around here you'll see there's a lot of kind of boiler plate markup that it's stubbed out just as an example for what an element could look like we'll ignore that for a second and just go ahead and import iron HX because we know we're going to want to use that and then I'll update my elements description so I'm going to say this is an element for fetching issues from GitHub and then I can go through and delete all of this extra markup that's inside of here so again I don't really need any of this it's just sort of example markup in case you haven't written an element before it's good to read through just to see what's possible but I want to strip it down to where I just have this sort of very bare skeleton next I'm going to drop the iron HX tag inside of my template and I'm going to configure it with a few attributes here so this Auto attribute tells iron Ajax to just automatically fetch data anytime it has a valid URL it's just going to go and and get some data this URL attribute as the name implies is going to be where we go and get our data from when that data comes back we're going to need to handle it as something so here we're saying handle it as Json I believe it also supports XML and you could also tell it to fetch things as document so for instance if you were fetching an HTML file you could say hey when that comes back I want to treat it as a document and it also fires events so there's a response event which we could listen to and we could have a Handler that that works with that but instead of writing a bunch of JavaScript to handle the response that comes back let's just go ahead and give it a URL so I'm going to tell it to look at Rob doson chart elements that's the repo where we'll pull our data from and we going to tell it to instead of you know handling that in JavaScript we'll just take the data that came back which is represented as this last response property and we'll create a scope variable for that called response now let's think about what's happened here for just a second I've got this one tag and it basically represents GitHub this is like a representation of the GitHub API I've configured it by saying this is where I'd like you to get data from and then I've basically used a data binding to create sort of a CL cative data provider so I don't really know the mechanics of how it is going in getting my data nor do I care like the implementation of How It's actually going and getting the data I don't actually care about instead all I care about is that it goes here and it gives me this data and with this data binding and you know because it's nice and declarative I can now hook onto it with different Dom nodes and they will stay in sync with data so this has removed the need for me to write a lot of java script in my my element normally I'd have to handle that response pick it apart you know go find the different Dom noes that I want to update with the new data here we're just saying hey I've got this nice declarative data provider and when that data comes back all my dom noes that bind to it will stay nice and in sync so pretty cool approach there this is a representation of the response that we're going to get back from GitHub you can see it's an array of objects and the properties that I care about are this one right here called HTML URL so this is the actual URL to the GitHub issue and then I also care about the title so this is what we'll we'll display in our list of issues so let's go back to our template here and because we've got this nice declarative data provider now uh let's let's generate some Dom for it to link up to so I'll create a template with a a Dom repeat template and I'm going to give it an items attribute and we're going to link these two together right so you can see this little linkage that we've created here we're saying the items should be linked to uh to that response so now now that these are are combined this template is going to try to iterate over that that collection that array of of objects so we can you know drop a a div with an anchor inside of here and we can bind two for every single item combined to its HTML URL and its title so now we're just generating this sort of list of anchor tags based on that response and this is pretty cool because again I didn't have to write a bunch of JavaScript to handle all this I just created this little linkage here I've got this nice little declarative data provider and I'm just generating Dom based on the data that it it returns so let's go look at the demo file that was that I I showed you earlier as part of our documentation we're going to clean this up a little bit so that we can preview our tag again Yan generates a bunch of boilerplate and it's cool if you haven't seen it before but in our case we're just going to delete it we'll drop in the GH issues tag I'll bump this up a little bit so you can you can kind of see a bit better and yeah let's just preview this thing in Chrome so we'll click on our demo button and we'll see these are the two issues that come back from that repo and click on one and open it in a new tab just to verify that came from Rob Dotson chart elements so okay yeah we've got our very basic element working it's fetching data from uh from from the GitHub API and so far we haven't really written any JavaScript whatsoever we're just fetching data we're generating Dom based on that data and that's kind of a cool flow but let's see if we can push this a little bit further and make this thing a bit more configurable so if we go back and we look at our elements definition you can see that I've hardcoded the path here which is you know kind of a bummer right I want I want anybody to be able to use this tag and so what I can do is I can take the owner and I can take the repo name and I can make these configurable properties of this element so let's go down to the properties object and stub out two properties one called owner and we're going to say that uh by default it's it has the value of polymer sure why not and we're also going to make it two-way bindable so we'll say it uh fires fires change events when it changes so we're saying it's notified true and we'll also create a another property called repo we'll also set that to polymer and this will also be to a bindable and lastly I'm going to create a a computed property called URL and what it's going to do is it's going to compute the values of owner and repo it's going to so if either of these changes it is going to recompute the URL where we're fetching from in GitHub and we're going to stub out method here for compute URL we'll say hey when we get owner and repo what we should do is we should take that that hardcoded URL that we were working with before so we'll just copy this we'll drop it into an array and we'll replace where it says you know where it has the owner and repo right here we'll just replace those with these two values that are being passed in so as someone is configuring our tag they're passing in an owner and repo that's going to update this URL so I'll pass this in and then we're just going to join the whole string with slashes to to turn it back into our URL and we'll say hey this is what iron HX should buy to this configurable computed URL now so let's uh let's switch back over to Chrome now that we got this set up and we can go look at our demo you see now we're seeing all the issues from the polymer repo we can actually open one of these and see yep organizations polymer polymer repo but let's configure it a little bit more so so now we can go and we can pass whatever owner and uh and repo we want because we have these properties and we can pass them uh values as attributes so let's look at polymer elements paper input refresh the page here now we're looking at issues from paper input so this is pretty cool now anybody can use this tag to to pull issues from GitHub which is pretty awesome right um but I think we can actually take this a bit further so just for funes let's take the uh the the demo that we're working on here and and wrap it in an auto binding template and this is going to let us use data bindings inside this space without creating our own tag and I'm just going to take uh owner and repo and make them bindable so I'll create two text inputs these are just native text inputs so one is going to bind to owner and one is going to be bound to this repo variable and because we're creating data bindings on native elements notice that I'm using this sort of special double colon syntax so this is sort of how how polymer allows you to set up data bindings on Native tags native tags they fire their own events when something has updated in the case of the the input element anytime you you have finished typing some text inside of it it is going to fire a change event and so we're saying hey when you hear the change event update the the owner binding right same with the repo binding so now I can go and I can replace these with uh those same scope variables owner and repo and now if we uh if we switch over to Chrome you'll see that at the bottom I've got these two text inputs they they are initially receiving the the values that the the GitHub issues element put out so owner and repo are initially polymer polymer but we can change these so we can say hey this should be polymer elements and this should be like iron a Jacks and watch here all of the issues update and that's because we have that auto attribute on our iron Ajax element so we've given it some new values it recomputed the URL it told iron Ajax to go fetch that new data and that updated our Dom for us and again we didn't need to write a bunch of JavaScript to manage all of this flow and that's again sort of the power of a nice declarative data provider like iron Ajax which is pretty cool um you can actually yeah you can open one of these up too and you can see that verify that it's actually pulling from polymer elements iron HX now another thing you may want to do with when you're working with Ajax is pass along parameters so you know you might be like hey I want to go to f.com uh dollar sign or sorry question mark Q equals like you know some some value or something like that right you can pass along parameters as you're as you're working with these URLs and if we look at the GitHub API you can see that there's a few parameters we could pass one of them is state so we could say hey give me all of the issues for this repo and maybe I want just the closed ones you know or just the open ones so that's that's one parameter that we can use another one is this down here for page so it's a little hard to see but we can actually paginate our URLs as well so we could be like hey I want I want page three of all of the closed issues stuff like that right so let's go and uh let's let's add that to our element as well we'll go back to our our markup here and we can give iron Ajax this prams attribute and you could give it this Json encoded object and that could be how you how you pass along parameters right so we can say State I want all the open issues and I want it to be page number one but again where's the fun in that let's let's make this configurable right right so much like we did with URL we can replace pams with a computed value so I'm going to create a binding for options it's what we'll call our computed value and we'll say that we want to create State and Page properties and we will create a new computed value called prop called options which will just compute State and page so anytime those change it is going to return a Json object with whatever the state is and whatever the page is so it's kind of a kind of a weird example but but you can see that it demonstrates how parameters work so now we can go back and we can create bindings for state and Page inside of our demo and just like we did with owner and repo uh I will create input fields for these as well so now when we swap back if you look you can see again it's initially bound to polymer polymer it defaults to all of the open issues and it defaults to page one and so let's change that let's say hey I want to see the closed issues in polymer okay that updates uh I want to see page three of the closed issues in polymer okay that updates and I want to look at page three of the closed issues from maybe like paper input and that works as well and again we can go back and we can open one of these and we going verify it's a closed issue coming from paper input so pretty cool we've created now this this pretty robust little little element it does a lot of really fancy stuff it's entirely configurable user can just go in and live edit it and they're getting all this data back it's updating the Dom and we're not having to write a bunch of JavaScript to manipulate the Dom in any way which is rat so when should you use iron Ajax well that really depends on context if you're in a situation where you've got like 30 iron Ajax tags sprinkled throughout your element then yeah maybe consider doing it with JavaScript instead but if you only need a simple data provider without a whole lot of fuss then perhaps iron HX is a good fit for your application we talked a lot about iron Ajax today but I've I've actually only barely scratched the surface and so if you go over to the catalog you can see that there's this iron Element Section you can go there and check out the docs for iron Ajax and there's a ton of things that this does it does you know the full breadth of what you can do in Ajax so you can add a body to it you could change the method to post or put um you can see all the the various methods that the element supports the events that it fires and so on so definitely go read through the docs of iron HX because there's a lot of power in this one little tag also a little bit of Shameless promotion here we just finished doing a big event in Amsterdam which we're calling our mer Summit um I will here I'll draw a little link here so you can you can click on that annotation to go to the actual website it's a full day of talks and code labs for you to check out to learn all things polymer uh so you can go check out our our playlist over here on the Chrome developers Channel and see all of our videos you can also go to our code labs and you can maybe click this as an annotation go check out all of our Cod Labs uh and again there's there's tons of stuff for you to play with with if you're if you're just getting started with polymer or even if you're you're a bit of a polymer Pro there's probably something in here for you so if you if you missed the polymer Summit go check that out that's it for today folks if you've enjoyed this episode consider clicking that little subscribe button down there at the bottom also if you have questions for me you can leave them in the comments or you can ping me on a social network of your choosing at # askpolymer as always thank you so much for watching and I'll see you next time [Music]