Table of Contents

JOIN FIELDS IN THE ADMIN LIST VIEW WITH FIELD RELATIONS

Feature Effects How JCB Builds
What The Feature Is All About?
Demonstration - New Feature - Field Relations
Area Column - Three Places - Model(before modelling), Model(after modelling), View
Looking In The Code
Some Changes Targeting Model Area - Joint Type - Concatenation With Glue Option
More Changes - Instead Of Using Default Glue Option Do Code Option
Only Target The Name List Field Once
Create Preacher Without Email Address
Targeting The View
Demonstration
Going To The Code(see video)
Preacher Field - Two Fields - Name And Description
Demonstration - Combining Preacher With Name Row

JOIN FIELDS IN THE ADMIN LIST VIEW WITH FIELD RELATIONS

Feature Effects How JCB Builds

Well, I am happy to announce that we have added a very long-awaited feature to JCB. You will need to upgrade to version 2.8 to have this feature. This feature though does effect how JCB builds the Admin View, ListView. That means these areas where you got lists of items. 00:00:33 If you have custom scripting in your component in these areas when you install or upgrade to version 2, you would experience that your custom scripting does not get added correctly. We will still add it, it will still be added to the document. But you have to go and move it into the correct place and uncomment it and do the 00:01:01 replacement of the code, add those diamonds to notify JCB to update the placement. Just a heads up, because the list views are improved the way it is being built. These extra changes to the code, snippets changes, the fingerprints and all that.

What The Feature Is All About?

What the new feature is all about, is taking specific values like maybe this value(Look) and that value(Looks) and to combine them into one value into one column and yet have the option of still being able to filter with those values. We have this component Sermon Distributor and I am planning to take the Preachers List View, 00:01:59 you will see that it shows the name and a short description or whatever description you have added. I want to have it also show if there is an email address. If this email address is filled in, then it should show the email address or if it does not find an email address but it finds a Web address it should show the web address. It should show either one or the other. It must be connected next to the name. I think we will use that as our demonstration of this feature.

Demonstration - New Feature - Field Relations

Let's go back to Component Builder and then we would go to the Admin Views. If you have not done it yet, there would not be an icon showing up anywhere, but once you have done it, there will be one. Go to the Preachers Admin View and to the one you want to change. 00:03:01 Under the fields area you will see that there is a new area called Admin fields relations. At the bottom, you will see Field Relations. That is the new feature. You could either click 'Create admin fields relations for this admin view' 00:03:27 or you can click 'Create', both of them will achieve the same and take you to the same place. I am going to click on 'Create admin fields relations for this admin view'. Then you are in the New Admin Fields Relations Builder.

Area Column - Three Places - Model(before modelling), Model(after modelling), View

You could click on adding an Admin Fields and we are going to use the name and join that up with the email and with the web URL. We will see that there is this 'Area' column. The Area column can target three places, before modeling the value, after modelling the value, and the view. 00:04:12 If you know what a model is, that means the area where you are still working with the code. Whereas in the view you must think of already having an HTML trunk that represents that field.

Looking In The Code

If I could show you that more directly in the code. First looking at the folder structure, you will see I am in administrator, components, sermon distributor, here are the views and the models. Go to the model of the preachers the plural one, because we are going to the list view. You'll see it has items. At the moment there is nothing being modeled. Modeled usually would imply 00:05:01 if it is a json object, and it needs to be taken from json to an array. Or if it's an encrypted value and needs to be encrypted. Those kinds of things. Whether you want to work with the value before that happens or after that has happened. If you want to work with the actual item where it's still an integer or a string. Then you'd target the model. If you want to target the view, 00:05:37 which in this case if we go to preachers and the body, you will see that everything from here up to here, is representing the ID. Everything from here up to here 00:05:58 is a presenting the name(see video). If you want to target this portion, it still gets generated, then you would target the view because then JCB will still build this whole block for you. Basically this block and you can move this block around and join it with the other block for the other field as you like. That could be that you can have two links. 00:06:27 Yes, all kinds of interesting things can happen. My best advice is to try it out, take it for a spin. Make some changes, compile it, install it. See what has changed, go to the areas which were either the view or the model. See the code that was generated based on your selection.

Some Changes Targeting Model Area - Joint Type - Concatenation With Glue Option

We are going to make multiple changes and show you what will happen. Save you some time, and understand what's happening. The first area I'm going to target is the model area. Then it has a Joint Type which is either a concatenation with a 'Glue' option. The 'Glue' option is: what do you want to be placed between the values? You could say no I want them to be completely crank up against each other like that (Glue/Code). It will still add a little space in. 00:07:30 You can say no I want a little Arrow-> between them. It is a value you want to place between these two values. I'm going to leave it as a comma for now. Save and close. Save and close the view. You will see there is a new icon, we can click and directly go edit the relation. 00:08:01 A new icon is added. If we go to the compiler, we will be able to compile this and see it in action. Go compile sermon distributor, install it. First thing is, let's open Sermon Distributor and let's go to the Preacher's table and see how it looks in the interface. We see 00:08:30 it is adding both of them, adding the email, as well as the URL. Because it's exceeding a specific length, it is escaping it and we have this little Pop-up come up. There is that comma we added as a concatenation between the values. That is what we expected.

More Changes - Instead Of Using Default Glue Option Do Code Option

Let's go back and make some changes. Well, let me first show you the code that was built. We were targeting the model, it adds this(See Video) as a glue to glue these values together. Concatenating them. Yes, that was the model. This specific view does not have any modeling it does to the values. Even if I would to say: select after, it would not necessarily change anything. 00:09:32 Let's make another change. Instead of using the default 'Glue' option, we want to do a code option. You'll see the JCB cranks out to give you the freedom to write code. We are using the IDs of the fields 00:09:58 in curly braces{} because many reasons, more or less it boils down to the fact that it is difficult to know exactly what the field names are going to be at this point for every type of field that is there. Working with the ID saves us a lot of effort. 00:10:22 But since it is difficult to know which field is which ID, we had this little comment to give you a heads up. This value(280) is the website, this one (1222) is the email(see video). I would suggest if you are sure of what is what to take the comment out because otherwise it will be added to the code. At this stage, we know that what this is saying, is what we saw in the code. It is almost exactly the same, except that it is using numbers. We can do some little PHP. 00:11:00 We can say something like this: $preachersDetails. We are checking if this is not empty. Then we use that, which is the email. Otherwise, we fall back onto the URL. When the URL is empty it means that there will be an empty string. Maybe it is not that ideal either. Let's make it a little bit more advanced. It is saying if there is an email, use the email otherwise check if there is a URL. 00:11:32 No, if there is, sure then add it, if not then add nothing. It stays without the comma and everything. There we have a little adaptation there. So just make sure that this Convention is kept, ($item->(1222) the curly braces with the ID and then the closing curly brace. This will then be updated with the actual name of the field and so you can do full PHP coding in this area and 00:12:02 it will be implemented. You could also pass the value to a function which then passes it back to the value. This is in the model. This is before modeling and after modeling. That is a good thing that happened. Every time you change anything it's going to update the code. Sometimes it is expected that these two values might look different at this stage it doesn't. It is a JavaScript that fires on 00:12:37 changing of any of these fields. I have to type all that over. The best idea if you want to make changes, first copy the value then you can make changes. See what happens. Then as you decided what you want to do, you can paste it back in. 00:13:04 There we have it. If it does not behave right just change it a few times. We will still tweak the JavaScript to make sure that it is working exactly 100 %. So this is sort of beta phase but it works and functions as it should. I am still ironing out some JavaScript.

Only Target The Name List Field Once

Another thing. You can only target the name list field once. You cannot add it a second time like this(see video) and say here we are going to do it again. Using maybe some other values to also target it in some way. 00:13:52 You cannot do that. Only one of them will get implemented. The other one will be dropped. It's a limitation I know. Believe me, this feature as it is now is already stunning and able to achieve quite impressive results. Here we have it, we have adapted it. It will only show an email or a web address if there is one set. If there is none set, it will not show any. That is the expected result. Let's save this and see it in action. 00:14:31 We will compile it and install. There we have it. The preacher showing up with an email address.

Create Preacher Without Email Address

Let's create one without an email address. We created one with no email address. If you will see there's none. Let's add a web address. Let's close again. There is nothing, not even a comma, but as you will see this is a link. The whole thing is a link. That might not be exactly what you want. Let's add a web address. Save and close. Because your web address was a little bit too long, it created a pop-up. 00:15:26 All that can be changed. Let me do something else. Let's use a shorter address. Save and close. That looks more acceptable. It detects whether there's an email or a web address. If there's none it shows none. That was with this new combine feature.

Targeting The View

Let's do something even more interesting. Again we go and open Preacher area clicking the icon underneath Preacher. This is a shortcut. Instead of targeting the model, we are going to target the View. This is where it really gets interesting. Because this little place holder called field=199 is a portion of code as I explained initially in the beginning. Where we are saying; 00:16:30 instead of targeting the actual value database value, you are targeting the produced code which JCB builds; the HTML block for that specific field. I would also encourage you removing the comment, this comment '<!-[199]=> Name;[1222]=>Email(not required);[280]=>Website ->' that shows you the name, the email and the web address. 00:16:57 I would also encourage you to once you have seen it just remove it. We might at a later stage take the comment and add it underneath the box that it is clearly nowhere in the way. It is for you to know that this portion is for the email and the website address. Again I want to add a little bit dynamic Script. I need to keep in mind that I'm in HTML. 00:17:31 If I wanted to add PHP I will need to do the correct PHP tags and all the rest of it. That means you can target the item value. You can remove this '[field=199]br/[field=1222]br/[field=280]' and work with the item value. But this [field=199] little placeholder will produce the whole 00:18:03 block of code. If it's going to be a dynamic link or something like that. It'll produce all of that for you if it's a custom field that links to another View. Then all of that can still be produced in this dynamic placeholder [field=1222]. But you can remove all of this and you can have it echo out anything which you just have to code.

Demonstration

I think best to demonstrate is, first used the Concatenation option which we can put a br/ between the values. Save and close. Compile, install. We will refresh this area. We will see that 'Leonard Ravenhill' value is a link, but the other two are text. That's exactly what we wanted to achieve.

Going To The Code(see video)

Going into the code, we open the body. You will see the JCB added the br/. There is a br/, there's a br/. There is the portion '<?php echo $this->escape($item->email); ?>' of code that JCB build. It really builds all of this. It's still built a link to the preacher. It's still built this as well. If this '<?php echo $this->escape($item->email); ?>' was going to be a link to another view, it will produce that code. Checking the permissions and everything. Which is really what makes 00:19:43 The implementation of This area quite exciting. Because it still takes care of the hard work of producing the code needed to display the value. If you pick up any behaviors in this new feature that is unexpected, please give us a heads up on Github and open an issue. We will try and address it as quick as we can. This is the new feature of combining admin view values 00:20:19 in a very easy way. It could have been done previously with some custom scripting, but this helps you and I'm sure it makes it easy for you to just select the field you want to target. You first need to add the fields that you are already going to show in the list view and then select the field you want to join it. I expected that you will understand that, but I realize I must mention that separate.

Preacher Field - Two Fields - Name And Description

If we go into the Preacher fields area, you'll see we have two fields the Name(text), shown in the list, and the Description shown in list. We don't make any changes. We don't say that the email and then the website must also show in the list view. Only the fields that are not showing in the list view, show in the relationship view as Joint options. That's a heads up. What is exciting though, you can do a filter or a search on these fields that are not going to be placed but you know you are later going to select them as relationships. 00:21:47 JCB will end up creating the filter and make it searchable. Even if it's a link to another page you can click this to be a link and it will generate the link. I think it is amazing knowing that it's going to set all the permissions in place and everything else. Maybe I should demonstrate that quickly.

Demonstration - Combining Preacher With Name Row

In the Sermons area, we will see that we have a Preacher table and a Name table. We have these two links 'Ten shekels and a shirt and Paris Reidhead', this 'Paris Reidhead' will open the Preacher, the same as opening it from the Preacher list view and then this 'Ten shekels and a shirt' is going to open the Sermon. This is going to be easy because 00:22:45 we can decide we have so many rows, let's combine the Preacher with the Name row. Yet we want to retain the link as it is working. We want to retain the option to filter by the Preacher. Let's show you how easy it is to do that. We'll go to the Sermons list View or admin view and then again to the fields, click on create fields relations, before we are going to do that, 00:23:20 I first need to remove the Preacher from the list. We are first going to go to where we selected the fields. That needs to be linked to the admin list view. The one we want to remove is the Preacher value. 00:23:42 Sermon Preacher. We are going to say, No, don't add it. When you are going to do that, it is going to wipe out all the links that usually should not be selected if it's not a list view. But since we still want it to be a link, we still want it to be a filter, we are going to leave those checked and click save and close. Going back to Editing The Admin View page, going to Fields. We'll see that 00:24:10 the Sermon Preacher is no longer going to show in the list view. But it's still going to be a filter and a link. If you compile, it won't show up at all. You will still need to go and select the Relations area. Click on New. Then select Name in List Field. 00:24:33 In Join Field you would need to select the Sermon Preacher, and then View in Area row, we could either say we want to do this ourselves, or 00:24:50 we could use 'Glue' which in this case I'm going to use a space just an empty space, and save and close. Then compile, install. Refresh the Sermon page we will see that there are 00:25:21 two links. The one is to open Sermon and the other one is opening the Preacher. If we click on it, it still behaves as before. The Preacher opens, we close it again. We are back and we still have the Preacher filter at the bottom of our page as we had it before. 00:25:48 This is really great! We can also then open 'Ten shekels and a shirt and Paris Reidhead'. All is working as expected.

Now as easy as it was to combine these two values into one column while still retaining the links and everything surrounding this value having it dynamically get the Name. 00:26:16 Because in the table it's the ID only. Showing it here means it's remapped in the database. We open the sermons model and we scroll down. We'll see in the getListQuery it still maps the preacher table in, builds the connection on the ID, and the preacher. It still selects 00:26:49 the preacher name. Then going to the view of that sermons. We will see if you scroll down, it has produced this portion of code for the preacher's name(see video). This portion of code 00:27:14 for the sermon name. It still does all the producing of the HTML code and all the permissional checking whether does this user has the edit permission to change this value of the specific preacher. 00:27:37 Yet it's showing the preacher name as the linking up in the database was done. It's quite exciting. I really hope that you would find it as useful as I am. Like I said if you discover anything not to work as expected, please do contact me and on GitHub open up an issue. We will take it from there.