joomla/Component-Builder
joomla/Component-Builder
39
23
Fork 11
Code Issues 82 Pull Requests Projects 4 Wiki Activity
Page: 008 Advanced Fields
Pages
001 Hello World with Joomla Component Builder 002 Intro to JCB 003 Installation of JCB 004 General Planning 005 Field Types 006 Basic Fields 007 Admin Views 008 Advanced Fields 009 Adding Admin Views to a Component 010 Component Settings 011 Component Scripts 012 Component FTP and more 013 dynamicGet 014 Adding dynamicGet to a Site View 015 Adding Templates and Layouts to a Site View 016 Template Setup 017 Layout Setup 018 Custom Admin Views 019 Adding Site Views to a Component 020 Adding Custom Admin Views to a Component 021 Tweaking MySQL Demo Data 022 Global Settings of Component Builder 023 Adding a custom time field 024 How to integrate the Create User Helper Method in your Components 025 How to use email helper in your components 026 How to setup a store message method along side the email helper class 027 How to ensure that a field is not escaped when added to list views 028 How to change exported values and setup custom import options 029 How to overwrite the custom fields 030 How to filter a list field based on association with another field 031 Automatic import of custom code during compilation in JCB 032 JCB manual custom code implementation 033 Export Import of fully mapped components 034 How to add Custom Buttons in JCB to your component Admin Area 035 Translation Mananger in JCB explained 036 Setting Site View Permission 037 Auto create SQL updates for Componets in JCB 038 Setup Site Edit View in JCB 039 Automated backup system in JCB 040 Adding Helper Structures to any JCB component 041 Upgrade to JCB v2.5.8 and using the new Admin View and Admin Fields 042 How to setup tabs after upgrade to v2.5.8 in JCB 043 Major Release of JCB v2.6.0 044 Hello World Component with Joomla Component Builder Creator Extended 045 Adding your own rule validation to a field in JCB 046 General overview of how community snippets work 047 Tutorial on forking JCB snippets so you can share your snippets with the rest of the Community 048 Tutorial on making a pull request at Joomla Component Builder Snippets 049 The New Library Manager Area 050 Easy Translation via excel 051 Dynamic Router Implementation Explained 052 Automated database updates in Joomla during development of a component 053 Quick Subform Demonstration 054 VDM Package Import Option 055 Dynamic File and Folder Inclusion concept 056 How to use the file field type to upload a file in JCB 057 Drag and Drop Upload functionality in JCB 058 The Quick Hello Word with JCB 059 Adding none database fields to an admin view 060 The custom dashboard option in JCB 061 Add or Remove Prefix to Component Name in Joomla Menu 062 Add your own JCB packages to the JCB Communty Directory 063 Proposed Collaborative Workflow in JCB 064 How to install jcb packages 065 JAB18 Using Joomla Component Builder 066 The new fields Area to make things easier 067 Adding Language String to your Component and get the Language Placeholder for dynamic use 068 Library Manager Anticipated Functionality 069 Join Fields in the admin list view with field relations 070 How to change the License Template in JCB 071 Reuse Custom Code 072 Setup Local Development Environment with Bitnami 073 JCB Fields Type Extended 074 How to add Joomla Custom Fields 075 Expand Custom Field Type Beyond The Default 076 A Quick Demonstration to Load a List of Items in a Site View 077 Run Expansion Explained 078 How to Add a Form to a Site View 079 Update the Site Form Field via URL Parameter 080 How to Add More Helper Methods to Your Components Helper Class 081 Easy Validation Rules for Fields in JCB 082 New Placeholders Feature 083 Manage a Components Global Config Option Field in Relation With Menu Params 084 Default Database Values can be set per Field Type Beta Testing Component Settings Develop a Joomla Component Guide to use the Component Builder Developing with Joomla Component Builder Home PHP Settings TIPS: Custom Code Using the JCB Demo Component While Building Your Local Development System
32 008 Advanced Fields
Amigo edited this page 2019-08-15 17:33:07 +02:00
Table of Contents

ADVANCED FIELDS

00:00:00 (Click on these time links to see Youtube video)

There are a few advanced field types. The most advanced is one called custom field type. Sorting by custom fields, you will see that we have quite a few custom fields in place.

Setting Up A Folder

00:00:38

Let us look at two of these. One is the local file list, the other one is 'sermon'. We'll look at the local first. You will see that the whole 'XML field definition' column is PHP. I'm creating a view that is taking information from the global settings of your component so that there needs to be a field with a name 'localfolder' in your global settings. When we get to the components we'll look at setting up global settings. If it doesn't have a setting it falls back onto the image which is in the 'JPATH ROOT'. For your component, this will be replaced with your component name. It places it into a local folder. 00:01:36

Now I start the options array, which you are going to return. Select 'Please add files'. If there aren't files it will say 'Please add files' too, and give the local folder name. If there are files, we are going to update them at 'JFolder'. First, we bring in the file system classes from Joomla, then we check whether that folder exists. If it doesn't exist we create it in the field type. Once it's created and it exists, it doesn't go in there; it grabs all the files from the folder and place it into files and starts up an array where it loops the files and places it into options. 00:02:40 By doing that we are adding the file names to our options array. Returning the options array. You can add your own custom PHP scripting when you extend a list field. We are extending a list field. It is going to be a drop-down list of all the files in that specific folder; either images or the folder that was set globally in the local folder.

There is a field type called 'file list'. I didn't use file list because file list has a static directory to where you need to add the files to view them. 00:03:44 We want it to rename the folder for the files, for the media, etc. then have it update itself automatically. So we created a custom field where we extended the list type. We chose a custom field, and then extended the list type. (We don't want it to add 'new button' because it won't work.) We are allowing them to select multiple. Since we are using multiple, we need to make sure that we are storing it as a 'JSON'. That is when you have 'multiple' or 'arrays', or any kind of arrays in a value that needs to be stored as a 'JSON'. 00:04:48 The component builder itself will check if the multiple selections are true and automatically store it in a 'JSON' object even if you forgot to select 'JSON'.

How to Create a Sermon Preacher Custom Field

00:05:32

It is a preacher custom field. It will show a list of preachers but will display the preachers that are set up in the preacher list view. Open that 'Sermon Preacher.' The convention is that you should call the type, preachers, that is the list view name. You should use the same as the editing name which is 'preacher' without the 's'. If you go back to your admin views you would use this name as the name of the field, but you have to use that name as the type because you are now creating a custom type. The logic behind it is that while it shows a list of preachers, you might have selected just one preacher.

You can use any label you like, whatever is descriptive enough for your user to understand. There is a place for adding a description. In 'XLM field definition' we set multiple to false. They should be able to only select one preacher at a time. At 'Default 0' all are left to their default values. 00:06:56

Jform in Component Builder

00:07:02

'Extending list' is the most common custom field that we have. If you want to receive a list of custom fields that is available, you can go up here to 'extend' and see the list, radio, and checkboxes that are available. User is also a user option to extend users. If you want to see what is available, look at that name 'Jformfield' and go to Component Builder. Go to the back end of Component Builder. (See video.) Go to the compiler, then to Joomla 3, which is the current version we are targeting. Search for that Jform. 00:08:00 Those available to extend are user, Jform field, JForm field user, Jform field radio, Jform field list, and Jform field checkboxes. This means that if there is a form field you want to extend that doesn't exist in our advanced seminar, you will be shown how to add your own form fields here. There would be two places you need to change. One of them would be adding the field and update it accordingly; the other one would be adding it in the code at some places and in a JSON file called settings there. These are some of the things we will deal with in the advanced adaptation of component builder. 00:09:04

Extending List in Custom Field

00:09:16

Getting back to extending a list field: you simply add the list. There are a few conventions. One of them is that if you are going to be targeting 'Preachers' for example, you will be using the preacher table as the table being targeted. The question to ask is where the data going to be found. This table needs to be added. (See video.) The reason why we have this 'component' here is that it's a placeholder which component builder will replace with the component's code name once it's built. 00:10:08 We added this feature because sometimes we want to rename components. If you had statically added the actual component name there, you have to update that name in every field and view.

To explain what the system is doing, go to components, open 'Sermon Distributor,' take the name in code, like that 'sermondistributor', copy, and you'll see that it is a lowercase 'c.' If it had been an uppercase l it would mean that you'd have to place the component's name with an uppercase as well. 00:11:12 The system is replacing these place holders with the actual component name on the fly. Using the placeholders saves you time in the long run from making changes everywhere if you make a change to a component's name. Which is quite normal to do. Often you start with the component and think of calling it something and later realize that the name is been used in the Joomla repository, and you need to choose another name. To do that is going to affect the whole component, so we added this placeholder structure which should make the data easier.

In all the custom coding that you're adding where you need to use the components name, you can use the tag format of replacement. 00:12:16 In some areas you would need to use brackets. Most of the time it works either way. The best way to ensure that it works is to try it with a hashtag first; if it didn't replace it in the code, the angle brackets need to be used. In this case, we are using these ### characters. Again, the view is the single variable of the view. If we close and go to the view which would be preacher, all lowercase is what you would be adding here. Make sure that it's always lowercase. 00:13:20

The list view (or the views plural) would be the added value there. All lowercase too. The value field is the field that the user will see. It is visible in the UI user interface. The key field is the value that will be stored in the database. This field relate to this table (#-###component###-preacher). Inside this table, which field do you want the user to see? The name of the preacher. Inside this table, which field would you want to store in the other database? We are going to store it wherever the field is being used. That would be the ID and the column name in that database of that view where this field will be used. 00:14:24 It will be called 'preacher.' To show that in the database itself. Open it. (See video.) Go to sermons, click 'new,' and you will see a place for 'preacher.' If you were to look with firebug at it, you'd see that it is the name is 'preacher.' (Remember we spoke about this Jform_ as the ID.) It's simply the preacher field which is being stored directly in the database in the preacher column of the table. 00:15:28 It's stored as INT 11 and we say that it is a key. We can target it. If we look at indexes, we'll see that it had added it as a key.

Custom PHP layout in Field Definition

00:15:59

All of that is done in the database structure and in this area. (See video.) Here you can add your own custom PHP. I'm using 19, 18, 17, etc so that it's creating line breaks and spacing and tabs for me dynamically. I could have placed them all under PHP one, without these quotation marks. 00:16:32 We wrap around them as we did with the file folder list view example we did previously.

(Just a note: inside of this code, you can't use quotation marks; you need to use single quotes, even if you try to do an escape. It will not behave as you might expect.)

Build Code for Sermon Preacher

00:16:51

These place holders reflect back to these 'key_field_id' values. (See video.) Basically, 'a.###ID###' will be written here and the text value which is the field value is going to be called 'a.###name###' and then '###ID###' and '###code_text###'. 00:17:36 This code is built up by the view that we are in, as well as by the text, so it would read sermon preacher in the code.

To show you how it looks when it is being built. Open jformfieldlist. That is what it starts with, replacing this place holder with your code. It replaces all these features up here as well. 00:18:30 Everywhere you see '###component###', it will be updated through component builder. Everything here will be replaced with your licensing tags. Let's look at the finished product. 'Sermon' is placed on the module field and there is 'preachers'. 00:18:57 If you open it you'd see that it added preacher there, and the input added. If you trip that switch, like we have explained, to show the line numbers in your component. It shows you in what file. 00:19:15 These files are found if you go to Component Builder, helpers compiler. These are the files that are being used to compile your component.

Generate a New Button

00:19:39

We are trying to build a component, not as yet to extend component builder itself. Here you can see where in the code it is building, compiling, and putting this together. 00:19:59 This is used for the button. (See video.) This is to generate a new button. When you click on new, this is the button. This area is generating the button. This controls whether the button should show up or not. 00:20:21 If it is to be set at all, this is what generates the button. We said that the 'get options' will show the name and 'ID'. Going back to our structure here, we dynamically replace these (###ID###,###name###) with 'view preachers'. The reason for this is that it's done a few times. 00:20:48 We'll say that you only need to update these values and it would get updated all over in the bottom of the code. It makes it easier to change your custom fields. A field called preacher name was built. Which again used 'preacher_name' as an object value. 00:21:17 Because it retrieves the object from the database and it seems as if the object exists, it reiterates and builds up option list which is returned to use in the dropdown. It dynamically generates your list. So component builder through this infrastructure compiles all of the code for you and puts it in the right file in the right place. 00:21:37

Once you have built a component and know where you have made those changes in component builder you can look at the files if you know how to build a Joomla website. I used the same conventions as decor in regards to the implementation of the files. 00:22:07

Dropbox Custom List Example

00:22:31

We will now look at Dropbox manual file list, which is more advanced. We are dealing here with a file that is stored. I created a function in my component global helper function called 'getDropboxlinks'. It wants manual links and passes a specific variable '2'. 00:23:02 It would return some links which it will check to see if it exists. It will check the array and the values in it. If it does, it backs it into the options and gives it over to the options array, to the list. 00:23:24

Component Helper Class

00:23:32

This part means that you can add a helper static method call in your custom field types. These two symbols mean that it is a static method being called from a class. If you know the Joomla API and how to work with builder component, you will know that you can add a component helper class to any component. 00:24:07 If I go to sermon distributor, the component helper class is always located in the helper folder of the admin as well as the site view. The admin is in the back end in which is administrative components. 00:24:28 There you'd see the component and its helper folder. In the front end, you have the same convention, component, and sermon distributor. There is a helper structure. Here is some of the script of sermon distributor structures through its helper structure. There is the helper file for the front. Here is helper file for the back. (See video.) 00:24:49

Adding Methods to the Helper Files

00:25:10

If you want to know what the custom helpers are that we ship with all components, you can open component builder. Go to the compiler and Joomla 3 then look for the helper file in the site helper file. 00:25:30 If you open it you'll see many helper methods. With a lot of place holders, we customize for each component that targets that component. You'd see a Json to string method here to 'getvars'. (See video.) There's a 'getvar' singular. This is getting one variable from the database so you don't need to rewrite the whole string to get one variable. 00:25:55 You can look at how this works and use it to get a variable from the database. We also have 'ispublished' to check if a specific object is published. 00:26:14 I wrote these functions. (See video.) 00:26:40 If you do save string we change every number in the string to text so that you can be sure that whatever you get back from save string doesn't have numbers in it. 00:26:58 In this way we are ensuring that it is always text. It's is quite necessary, especially if you don't know if the first character might be a number.

Strings

00:27:27

There are many custom methods that we ship with all components that are developed. If you were to open 'sermon distributors', 'helper class', you'd see that these helper classes are all showing up. (See video.) 00:28:00 If you have a better way of doing this, please go on the forums at Github and bring it to my attention. I recently tried to improve on this checkstring by doing adding {}. The plan was that I could dump this part(&& strlen($string)>) and save on the query. 00:28:22 But for some reason it started causing problems and strings were being returned as non-strings. 00:28:41 So I went back to the old school way of doing it. We first want to ensure that this value is set. If it is a string, then it has a length. Something can be a string and yet not have a length. 00:29:04

Back to the UI. That is where I get these values where it says 'getDropboxlinks.' (See video.) 00:29:29 We see that it has '$return' set to false. It means that if it should return the manual values, then it will only return the value manual links. Since I've set it to 2, it will return all of those links because you can target that it should return one specific sermons link. 00:29:52 This method is dynamic. That is all I am calling in this advanced field type which is called 'custom field' and it gives me an array of all the links which I have loaded. 00:30:15 It is an advanced implementation of these custom fields. 00:30:37 With that list concept you can nearly do anything, even grab a bunch of website names from somewhere. You can put any PHP in there and build a list which can be used to save to the database.

Custom User

00:31:02

There's also a function called custom user. In the custom user, you don't need to set or change anything here. (See video.) 00:31:25 All of these should just work. The only part that you want to consider removing would be the PHP here. (See video.) What this does is it limits the user list to only a certain group. 00:31:47 It means that you need to set up a global value in your component field. In the Global, as mentioned previously, if you click on 'options', it opens a place where you need to set 'global'. 00:32:07 These are all global values. This is an area for global values. You can get hold of these global values through the component helper 'getparams' with a component name and get. (###text###) You would place the field name. 00:32:28 That's how you can get a value from your global settings. I'm getting a specific groups value and placing it in here. Then I return that group. That is what this is doing. (See video.) Those two sections are independent. This one is the one that helps you set to return a specific group. 00:32:52

  • The Exclude Feature

This part helps you set any users you want to exclude. This specific feature here ensures that only one record per user is set. (See video.) Let's say a user had already been added to a previous record, then that user should not show up again. 00:33:18 The user should be removed from the list. This is what this PHP is doing. It looks to the current view and checks if there are users; it gets their ID's and sets them up in their unique manner, then returns them. 00:33:36 If you are building something which is supposed to have student details, for example, you don't want a student to have more than one entry in that table; you want every student to just have one. 00:33:58

Now to show that to you in the code. Let's go to another project that I am working on: 'Learning Manager and Models.' There are fields called studentusers and studentuser. 00:34:27 There are two ways to do this. One is not allowing more than one user to have an entry; the other is excluding users that have already been used. That means if a user has been selected, the other one returns null. 00:34:52 In other words, it will always show all users. The way to have it set to null would be to remove this part of the code. (See video.) Then Component Builder will automatically set this 'return null' value to null. When it gets to the group part the principle is the same. 00:35:19 If you don't want it to show a specific group, you can set it to null. All you need to do is remove that part of the code and it will target a specific group or remove specific users. 00:35:48 For example: If you want to remove users that belongs to another table or structure, all the PHP that you need to write can be placed on the 'type_phpx'. 00:36:11 So all your PHP can be placed in here for excluding. (See video.) 00:36:33 This 'type_php_1' will be used for the groups. It says Getexcluded method and PHP for the getgroup method and in the code which is stored under 'fields' and 'models' where can be seen what it does. You can do things and then look at what Component Builder build. 00:36:59 You can go to any view and see how it works. 00:37:24 You will use that(preacher).

Here is a select list; here you have the values. That's the IDs and the actual name of the speaker. This is how it should display the data. Component Builder sets up the XML structure that Joomla uses to build this. 00:37:53 Joomla is building this whole structure for you. It is done through these XML input values that you are adding here. 00:38:08

  • No Underscores or Spaces

Something to remember here: the type names may not have underscores or any spaces in them. Anything that isn't translatable usually needs to be without spaces. 00:38:35 You must also remove the underscore. You can use uppercase but it will become lowercase anyway. 00:38:57 This works because it isn't only used in the file database but also in the name convention and everywhere this file type is. You can see in here that the file type is called studentusers and even the file is called studentusers. 00:39:21 Specific type name is used everywhere.

You can update these fields. Mostly they are fields that are related to all the other fields. 00:40:07 This one specifically says extends user. It shows you how it's going to extend it. If you removed all the PHP, the field like this will show all users every time. 00:40:28

Repeatable Custom Fields

00:40:38

Repeatable fields aren't that difficult but you need to understand how it's structured. First, you need to create the fields that you want to repeat inside repeatable fields. 00:40:55 This is a repeatable field. (See video.) If you know a little XML and worked with repeatable fields, you'd see that the fields are being repeated inside of the repeatable field. 00:41:23 Repeatable field is a field type that has other fields inside of it.

You don't need to write any of this. It's very simple to structure a repeatable field. 00:41:47 First you create the fields that you want to repeat. You can't use repeatable fields in repeatable fields, but you can use custom advanced fields in repeatable fields.

  • Cause and Risks

Here is a field type called 'cause and risks'. (See video.) If you know Joomla you'd know there is no such field type. That means that this is a custom field. If you were to go to fields, you'd see a field called 'cause and risks'. 00:42:16 It gets its information from this database table. This is another component that I've done with Component Builder. 00:42:35 It is displaying that data, making some model changes and adding some style to the data.

You're able to add an advance custom field inside of a repeatable field. However, for example, you need to have the field ID and you have to order it according to the order you want it displayed in the line where you do repeatable fields. 00:43:17 Here you will see that there a number of fields in one row. (See video.) If I click next they all appear again etc. 00:43:43 That's what repeatable fields is about.

Here I developed this specific pop-up repeatable structure. (See video.) Here is a list of all the repeatable fields that I've already built. There are three pages of 20. 00:44:08 If we were to click on add fields for views, this is the repeatable field for adding fields for views.

Joomla Icons

00:44:41

If we go back to the view, you'd see that it says 'add.' I'm adding an ID in a class to it. A description would appear if we were to hover over it. It has a little setup field for this view which is the description. 00:44:59 The label is fields; the icon is what is shown in the button, a list. 00:45:17 All those custom Joomla icons can be used. To know these icons you should go to URL Docs.joomla.org/J3.x:Joomla_Standard_Icomoon_ fonts. You'll get to Available Icomoon Icons. 00:45:41

These are all the available icons. You use contract-2 and checkmark-circle. If I wanted to checkmark-circle, I'd copy checkmark-circle and change the icon to checkmark-circle. 00:46:02 That's how you change the icon.

These are simply the IDs of the fields I want inside of the repeatable field. 00:46:22 You'd find the IDs next to the fields on the right if you close repeatable fields. You'd create the fields that you want to use in the repeatable field and get a list of those ID's jotted down somewhere. 00:46:51 Add them in the order that you want them to be added. Inside of your repeatable field paste it in the area of the fields with a comma separating them. Then component builder will dynamically construct the whole structure for you and add it to your component. 00:47:11

Radio Buttons: A Note

00:47:39

A note: you need to remove the class of the radio buttons you use in the repeatable fields. It can't be a button; it must be a dot. Unfortunately, they don't make it possible to load the button. What's the difference? 00:47:59 CSS YES/NO is the button version of a radio button. Searchable Yes/No is the dot version of the radio button. It doesn't look like a button. 00:48:20 What makes it a button? It is the class that is being added to the field. You need to remove the class values from your radio button if it's going to be used in the repeatable field. 00:48:38 If you forgot to do that and compile your component you'll see that the radio button is not working if you look at the repeatable field, but that it messed up.

That was looking at advanced fields called custom fields, custom user fields, as well as repeatable fields. 00:49:04 These were the advanced field types that there are.