Building a XenForo 2 Add-on - Part 2: Creating and linking test pages
we're going to start off by building a test page and to build that test page we're going to need a collection of components to all come together we're going to need a controller that will take an incoming request and process it and then deliver something out we're going to need a route which will be the address of where our page is going to be and we're going to need a template which will control the final output so let's start off with the controller because everything else is going to hang off that so i'm going to come into my pad add-on directory here and create a new directory and i'm going to call it pub because this is going to be a public controller now i'm going to kind of do this the long way around because it's it's the gold standard it's the way that we do it in XenForo itself but so long as your classes extend the the correct bits and pieces then it doesn't really matter where you put them but i'm going to do it at the XenForo way just because that's what i always do so pub and controller and now i'm going to create a class inside here so new php class and seeing as we're making a scratch pad notepad type thing i'm going to create a controller called note which will deal with the notes that make up our scratch scratchpad so i'm going to call it note.php and i'll deal with the extension and everything else afterwards so let's okay that no i don't want to add that to git thank you now it automatically creates a namespace for me which is important because in a big object-oriented application like XenForo we use namespaces to make sure that we can identify different place different bits and pieces from where they come from so the namespace is quite easy to identify it's just the name of the add-on and then essentially the directory path down to where you are from a starting point of the add-on so demo pad pub controller we've got this class note and we need to extend the abstract controller i believe it's called from xf there we go so now it's automatically added the abstract controller in the list of classes it's going to use and that is now essentially ready to go it doesn't do anything yet but it does exist so in order to use that we need to tell XenForo how to get to it and we do that with a root so let's head to the front end of XenForo and you can see that at the moment i'm at the the members root and i'm going to change that to slash notes and it's going to tell me that it has no idea what i'm talking about there is no root that controls slash notes and as there's no control there's also no action so what we need to do is we need to go to the control panel and create a route that will i will put glue these things together so development routes add a route this can be a public route and the route prefixes as you can see there notes so that will correspond to this slash notes here i'm using full friendly urls here just for ease of typing but if you're not using friendly urls then the the identification of the route should be relatively straightforward anyway i'm going to ignore all that stuff for now and just come to the controller now you can see that i've actually done this before and the controller is demo backslash pad because once we're in php we have to separate directory paths with backslashes and then a colon and a note and this is essentially saying any note controller that exists within the demo pad so we'll say okay to that and notice that it's pre-selected the demo scratch pad notepad thingy because that's what we specified in our conflict.php and we'll hit save so now the notes root is here and it tells me that it's going to respond to notes slash so if i come back here and hit refresh again then it won't work yet but we will get a new error so now it's saying invalid action but the controller was demo slash pad colon note and the action was index so we've got two things to note here first of all we have no action we only have the root and as a result XenForo will look for an action called index in the same way as a web server tends to treat indexed html or index.php within a directory as the default document so if you don't specify a document it will return index.something or other XenForo does something similar with actions if you don't specify an action it will look for an action called index so let's create that we'll come into here and on a new line we'll have a public function called actionIndex() don't need to put anything else in there for now let's just check that that is actually going to get called up so come back here and hit refresh and there we go so it's identified the correct action but there was no reply from action index and why was there not replied well action index doesn't reply it doesn't return anything yet so let's get it to return something and the thing it's going to return is a view so we'll say return this view and you can see here it's going to expect a class string for the view and then a template name and then a an array of parameters as an optional param as an optional argument so the name of the view class as a general rule it's good to have something that reflects where we are in the controller and the action so i'm going to call this demo/pad because that's the the add-on we're in :Note\Index so essentially it's a copy of the controller path here but it's going to point to a view the view itself is a class that is optionally defined if you don't define one it will use the standard view and we'll come back to that in a much later step but for now just use some sort of semantic naming that allows each of your actions to have a uniquely identified view like i've done here next we're going to specify a template for it to call and just as we did before i'm going to name space that with the add-on id that we're using so it's going to be demo_pad_ and let's call it index seeing as that's where we are we're just going to use this as a test page for now the third parameter for for view here would be an array of parameters to parse the template but we're going to ignore that for now because this is literally just a test page so let's come back to the control panel and go and create that template let's copy that over here so here we are in appearance templates add a template making sure it's public and master style again we're going to call it demo pad index and now i'm going to put in just some text to identify it and i'm actually going to hit save and exit here because i'm going to do all my editing in my code editor rather than messing around in the template editor in the XenForo web application because although it can do some relatively basic things like auto-completion of tags and things like that it's not a full-fledged html editor and why would we cause ourselves the suffering of using that when we can use a full-fledged data set like PhpStorm, so we'll save and exit that and sure enough there it is and it tells me the add-on that it belongs to and then you see that little chevron's appeared next to my public directory here and there is demo pad index so let's open him up and there is the text that is in the demo pad index let's just add a little more meat to that i'm going to give it an <xf:title> tag and we're going to call it demo pad index page and if you don't already know what the <xf:title> template syntax does it specifies the actual title tag for the page that we're going to be loading in and it also puts its value into the <h1> tag for that page by default now let's give it a bit of test content so i'll just have an xf dot block that will sort of do and let's go and save that now worth noting here that although i've saved out this template and the the file there has received that content that content has not been slurped up into the database where the system will use it at this point the system has no idea that we've done anything with that template but what's going to happen is when i ask the system to use that template it will check to see if the file has changed while we're in development mode and if the files change then it will slurp up the contents of that stick it in the database compile it and use it there so if i were to open demo pad index right now it still has the original content it doesn't have this stuff whereas if i come back in here and we know this is going to load the the correct the correct content because it's going to look for the return value for action index from the note controller so let's refresh that just to check that it will demo pad index page there's the <h1> and here's my hello there now at this point the the template has been slurped up into the database compiled and saved you might have noticed that that page refresh took slightly longer and that's because it was doing that template slurp and compile and you'll notice down in my query account here that it executed 14 queries to build this page but if i refresh that the queries go down to four because 10 of those queries were involved in the template compilation process so now the temp page reloads very very fast and only uses four queries whereas if i put something new in there and hit refresh then we're going to go back to 14 queries and it took much longer but refresh again and now we're back down there so having said all that if we go back into the demo pad index template here and hit refresh then we should see the content that we've been working on in the editor there so having one page built is all very well but what we need to do now is we need to build some more pages let's see how to get those built and then link them together so let's start off by creating an action for our second page so we're going to come back in here to the controller and do another public function which i'm going to misspell again and i'm going to call this what shall we call it action test just to be really adventurous and i'm going to take the view return from that action index dump it in there and just adapt it so that we can use it so now we've got a new action test and it's gonna return a view called demo pad note test and a template called demo pad test so let's head back into the template editor and having said just now that we're not going to use the template editor at all we do have to use it to actually add templates there's no way to add a template through the file system alone you do have to do it through the template editor so let's just grab hold of the name of that template from there and dump it in here and we'll do the same thing again save and exit and when we pop back over here we'll find that demo pad index has appeared so let's open that up and then put in the appropriate <xf:title> the second test page will do and then we'll use another one of those put a block row in there and add a bit of content that'll do and now what i should be able to do is if we go back to the controller just to review what we've done we've got action index so that will be returned if we call up the the route with no action and this one will only respond if we have the root namely notes slash test so let's go and grab it and see that it works so here we are in slash notes now let's go to slash notes test and you can see already that we've got the second test page and here we go so great now let's link between them and to do that we're going to start using the link builder i'm going to talk about this in a little more detail later on but for now we're just going to do a basic link between these two pages so let's start with the index page and let's make this a little more interesting so we'll surround that with where is the thing there we go we'll surround that with the <p> tag and then we'll have another <p> tag with a link in it let's just leave that as is for a minute and say open the test page and now we can talk about how to actually use the the link now we're going to use the what we call curly syntax or curly bracket syntax which is the sort of second part of XenForo template syntax after the <xf:tag> syntax so in here we're going to have a double curly brace and inside that link that's essentially a function call so we'll have some parentheses there and now we link to it by using the root and the action so in this case it is notes slash test and that's all we need at this point as i said we'll come back to the link builder later on to do more advanced linking but at this point that will link us to the test action from the notes root so let's go to the demo test pad as well and we'll have let's do something like that get rid of my typos and we'll go to link and this time we're just going to link to notes with no action because we're going to the index root and we'll just do that and let's let's go check that that works so we'll refresh this page and there's my link back to the index and that takes us to the index page notes that was a bit slow because it's recompiling this one will be fast because there's no compile to do i think or at least there we go now it's fast because the templates have done their job so here we go linking between them and you can see that up in the url bar there we're going between notes and notes slash test so that's the basics of linking so now that we know how to build a link it would be useful to employ that knowledge to provide a link from the the main system into our pad pages because right now they are completely isolated they're orphaned from the rest of the system if i were to go over and click on any link within the XenForo system then i've got no way of clicking back to my notepad pages because it's not linked anywhere so what we're going to do is we're going to create a navigation entry and i think we're just going to have a little link that says notes among these tabs up at the top here which is very straightforward to do so we'll just head over to the control panel here and then we'll go to setup and public navigation which controls that stuff up at the top there and you can see that the public navigation is laid out in this tree of content here so let's take a quick look at one of these items we've got an item called forums and you can see it's styled slightly differently to show that it's a top level item and it has children of new posts and forum lists and fine threads which has its own child entries of this stuff so let's just take a quick look at that here and you can see that by and large that reflects what you just saw in the control panel some of those items don't appear because they have conditionals attached to them but that's not something we need to worry about right now so we're going to add a new top level item and to do that we need to know what display order to give it now these tabs are arranged according to their display order so this one will have a higher display order than this one which has a higher display order than this one and this one etcetera so if we go and take a look at what those display orders are we actually print them out without having to click through into them so home has a display order of 100 forms 200 and then right down to members which has a display order of 600 so we need to give our entry a display order of at least 601 in order for it to appear last in that list so let's add a new item and we'll call it demo pad notes which you can see i've already had set up there and i'm going to call it notes and the parent navigation entry is going to be nothing and the display order is going to be something greater than 600 so i'm going to give it a display order of a thousand and the type is a basic link i'm not going to make its display conditional it just it's just always going to be there and we're going to use link building syntax as if we're in a template here so link and then we're going to link to notes and then close that off we can see that the add-on has already been pre-selected so let's hit save on that and here it is it appears at the bottom of the list so when i come back here and click on any link to to go somewhere then my notes item will appear and clicking on it will take me to the notes page so now we have a test page that links to a second test page which are linked from the top item so let's while we're here just go and add a child item to this because right now there is no change to the list of of sub navigation items so let's come in here and say we want to add navigation and i'm going to call it demo pad notes test because we're going to link to the second test page and i'll call it test page the parent entry this type is going to be notes and i'll give a display order of 10 so i've got options later on to put entries before and after it it's another basic link and this time we're going to use that but with slash test just as we did in the template this is all looking good we'll hit save on that and what we should see now when we click on to notes is oh i forgot something when we built the route i said that we'd go back and do some more advanced stuff and the the one thing that we haven't done that we need to do at this point is to say what the section context is for the route right now when we click on our notes pages it doesn't have a section context so it shows me the sort of unselected collection of navigation items so what i want to do is i want to say that i want the section context for the notes root to be this demo pad notes navigation item so we'll copy that come in and enter development go to roots and find my notes root and in section context i will paste that in there and hit save and that's all there is to it now when i click onto forums then the forums tab selects when i click into members then the members tab selects and when i click into notes the notes tab selects and i've got my test page sub navigation item if i'm somewhere else then the notes becomes a split link so i can access the menu and there we go
2021-05-10 18:13
