Customer basket fields in Miva Merchant are very powerful developer tool. They allow you to save data, any data you want associated with the Shopper or the Basket in this case. Anytime a visitor comes to your Miva Merchant store they automatically get assigned a basket id. This is their unique identifier. With Custom Basket Fields, you can save data associated with that Basket ID. The best comparison is to think of a Custom Basket Field as a cookie. Similar to how you would use cookies to save data associated with a particular customer on a session basis, custom basket fields are the exact same concept; but instead of saving the data to the browser, it actually saves it to Miva’s database. The key thing to remember with Custom Basket Fields is that as soon as the basket expires, so does this data. Miva will automatically delete any custom basket fields that are associated with a basket when that basket expires. This is actually really nice because it lets you not have to worry about having to… You’re going to use the item tag and the name is Custom Fields. That's always going to be the same. The parameter is going to be write_basket or read_basket, depending on if you want to read or write. So here's an example, I'm a create a custom basket field and this first parameter is the code I want to give to this field. This is essentially, my identifier. So I'm going to call it “customer _ip.” The second parameter is the value I want to save into this field. So I’m going to use a system variable for the customers ip address “remote_addr” to save the customers ip address into a custom basket field. Now, there is one key difference between say custom basket fields, custom product fields and custom category fields - it’s that Custom Product Field first needs to be defined in the admin under Utilities. This has to be done ahead of time. But Custom Basket Fields are more flexible. They get created on the fly. So this code here that I'm creating doesn't exist anywhere in Miva. I'm just defining it using this tag here. This can be anything you want. There's no restrictions. Here I'm using underscores. It can also be dash separated or even space separated. The other comment would be to keep your naming convention consistent. You don't want to use underscores for some, dashes for others and spaces for others. It's going to make it complicated when you need to remember the names of the custom basket fields to read them back in and display their values.
So let’s take this coat and bring it over to Miva and see what happens. So here I am, back to the Miva Merchant Admin and I'm going to go to the Storefront Page and in the Content Section here I'm going to paste in this code. Now if you remember the last video, I don't need to do any assignments for the Custom Fields. They work on any page with Miva because the custom field item is an extension of the store item which is assigned to all pages by default. So I’m going to update this then come back to the front end here and hit “Refresh.” Now you’ll see that nothing happened and that's ok. When you write a Custom Basket Field there's nothing that gets output to the page. There's no success message and that’s exactly what we want. We want the data to be saved in the database without any message to the customer or the Shopper. The next question is how do we know this actually worked. Well, the easiest thing to do is going to be read back in that custom basket field and display it, which we’re going to do in a second. Before we do that I want to take a look at the Miva Merchant mysequel database to show you how these custom basket fields are actually saved. Here I am, logged into Miva Merchants control panel and I opened up phpmyadmin, which is a web tool that allows me to view the mysequal database. On the left hand side here I have all the database tables. And on the right hand side it’s showing me some specific information for this basket info table. This basket info table is a table that’s used to save the custom basket fields. If I click on this here to refresh it, you’ll see that I have one entry within this table. I edit this entry, so here it has some information about the basket id, the module id, and then here’s the actual information. It has customer_ip, which is the code I used to create the Custom Basket Field and then the ip address. So this is actually where the data is saved. You can see this syntax looks pretty similar to what we’ve seen in some previous videos where we took a structure or an array and we serialized it to output it to the page. This is exactly what’s going on here. The data gets serialized, written to the database and then it gets deserialized which basically restores its object, whether that’s a structure or an array, and allows Miva to use it when needed. You shouldn’t ever need to come to the mysequal database and modify the custom basketfields like this. But it’s important to understand how this data is actually saved if you’re ever trying to troubleshoot something not working.
Let’s jump back to the text editor and look at some more examples. Let’s add one more right basket tag. So here I’m going to give it a field code of “my basket field.” So here you’ll see I’m using spaces just to show that they will work and I’ll give it the value of “Hello World.” Let’s bring this over to Miva, and jump back into the front end and refresh. Again, nothing happens. Ok, let’s take a look at how to read those fields back in.To read a custom basket field it’s going to be done with a read_basketfield function. It has two parameters; the field code that you defined, it has to match exactly what you have up here, and then the second one is optional, but this is where the value is going to be saved back into. So here we have g.customer_ip. Now one important note with this global variant we are creating here, this again can be anything you want. It can be a local variable, a global variable, however, because this statement is being evaluated, you don’t want to use dashes in the global variable name. While that’s a completely valid global variable, Miva will actually read this as g.customer - g.ip. It will actually treat those as two separate variables and try and do a subtraction on them which doesn’t work and won’t give you the desired result. So as a rule of thumb, if you’re creating a global variable to save some custom variable back into, stay away from using dashes. So here I’m going to call it g.customer_ip. Down here I’m outputting the entity &mvt:global:customer_ip. So let’s bring this over to Miva and run it. When we hit refresh, you’ll see I have the ip address that I first saved into a custom basket field and then read it back in.
Now I can read this value in any page, it doesn’t have to be just the storefront here. It doesn’t have to be the page I wrote the value into the custom basket field because the value saved in the database, it’s available anywhere throughout Miva. Back here in my text editor, let’s take a look at one more example. Right now I have two custom basket fields. And they are pretty easy to read in using this function here “read_basket” and then I pass in the field code of what I want to read. Well say for example I had 10 or 15 Custom Basket Fields and I didn’t want to individually read them in, well, every custom field, not just the custom basket fields has the ability to create an array of all the custom fields of that type. So in this case I want to create an array with all the custom basket fields. In order to do that, use the same “Read_Basket” function, but instead of passing in a specific basket field code, you pass in an empty string which is two single quotes. This will automatically create an array of custom fields that you can iterate through and output the code and the value. So let’s take this code here, bring it over to Miva, hit “Save,” and so now when we refresh it output the field code that I defined, plus that value for all the custom basket fields that exist. So this is very powerful, and remember it’s not just for custom basket fields. You can use this for any type of custom fields. Custom Basket Fields are a very powerful part of Miva Merchant. They give you, the Developer, a lot of flexibility to save and retrieve data without having to worry about any of the heavy lifting of communicating with the database or cleaning up the data once the basket has expired. Miva handles that automatically for you. Once you start incorporating Miva Merchant Custom Basket Fields into your Development workflow, it will be very hard to go back and use cookies ever again.