Express - What is the 'Name Mask' in data objects?
Permalink
Hi There,
Express looks interesting so I'm having a play but what are Name Masks?
The dashboard form states...
But I don't understand what that means or which part is the 'Name Mask' - nor can I find info on it sorry.
Any help would be much appreciated.
Cheers
Ben
Express looks interesting so I'm having a play but what are Name Masks?
The dashboard form states...
'Example Entry %name% or Complaint %date% at %hotel%'But I don't understand what that means or which part is the 'Name Mask' - nor can I find info on it sorry.
Any help would be much appreciated.
Cheers
Ben
@cmscss
Here is draft explanation of how the Name Mask field works:
'There are certain times when we need to know how to display the name of an express object, usually this is when that object is listed as an association for another object.
In the salons and stylists example, you might have a Salon object with a one to many Stylist objects (who work at the salon) relationship. When you’re retrieving a list of Stylist objects as you display the salon, you need to know how to display the stylist in that list. But we didn’t add a “Name” attribute or anything like that, we just have custom attributes that can change from object to object. That’s where the name mask comes in.
You can basically loop through all associated Stylist objects and say “give me the display label for this object” and the name mask determines what that actually is. The name mask itself is just a string where you wrap your attribute handles in "%" delimiters. The actual value of the attribute will replace the "%attribute_handle%" when it is displayed. When you want to display the display label in your code, you would use the getLabel() method on the object.
In the example of stylists, let’s say there are two custom attributes for each stylist, with the handles "stylist_first_name" and "stylist_last_name". If you make the name mask for Stylist: "%stylist_first_name% %stylist_last_name%", any time you display the salon in an associated list in the dashboard it will look through to the Stylist object and retrieve the first name and last name and display that stylist like “John Smith”.'
Example: get the display label (the name mask label)
- the name mask is "first name: %contact_question_first_name% last name: %contact_question_last_name%"
This might display something like:
first name: John last name: Smith
first name: Olivia last name: John
first name: Rob last name: Roy
Here is draft explanation of how the Name Mask field works:
'There are certain times when we need to know how to display the name of an express object, usually this is when that object is listed as an association for another object.
In the salons and stylists example, you might have a Salon object with a one to many Stylist objects (who work at the salon) relationship. When you’re retrieving a list of Stylist objects as you display the salon, you need to know how to display the stylist in that list. But we didn’t add a “Name” attribute or anything like that, we just have custom attributes that can change from object to object. That’s where the name mask comes in.
You can basically loop through all associated Stylist objects and say “give me the display label for this object” and the name mask determines what that actually is. The name mask itself is just a string where you wrap your attribute handles in "%" delimiters. The actual value of the attribute will replace the "%attribute_handle%" when it is displayed. When you want to display the display label in your code, you would use the getLabel() method on the object.
In the example of stylists, let’s say there are two custom attributes for each stylist, with the handles "stylist_first_name" and "stylist_last_name". If you make the name mask for Stylist: "%stylist_first_name% %stylist_last_name%", any time you display the salon in an associated list in the dashboard it will look through to the Stylist object and retrieve the first name and last name and display that stylist like “John Smith”.'
Example: get the display label (the name mask label)
- the name mask is "first name: %contact_question_first_name% last name: %contact_question_last_name%"
<?php defined('C5_EXECUTE') or die('Access Denied.'); // express_form_170 is the express object handle for the sample content Contact form, it may vary $entity = Express::getObjectByHandle('express_form_170'); $list = new Concrete\Core\Express\EntryList($entity); $contacts = $list->getResults(); if (count($contacts) > 0) { foreach ($contacts as $contact) { echo $contact->getLabel() . '<br>'; } }
This might display something like:
first name: John last name: Smith
first name: Olivia last name: John
first name: Rob last name: Roy
Awesome reply, much appreciated but I'm still confused sorry. Specifically, why do we need another way to grab and display the field name?
“But we didn’t add a “Name” attribute or anything like that…”
Probably a simplistic question but why didn’t we add a name attribute? Isn’t the mask field in the same form as the field name?
Or is the mask an optional, alternative way of displaying the field name?
Also, is this for displaying the field name on the front end or the dashboard?
“…any time you display the salon in an associated list in the dashboard…”
Sorry if this is simple, I might also be confused by the term ‘mask’ - what does it mask?
“But we didn’t add a “Name” attribute or anything like that…”
Probably a simplistic question but why didn’t we add a name attribute? Isn’t the mask field in the same form as the field name?
Or is the mask an optional, alternative way of displaying the field name?
Also, is this for displaying the field name on the front end or the dashboard?
“…any time you display the salon in an associated list in the dashboard…”
Sorry if this is simple, I might also be confused by the term ‘mask’ - what does it mask?
@cmscss
In the example, there are two attributes, one for first name and one for last name. There may be situations where you want to display them with formatting like "last name, first name". With a name attribute, it would just be "first name last name" without the option to format how that might be displayed (it is just a string of characters). Name masks allow you to create a custom display label without creating extra, possibly redundant, attributes. Without the name mask, you would need to create a third "full name" attribute that required typing the first name and last name a second time.
Another example might be a product, where you wanted a display label to have a product name, product ID, and product type ("Landing Gear Rear Panel #32409b9f Aeronautics"). Instead of creating an attribute just to combine and reuse existing attributes, you create a name mask instead.
The name mask is an optional display label.
`any time you display the salon in an associated list in the dashboard it will look through to the Stylist object and retrieve the first name and last name and display that stylist like “John Smith”.'`
I believe the name masked display label is used within your custom code and not in the dashboard. I am not positive though - I need to test this (or someone else can confirm this).
In the example, there are two attributes, one for first name and one for last name. There may be situations where you want to display them with formatting like "last name, first name". With a name attribute, it would just be "first name last name" without the option to format how that might be displayed (it is just a string of characters). Name masks allow you to create a custom display label without creating extra, possibly redundant, attributes. Without the name mask, you would need to create a third "full name" attribute that required typing the first name and last name a second time.
Another example might be a product, where you wanted a display label to have a product name, product ID, and product type ("Landing Gear Rear Panel #32409b9f Aeronautics"). Instead of creating an attribute just to combine and reuse existing attributes, you create a name mask instead.
The name mask is an optional display label.
`any time you display the salon in an associated list in the dashboard it will look through to the Stylist object and retrieve the first name and last name and display that stylist like “John Smith”.'`
I believe the name masked display label is used within your custom code and not in the dashboard. I am not positive though - I need to test this (or someone else can confirm this).
Awesome, I'm getting there (I think)!
Last question, why would you use a mask over doing something like this?
Or do express objects not use views like block templates etc?
Last question, why would you use a mask over doing something like this?
<?= $firstName; ?>, <?= $lastName; ?>
Or do express objects not use views like block templates etc?
@cmscss
If I understand it correctly, less code.
Your example uses 2 attributes, but what if you wanted more than 2 attributes built into a specifically formatted string. It would require building that specific string each time you wanted to use it.
If I understand it correctly, less code.
Your example uses 2 attributes, but what if you wanted more than 2 attributes built into a specifically formatted string. It would require building that specific string each time you wanted to use it.
Got it, way easier to output variables within copy - thanks heaps for your patience, much appreciated. Cheers
There's a brief mention of it here:
https://www.concrete5.org/about/blog/community-blog/concrete5-821-no...
I hope that's relevant!
https://www.concrete5.org/about/blog/community-blog/concrete5-821-no...
I hope that's relevant!
Thanks guys but I'm a bit dim-witted sorry - I don't understand what any of that means!
Is there a practical use case? Using the boats and marinas example, what would it allow you to do and where would it get used?
Is there a practical use case? Using the boats and marinas example, what would it allow you to do and where would it get used?
This looks like a new feature that has not been documented yet.
It appears that it was added here:
"Name formatting for entities #5782
This copies the name format that was given to associations and allows it to be used for entities as well. This replaces a lot of the association naming functionality."
https://github.com/concrete5/concrete5/pull/5782...