Hello! Welcome to my humble web presence. I'm Mark Hamstra, 29 years young, wearer of many hats at modmore, resident of Leeuwarden, the Netherlands. Most of my time is spent building and maintaining awesome extras and tools at modmore, but I also love gaming, cooking, and my dogs. More about me.

This site is where I share thoughts, cool projects and other oddities related to MODX, xPDO and ExtJS. I also write about MODX regularly over at MODX.today. Sometimes I post three blogs in a week, sometimes there's nothing new here in a year. Read a random article.


One of the new features in MODX 2.2.1 is the ability to indicate if a user is a "sudo" user. This humble checkbox is one to be extremely careful with, as it allows a user to completely bypass ANY access control you may have set up. This bypass is in the core, and will therefore also affect any custom access policies you built up and access policies by 3PCs, such as Quip.

When to use sudo users

Its goal is to allow the concept of a super user or administrator which is not affected by the security setting... you can imagine that to be helpful when you are working on actually setting up the security (to prevent yourself from getting locked out), or when you want to make sure someone has access to it all. This was a much requested feature from the forums.

More importantly: when NOT to use them

Please do not set a front-end user to be a "sudo" user. All access permissions means all access permissions, and if they find out the link to your manager (cause, being security aware, you used the advanced distribution to move it, right?) they are free to do ANYTHING, from editing resources to deleting your account or other wrecking things.

Sudo users don't even need to be assigned to any user groups in order to get full access.

Sudo users are to be used for providing access to everything in the manager and all front-end contexts - if you don't feel at ease with someone having that access, do NOT set them as a sudo user. Simple as that.

How to set a user as Sudo user in MODX

If you are updating to MODX 2.2.1, you will find that any users which are assigned to the Administrator user group with Super User permissions will have been marked as a sudo user. The first account you create via the installer (for a new install) will also be set to be a sudo user by default.

To set other users as sudo users, open Security > Users in your MODX 2.2.1 manager, and edit a user you want to give full access. You'll see the below screen. Simply tick the Sudo user box, and save the user.

How to set a user as Sudo user in MODX

Programmatically setting a user as sudo user

As we're dealing with what is pretty much root permissions, it is not possible to simply use sudo in a modUser->set() or modUser->fromArray() method - this is filtered out and will return false. This is to prevent auto assignment exploits (like the ones that caused an uproar in the Rails & Github communities recently).

Instead, you will want to use the modUser->setSudo(true|false) method. Pass it a boolean true to mark a user as sudo user.

Conclusion thingy

Do not start handing out sudo permissions! It's an extremely easy way to lose control over your manager if the user is not to be trusted. Every user set as sudo user could get its password guessed and cause you some major problems. But it's a great feature for developers setting up the security who don't like getting locked out!

This is probably a surprise for most of you (I have been in touch with some clients and partners about this already), but I am joining the MODX team! Mid March I will join the team part-time for a few weeks and in April I will officially hop on board full time for hopefully years to come.

Whoah, what?!

Yep, it's a big change that will not only affect me but also the very loyal clients I have had the pleasure to work with over the past year and 3 months. It wasn't one I took lightly (it rivaled the school vs freelance business battle back in March-Sept '11 for those that sticked around since then!), however I would be crazy not to accept an offer from the MODX team!

I will be joining MODX Services (consultancy, development and support) team, which is led by James Bohan-Pitt (most Partners will know him), and includes Garry Nutting and Mike Schell as Developers, and Robert Walker as Customer & Partner Support Manager. The team deals with obviously the support requests coming in from MODX Complete subscribers as well as development work for Partners and potentially some of the amazing MODX clients. Besides that, I will also get the chance to work on some great projects I can't say anything about yet, as well as the core product: MODX Revolution.

This job offer didn't just hit my inbox out of nowhere of course, I've been talking with Ryan Thrash on and off over the past year about the prospect of joining the team. The ball really got rolling in the past weeks when talking with Ryan, James and John Corcoran (the MODX CEO) and we're all very excited to finally be able of moving forward with my addition to the team.

What about my Company & Clients?

As said before, this new job does not differ much from what I used to do. Because of that I will be able to still provide the services I have offered before, however the invoice will have "MODX" on it and there will be an entire team to handle the work instead of just me! The MODX guys have been amazing in trying to make the transition as smooth as possible and if you would prefer me as your main point of contact they'll gladly oblige!

I will be working with MODX fulltime starting in April and likely wont be able of taking on many other projects, though stay on the lookout for one of the many personal projects that I will be working on.

If you're a current client (or we have been discussing a project for some time) and I've not yet been in touch about how your project will be moving forward with this very quick transition, send me an email. I've tried to reach out to everyone directly influenced by this, but with everything going on around here it's possible I've missed you. Sorry!

What about the site?

Over the coming weeks my website's content will be updated to more accurately display the new situation. Most of the Services section will be deprecated and removed (yes, that's part of the reason I made a new centralised Testimonials page) and some information will be added here and there to indicate the new situation.

The blog will remain like it is, and I will still be aiming for 2 posts a week (Monday and Thursday), so there's plenty coming up to keep you informed!

In other news...

I'm finally moving out (again)! Around the same time we were finishing up the deal of me joining the team I was offered a three bedroom (read: a bedroom, office and washing/junk/sleep-over room) apartment and I'll be working on painting the walls, laying floors and getting some furniture in over the coming weeks as well. I hope to have officially moved by the time I join the MODX team full time... we'll see how that goes :)

One of the powers of MODX is its flexible templating. The biggest part of the flexibility boils down to the different types of tags that can be used in Templates which replaced with the dynamic content specified.

While the different tags are listed in the Documentation, not all of them are properly explained and some take time to really make sense when you just started using MODX. This blog post will explain the difference between two tags that are very often confused with eachother: placeholder and resource field tags.

Let's see what the two terms actually mean and which is which.

Resource Fields

A resource field is a field of a resource. Oh, you figured that out already? Great! So if you fill in fields of a certain resource in the Manager, the value of that field is available through the resource field tag. What is important to realize here is that you can use these tags, no matter where they are used (in templates, chunks or elsewhere), will take the value for the current resource. So if you're viewing the homepage, a resource field tag will get the value from the homepage resource. If you're looking at a contact page, the resource field tag will be replaced with the values of the contact page.

It may seem logical or common sense (and really, it is!), but that's where placeholders differ from resource fields. 

Resource fields use the *asterix* token in the tag. Some valid examples:

And their values for the current resource:

Title: Welcome!
Introtext: Hi there! Nice to meet you - my name is Mark Hamstra and I am a MODX Revolution Developer working freelance for other companies and agencies. I also write stuff about MODX. Can I help you?
Menu Index: 0
Content (not shown to prevent the page from breaking!)

Placeholders

A place holder can be anything. 

Yes, really. Anything.

The key thing to realize with placeholders is that they are being specifically set by usually a snippet or plugin. That snippet or plugin decides what a specific placeholder will get as a value. Some snippets such as getResources or my getRelated iterate over resources, and they assign placeholders with the same name as the resource field. 

Let's go a bit more practical.. You may have a resource listing on your homepage (for example the latest Articles), retrieved with the getResources snippet. Your Homepage template will probably use the Resource Field syntax to display the current page's title in the <head> part:

Your getResources snippet on the other hand uses placeholders to provide you with information on the resource it is looking at. With getResources you specify the &tpl property which is the name of a chunk that will be used when iterating over resources. The chunk may look like this:

This means that when getResources reads the resources with ID 2, 3, 4 and 5, it will load the tpl chunk four times, and assigns values as placeholders each of those four times. The first time it loads the chunk it sets the values to the resource fields of resource 2. The second time it takes the resource field values for resource 3, the third time for resource 4 and finally for resource 5. So in this case we have placeholders that give information on a resource which is not the current resource.

Resource Fields always contain values for the current resource, while placeholder values can be anything from other resources, custom tables or simply random stuff. 

A note about Placeholders

While placeholders are usually set by snippets or plugins, that doesn't mean that's the only way they can be set or used.

You can also add parameters to a chunk tag, which can then be used as placeholders within a chunk. This is a nifty technique if you only need minor changes depending on the template, and want to prevent repeating yourself.

 

New Extras are released all the time, MODX LLC is always working on the next big thing and the Community is growing exponentially. In this series I'm going to try and keep you posted on interesting initiatives and stuff coming up. Welcome to Episode 1!

In this episode:

  1. [Extras] Interesting new TV Input Types
  2. [Extras] All things Analytics
  3. [MODX] Mostly Cloudy, with a 100% chance of MODX™
  4. [Evolution] Security fix for 1.0.5 now available

1. Interesting new TV Input Types

Many consider Template Variables the number 1 reason they like MODX, which is definitely something I can relate to. However, did you know you can also develop new input types to bring it all to the next level? Well, you can!

A lot of people know about MIGX, short for Multi Items Grid TV (for MODX?), which allows you to work with a grid, or table, enabling you to add an unlimited list of items. I think it could use a cleanup, but it does what it promises on the tin and I use it quite often. 

In the last few weeks, a couple more interesting TV Input Types have been released. ColorPickerImagePlus TV Input and SuperBoxSelect.

ColorPicker is not exactly new, the first version was released back in November, but it gives you a pretty nice colorpicker with different output types (such as HEX, RGB or JSON). If you allow users to change the color of certain template aspects, ColorPicker sounds perfect for the job.

ImagePlus TV Input is for those times where the default image cropping of PhpThumb(Of) is not enough, and you need to define exactly what is shown yourself to prevent weird results (like seeing only half of a face). While there's still a few bugs and I wouldn't recommend production use yet, this is definitely something to keep an eye out for as it gets further developed.

SuperBoxSelect, by the same author as ColorPicker and also first released in November, is a variation to the default ResourceList input type which allows you to select multiple resources through a combo (dropdown/select) box. 

2. All things Analytics

We all like Google Analytics (and making sure manager users don't show in the stats!), and over the past period a number of addons specifically for Google Analytics have been released.

First we have the Google Analytics Dashboard (for 2.1), its MODX 2.2 spin off using a Dashboard Widget and Big Brother, all of which request the Analytics data through its API (after authorization of course) and shows it to you the moment you login to your Manager. I've been using both the GA Dashboard Widget and Big Brother, and I have to admit I prefer Big Brother. Its authorization process was smoother (and looks super fancy, too!), and more matched the information I expected on the dashboard.

We also have two extras to put the analytics code into your templates, which are Analytics and Google Analytics (the naming isn't as original as Big Brother!). 

3. Mostly Cloudy, with a 100% chance of MODX™

.. or at least that's what the MODX team is telling us!

MODX Cloud, which is currently in private beta, will (again) revolutionize the MODX world by offering a cloud based platform where you get a fully configured installation of MODX Revolution in the Cloud. This new infrastructure, which is powered by MODX Sponsor Softlayer, will likely come with all the flexibility and benefits of cloud hosting: super fast and easy deployments, easy migration between servers and of course scaling with a click of a button (if that!) when you most need it. Rumours tell me there are some specific MODX benefits attached to Cloud as well (no specifics here though!), and from the looks of it you will also be able of getting access to MODX Cloud through the all new "coming soon" MODX College.

Seeing how the Revo development on Github has been a tad slower lately compared to the past weeks, I'm going to bet the team is working hard to get this out there! ;)

4. Security fix for MODX Evolution 1.0.5 available

Last week a critical security issue in Evolution 1.0.5 was discovered, which allows certain (Extra) configurations to be exploited, resulting in executing of snippet tags. Some people have indicated added files in the assets/cache folder which did not belong there and may have provided an entry point for further exploitation. More details in the Security Notice on the forums

The fix be applied manually by replacing the contents of your manager/includes/protect.inc.php file with the version on Github. Alternatively MODX Evolution 1.0.6 should be available soon with this fix and possibly more.

In the next episode...

I've got some ideas for the next in this series, but do let me know what you would like to hear about! The next episode will probably arrive in a few weeks.

Have you ever had a client asking for showing a list of related articles or news items? Chances are you've applied a technique to show a list of all articles in a Template Variable, allowing the client to handpick the ones that are related. This is a great technique and I have written about it in the MODX Documentation, but the admin or editor still has to manually pick what is related. Surely there's an automated way as well?

Back in fall 2011 I was contacted by Vierkante Meter, a Dutch web agency focusing on accessible websites, with exactly that request: a way to automatically show related articles. Some time later getRelated was born as the answer to their questions as well as that of many other developers. I've even deployed it on my own site! Just look a the "Related Articles" block to the bottom right of this post (not visible on mobile for now).

getRelated is very powerful, but, if I can say so myself, still very easy to use. It can be installed via the MODX Package Manager and from there you just need to call the snippet in your template - and it's there! But of course, the power is in the details..

What makes getRelated awesome

(More information about the aspects mentioned below can of course be found in the getRelated Documentation.)

#1: Configurable algorithm.

getRelated checks out the resource it is called on (or the resource you specify with &resource=`ID`), and identifies unique words in the fields you specified, and it uses those to find matching resources. To come up with the order in which they are returned, it specifies a value for every field. A value of 5 means that every matching word in that field is rewarded with 5 points added to the total. At the end of the processing cycle it sorts the results by the amount of points rewarded.

By default it only looks at the pagetitle and introtext, but by simply specifying the &fields property you can tell it what fields to use and how valuable they are. According to the docs:

That's a lot of information in only a few lines, but it tells you how to define the value of each field, and that you can even use TVs for them. To show how that works, here's the &fields property used on my site:

The most value is assigned to the "mh.categories" template variable: it's what I use to categorize my posts in 2 or 3 categories each, such as front end development or ExtJS. The "12" means that every category is worth 12 points when it matches on a different resource. So if another article has one category in common it scored 12 points. Every matching word in the pagetitle is worth 6 points, longtitle gets 4 points per matched word and the introtext gives 2 points. By defining all of that in the &fields property you can pretty much define your own algorithm for finding related pages automatically. You may use both categories and tags, so you could give categories a higher value compared to the tags to get the most accurate results.

#2: Completely configurable output

Besides the ability to specify, you are able of completely configuring how your related resource is shown. The default is a h3 tag and an unordered list with the top 3 related resources. But using the &tplOuter and &tplRow property you can change it to your hearts content. 

As performance is a big priority with a tool like this, it only sets placeholders for the fields you specified, and as of the 1.1 release (for MODX 2.1+) it also allows you to use TVs in the output. Just specify the resource fields (ie pagetitle, introtext) in the &returnFields property and the TV names in &returnTVs. Again, for speed it only gets the TVs for the top ranking results, so no performance is lost. 

For example, this is a screenshot from a current project (a jewellery webshop) of mine, which uses getRelated with returnTVs to show related articles. 

And the getRelated snippet call:

The match is completely defined on TVs used for products: the tagline, colors, materials and stones. Here's the getrelated.row chunk:

The getFirstImage custom snippet is used to get the first image: the product.images TV uses MIGX to allow unlimited amount of images. The custom snippet uses the following chunk to show the image (product.firstname chunk):

#3: Excited client!

#4, #5, #6 etc: More possibilities!

Use the &parents, &includeHidden, &hideContainers, &contexts, &exclude and more properties to decide which resources to include or not. 

Spotted in the wild!

We've just hit 650 downloads (well, okay: 647, but close enough!) of getRelated so far, I am very interested in seeing how people have been using it! Feel free to leave a link in the comments to show how you're applying it... I may feature the most impressive uses here as well!

Since the launch of MODX Revolution 2.2pl, the use of the Articles blogging tool has been growing exponentially as well. This post walks you through a question that is being asked several times per day: how do I show Articles on my homepage or in a sidebar?

Including Articles in Wayfinder or getResources

As individual articles are stored and used just like any other resource, you can use the same tools to display them such as getResources or Wayfinder. The trick there is that Articles are set as hidden from menus, which both of these snippets hide by default. Luckily both of the mentioned snippets support including those as well using a simple property, as shown below.

Wayfinder uses the &ignoreHidden property. As it is primarily a menu building tool, if you want it to to show hidden resources you tell it to ignore the hidden state. getResources is not linked with menus directly, and uses the &showHidden property to indicate you also want hidden resources to show up. So they do the same, but the terminology used for it is slightly different and can seem counter intuitive at first. 

But what if you don't want them included?

Excluding Articles in Wayfinder or getResources

If you don't want the articles posts to show up in a Wayfinder menu or getResources list, you can filter them out by checking against the "class_key" variable.

Normal resources have that set to modDocument (or modWebLink, modSymLink or modStaticResource), but as Articles installs a custom resource class the class_key is different as well. The blog container itself is an ArticlesContainer class, and the individual articles are of class Article. Knowing this, we can filter against this using the &where property. This &where property, commonly available in extras, accepts a json string representing an array (with xPDOQuery::where style comparisons). That may sound complicated, but here's an example for Wayfinder and getResources:

And that's all! Happy blogging!

Update!

Mere houres after publishing this article the MODX RTFM was updated with some more information on accessing all of the placeholders used in the Articles templates,  including the latest articles, tags and comments. Find it here.