So let's dive into the new Custom Field Function Syntax. There are seventeen functions in total. Eight for reading, eight for writing, and then a debug function to help with troubleshooting. They all follow this similar structure. Now these functions are all part of these custom field module, so their going to be used within an item tag and the function itself is going to be passed as a parameter within that tag. Because all of the functions follow a similar syntax, once you learn one or two it's easy to deduce what the other functions will be. This makes using them and remembering them very nice. So here's the function we have, Read_Product_Code. That's the name of the function and it passes in three parameters; a string named test, a string named custfield1 and a variable called l.settings:myvar. Now let's dive into each section one by one.
So the Read is either going to be read or write, depending on what you want to do. The function will always start with that. Read_Product_Code, Write_Product_Code. The next section will be identifying what kind of custom field you want to work with. So a custom product field, a custom category field, customer field, basket field or order field. So there are four types of custom fields and there are four different types of functions that you can use for each. The last one is either code or id. This is defining whether you're going to pass in a product code or you're going to pass in a product id. Now sometimes one or the other may not be available on the page. This is why there are functions for both. However, most the time the id or the code will always be available on the page. So you can use whatever function you like better.
Now let's talk about the parameters. First parameter is going to be the id or the code or whatever type of custom field you're working with. So in this example we're working with a custom product field and we told it we want to pass in the code of the product so instead of the string we're passing the value of the product code, which in this case is just test. This could also be a variable. So say we had the product code as a variable, maybe g.product_code, we could pass this value in as well.
All the parameters are in a comma-separated list. So we add a comma and the second parameter. Now the second parameter is the custom field code that we want to reference. The way to find this is to create the custom field itself. So, in the Miva Admin under Utilities and the Custom Fields tab we would have already had created a custom product field with a code of custfield1. Now this code can be anything you want. Because you defined it, you have control over it. You need to make sure you pass in the correct custom field code of what you want to reference.
Now the third parameter is completely optional. If you use a function with this parameter, Miva will read the custom product value and will save it back into that variable. That variable can be a local variable that you see right here l.settings:myvar or a global variable g.myvar whatever you choose to declare as the variable. Now, if you don't define this parameter, if you just use two parameters, then the data automatically gets saved back into l.settings:customfields and we'll look at that in a second. Let's take a look at some examples to help clarify what this all means. So back in my text editor, here's the full syntax to read in a custom product field. It's always going to be contained within an item tag. So this part never changes. &mvt: and the name of the item is customfields all one word, this is telling Miva that you want to use the custom fields item which references the custom fields module and then the parameter. So the parameter to this item tag is going to be the full function we just looked at. So the function we want to use is Read_Product_Code or pass in product_code, custom_field_code and then an optional third parameter, for a variable you want to save the data back into. So that's how you read a custom product field, how would you write a custom product field?
Well, here's syntax. The first parts exactly the same. All the way up to this parameter, this will never change. The only difference is, instead of Read here we have Write. Write_Product_Code, which means we're going to write to a custom product field and we're going to reference that product by its code. Again, we pass it the product code, pass in the custom field code, and then this one because it's a write, there's nothing that gets saved back into a variable. Instead, we're writing data to the database. So the third parameter, this is actually a required field, for the value that we want to pass in, and this value right now is a string because it's in single quotes. This value could also be a variable. We're going to take a look at an example here in a second that uses both these functions. However, I want to first show you the reference documentation for these new custom field functions. This is going to be your go to resource when looking at how to use a function or what the parameters need to be. This documentation is linked below this video. It has the image we just looked at which breaks down how to use each of the functions and also goes into more detail about how to use each of the parameters and what they mean. What you'll use most however is the functions themselves. So here it gives you an example of what all seventeen functions look like and what the parameters are that need to be passed into them. So you can see the Read_Category_Code,Read_Category_ID, you can look up a customer, an order or a product and the same things go for write. So you can write to a custom category field with the code, the id, the customer, the order and the product.
Now the last three are the Read Basket Function and the Write Basket Function and then a Debug function that will help with troubleshooting. This page also gives you some good examples of how to use these new custom field functions. Let's dive in and take a look at these in action.
So back here in the Miva Merchant Admin, let's take a look at how to use the new custom field functions to read in the custom product field. Let's go into Utilities and look into the Custom Field that I have configured. So right now I have one custom product field with a code of msrp. Let's say for example we wanted to pull this custom product field in on the Product page. Let's go to PROD and scroll down to Product List Layout. You'll see here that I have Retail Price already assigned to this page. This was back from when we talked about the Legacy version of custom fields. It doesn’t actually need to be assigned. With the new custom field function you don't need to worry about any of the fields getting assigned to the page before you use them. However, we see here some of this code that Mica inserted has the legacy version of custom fields. I'm going to leave this hear just as an example to show you that both the legacy version of the field and the new functions work side by side. So right below this code I'm going to add in a function to read the product code. So here, this first parameter, because we're on the product page, I know that g.product_code exists as a variable. I can also use l.settings:product:code as well. Both of them should work. So a lot of times you'll have multiple options to choose what to pass in. So I'm just going to use g.Product_Code and because it's a variable I'm getting rid of the single quotes because I don't need it since it's not a string. And so the second parameter here is the custom field code here I want to reference. Well this is going to be a string because I'm hard coding it to be the msrp field. So I'm going to change this to msrp and this third parameter is an optional parameter where we can define the variable the custom field gets saved back into after it's read. I'm going to create a global variable called g.msrp. So what this function will do is it will go and read the value of the msrp custom product field, or whatever product we're looking at. It will save that value back into this global variable of g.msrp. Now this function doesn't output anything to the page. All it does is read and create the variable. So, right underneath this I'm going to output the value to the page, &mvt:global:msrp because that's what we define right here. I'm going to prefix this hear with a label just so we can see which one is which. I'll put a break tag and then New Custom Field. Ok, now let's go ahead and save this. Let's go back to the front end and refresh the page. You'll see here's the legacy custom field where it prints retail price, that's the name of the custom field we gave it and then its value. Now here's the new custom field which we defined, and right now it's only printing its value, but you can see that both work side by side and it does exactly what we want. It goes and grabs the value of this custom field and prints it to the page.
Let's take a look at how to write a custom product field from the page. Let's jump back to the Miva Admin and make a quick change to this function. So here is the function we just worked with. Now this third parameter is the one I've been saying is an optional parameter. So what happens if you don't define it? Say we get rid of it all together. Well, the way the custom field works if you don't define the variable to save the data back into, it will automatically save it into a custom fields variable. So the way you reference that is l.settings:custom_fields or if you just want it output to the page, it's just &mvt:customfields. This will always contain the value that was read of the most recent custom product field read function. So let me update this. Now if we go back to the front end and refresh, nothing changes. It still outputs our $100 to the page, exactly what we'd expect.
Let's take a look now at how to write a custom product field from the page template. This is going to be done using the write product code function. We'll go back to the Miva Admin, both these here are reading in a custom product field value and outputting it to the page. The first one is the legacy way of doing things and the second one is part of the new custom field functions. So now let's try and write a custom field from the template language. So here's the function we need. It's Write_Product_Code because we're going to write to a custom product field using the product code. So here, we need to pass in the product code. Now, I could use this g.product_code value I used here but because there's multiple variables that contain a product code on this page, I'm going to use the second one, which is l.settings: product:code. Now both of these will always contain the exact same value and it's up to you which one you want to use. Sometimes this one might not be available and this one will and vice versa. Because both of them are available now I can use them interchangeably. The second parameter is going to be the code of the custom product field that I want to write to. So we want to change the msrp value.
The third parameter is a required parameter when writing to a custom field. It’s a value you want to write. So I'm going to change it from 100 to 200. Now here I'm passing in a string value because it's a dollar sign. If I didn't want to include the dollar sign, I could get rid of the single quotes and just use the number 200 that just requires single quotes around it. So let's do one more thing here. After I write the value of 200, let's read it back in. So we're going to use the same read product code function and just for fun I'm going to define a local variable so save the value back into. Because we're going to output this to the page, it needs to be within the listings structure. So it will be l.settings with a new value and then we'll output that to the page. It's just &mvte:new_value. All right, so let's talk through this one more time and let's see what's going to happen. Because a product field is going to be read twice, once using the legacy version and then again using the new custom field functions, and output to the page. So this value for this product will be 100. Then we're going to change this value. We're going to use the Write Product Code function to change the value of the mar custom product field to 200 and then we're going to read it back in and output it to the page. So let's update this code here and go back to the frontend of the website and refresh this page and see what happens. So we'll see here's the legacy version that's reading in 100, then the new function that's reading in 100 and then we changed it. We wrote the value of 200 and then read it back in and output it to the page here. It's exactly what we expected. This function changed the value of this particular product. Now because I put this function globally on the product page, it will actually do this for every single product. It will write the value of 200 under the mar custom product field. Now if I refresh this again we should see this retail price and new custom field price both change to 200, which they do. That value in the Admin for that product has changed. We can verify that by actually going back into the Admin and looking up that product. We'll go into the Custom Tabs field here and we'll see it has a retail price of $200.
So the new custom field functions give you the power and flexibility to read and write any custom field from any page. They are extremely powerful and one of the best developer features within Miva Merchant. Once you master the Syntax of the function calls, Miva's custom fields become a natural part of your developer toolkit.