Personalize Snippet Tutorial
I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.
It's common to want to treat logged-in users differently than anonymous visitors. The Personalize snippet will show one chunk to logged-in users and another to all others.
Installing Personalize for MODX Revolution
Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put Personalize in the search box and press Enter. Click on the "Download" button, and when it changes to "Downloaded," click on the "Finish" button. That should bring you back to your Package Management grid. Click on the "Install" button next to Personalize in the grid. The Personalize snippet should now be installed.
Strictly speaking, none of the properties are required. Typically you will set the
&noChunk properties. If you just want to set the placeholder, however, you can leave them out and just set the
&ph property. In order to have anything appear in place of the snippet tag, though, you need to create the
yesChunk and (optionally) the noChunk chunks and specify their names in the snippet tag. As of Personalize 3.4.0, the
&noChunk property is optional. If you leave out the
&noChunk property, nothing will be shown to not-logged-in users.
[[!Personalize? &yesChunk=`MyYesChunk` &noChunk=`MyNoChunk` ]]
You can put the snippet tag in the page content or (usually better) in the template. When the page is rendered, the snippet tag will be replaced by the contents of the appropriate chunk.
If you'd like to have the User's username appear in the
yesChunk (or elsewhere on the page), you can tell Personalize to set a placeholder for it using the
&ph property. The placeholder tag (see example below) will be replaced by the username.
If you're using the placeholder and would like to use the user's full name instead, just use
&fullName=`1` in the snippet tag. If you would like to use the first name for the placeholder, use
Note that you can also use the placeholder in other places on the page as long as they are below the Personalize snippet tag. If the snippet tag is above the
[[*content]] tag in the template, you can use the placeholder anywhere in the page content as many times as you like. As mentioned above, you can leave out all the properties except
&ph. Personalize will just set the placeholder and nothing will appear at the snippet tag location.
Create Chunks named
LoginLink, the first will be
shown to a user logged in to the current context,
the second to all other users.
Put this code in the
<p>Hello [[+personalize.name]]. Welcome back!</p>
Put this code in the LoginLink Chunk (replace
## with the ID of your Login page):
<a href="[[~##]]">Log in</a>
Put this tag in the template or the page content where you want the output to appear:
[[!Personalize? &yesChunk=`HelloUser` &noChunk=`LoginLink` &ph=`personalize.name` &fullName=`1` ]]
Logged-in users will see the welcome message. All other users will see the Login link. The Placeholder
[[+personalize.name]] will show the user's full name in the welcome message. If the user has no User Profile, or the fullname field of the Profile is empty, the snippet will fall back to the username.
You can use any name for the placeholder tag, but be sure the placeholder name specified in the snippet tag matches the one used in the yesChunk or elsewhere on the page.
As of personalize 3.4.0 (thanks to MODX community member Vasia123), you can specify the HTML to show to both kinds of users in the
&noChunk properties in the snippet tag rather than using chunks. Here's how:
[[!Personalize? &yesChunk=`@CODE:<p>Welcome back [[+personalize.name]]</p>` &noChunk=`@CODE:<p>You are not logged in</p>` &ph=`personalize.name` ]]
@CODE: prefix must be the very first thing in the property string. It must be in uppercase and must be exactly as shown here, including the preceding @ sign, the following colon, and no spaces.
Again thanks to Vasia123, the
&ifIds property lets you specify the IDs of specific users who should see the
yesChunk content. Just put a comma-separated list of IDs in the
&ifIds property and only users in the list will see the yesChunk. Everyone else will see the
noChunk (or nothing if you leave out the
Another addition by Vasia123, the
property lets you specify the names of groups the user must belong to in order to see the
yesChunk content. Just put a comma-separated list of User Group names in the
&allowedGroups property and only users in the list will see the
yesChunk. Everyone else will see the
noChunk (or nothing if you leave out the
Here's what happens if you use the various selection properties alone or together:
- If you use the snippet without the
&allowedGroupsproperties, any logged-in user will see the
- If you use the
&ifIdsproperty alone, only logged-in users who are in the ID list will see the
- If you use the
&allowedGroupsproperty alone, only logged-in users who belong to one or more of the allowed groups will see the
- If you use *both* the
&allowedGroupsproperties, only logged in users who meet both criteria will see the
|yesChunk||Chunk or inline HTML to show to logged-in users||(empty)|
|noChunk||(optional) Chunk or inline HTML to show to not-logged-in-users.||(empty)|
|ph||(optional) Placeholder to set for username||(empty)|
|fullName||(optional) Use fullname rather than username for placeholder||No|
|firstName||(optional) Use firstName rather than username for placeholder||No|
|ifIds||(optional) Comma-separated list of User IDs to show yesChunk to||(empty)|
|allowedGroups||(optional) Comma-separated list of User Groups to show yesChunk to||(empty)|
|context||(optional) Context user must be logged into to see the yesChunk||(current context)|
Remember that when you are previewing a page from the Manager, you are not logged in to any front-end context, so Personalize should show you the
noChunk and the placeholder will not be set. If you are bouncing back and forth between the Manager and the front end, however, some versions of MODX can get confused about where you are logged in, so it's best to test the snippet using another browser where you're not logged in to the Manager.
If you have the book and would like to download the code, you can find it here.
If you have the book and would like to see the updates and corrections page, you can find it here.
MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:
- Installing MODX
- How MODX Works
- Working with MODX resources and Elements
- Using Git with MODX
- Using common MODX add-on components like SPForm, Login, getResources, and FormIt
- MODX security Permissions
- Customizing the MODX Manager
- Using Form Customization
- Creating Transport Packages
- MODX and xPDO object methods
- MODX System Events
- Using PHP with MODX
Go here for more information about the book.
Thank you for visiting BobsGuides.com
— Bob Ray