Bob's Guides

Personalize Snippet Tutorial

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-premium 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.

Usage

Strictly speaking, none of the properties are required. Typically you will set the &yesChunk and &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 &firstName=`1`.

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.

Example

Create Chunks named HelloUser and 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 HelloUser chunk:

<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.

Inline HTML

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 &yesChunk and &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`
]]

The @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.

&ifIds Property

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 &noChunk property).

&allowedGroups Property

Another addition by Vasia123, the &allowedGroups 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 &noChunk property).

Combining Options

Here's what happens if you use the various selection properties alone or together:

• If you use the snippet without the &ifIds and &allowedGroups properties, any logged-in user will see the yesChunk.
• If you use the &ifIds property alone, only logged-in users who are in the ID list will see the yesChunk.
• If you use the &allowedGroups property alone, only logged-in users who belong to one or more of the allowed groups will see the yesChunk.
• If you use *both* the &ifIds and &allowedGroups properties, only logged in users who meet both criteria will see the yesChunk.

Personalize Properties

Testing

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.

Copyright © 2011-2024
Bob Ray