“Why did I not think of this?” moment in MODX 3 snippet development with PHPStorm

This is one of those ‘Aha!’ moments.

MODX is one of CMSs (content management system) that I have been using for a long time to maintain my shogi site. Market penetration of this CMS is said to be 0.1%. As of this writing, 43% of of Web sites uses WordPress and no other CMS reach even 10% of market share. (source, w3techs.com . I actually think MODX penetration is much greater than this number, MODX does not leave big footprint to show it’s identity in front of web crawlers. -Many sites I know powered by MODX, including mine – were identified as non-CMS site by w3tech’s tool.— Nevertheless, there is no doubt WordPress dominates the CMS market)

Although both uses same language (PHP) for powering the site, MODX gives much more flexibility in site design but you need to be proficient with HTML and CSS (and JavaScript). In another word, MODX is a tool while WordPress is a product.

What I liked about MODX over WordPress at the time was a separation of PHP code and HTML. This was a long time ago so the situation might have changed on WordPress, but I have been happy with MODX since.

At the time, I also looked at Drupal and Joomra . All of them forces you to follow their interpretation of what website should be. MODX has no opinion on how you want to create Web site. You have a total freedom.

On the other hand, if the only thing you want to do with your site is blogging, there is no better solution than using WordPress.

I digressed. Back to the subject!

With a wealth of plug-ins available, your rarely need to code in PHP. When you do though, MODX separates a PHP coding part from HTML with a thing called Snippets. A snippet is then inserted in to HTML with a use of tag.


You can edit a snippet within MODX backend’s editor. With a plugin like ‘ACE’ there is a nominal amount of syntax checking to the PHP code. Unfortunately, I am being spoiled with convenience of IDE such as PHPStorm,

MODX backend, Snippet editor with ACE plugin

So there is a desire to be able to write a snippet code using PHPStorm and get benefits of auto-completion and methods hinting, strict error checking and warning.

Unfortunately, there is no plugin in PHPStorm for MODX or MODX plugn for PHPStorm.

When I google “MODX with PHPStorm”, there are several hits, Although none of them gave me a direct answer on what I wanted to do, I was able to put enough facts together and came up with a solution. The solution that was just waiting for me to assemble few known facts, that I have used all of them separately in the past!

1. Fact that PHPstorm can create a project using existing remote site contents, so that PHPStorm can pull all file setup from MODX site.

PHPStorm->File->New Project from Existing Files

2. Fact that PHPstorm can then start syncing file contents of my local project files to server files.

File sync options available in PHPStorm

Ok, but Snippet is stored in Database. the code is not in the file, but then,

3. Fact, MODX snippet code can be from a static file, meaning I can create a PHP file and feed it as a snippet to MODX by turning on “is Static” option and point to the file location

Is Static option is turned on for Snippet. Snippet is now fed from “static file”

Result: When I combine those 3 factors, I can create a snippet with a comfort of PHPStorm IDE environment.

Snippet now editable in PHPStorm
Snippet output on browser page, powered through MODX

What do I gain? Full context support and code hinting, as PHPStorm analyzes whole MODX site and figures out all variables and object and its methods being used inside MODX. I have to give credit to MODX development team for fully documenting source files. Thank you!

PHPstorm explains what getOption method is
PHPStorm autocomplete support in action.

You can also open the corresponding file by pointing to method and do control-b to drill down on function.

I edit a file in PHPStorm, and you either 1) turn on auto-sync between your local files and server files or 2) manually upload changed file to server. Then I can run and test the snippet with MODX backend immediately.

So all of the sudden, I feel like invincible. It will be very hard for me to make coding error. (Ok, logic error still possible)

Once Snippet development is done, you may switch off the ‘is static’ option and keep the snippet inside database, remove the php file from the system.

One thing that is kind of annoying is that by default, PHPstorm thinks $modx variable is undefined. The default setting on PHPStorm’s inspections on undefined variable is somewhat on conservative side. It will not even acknowledge variables from included file!. To mitigate this, you need to put a check on “Search for variable’s definition outside the current file”

PHP settings->Editor->Inspection->PHP->Undefined symbols->Undefined variable

It hurts to think that I have been using both PHPstorm and MODX for more than 10 years and I am figuring this out just now 🙁

Creating a Blog page inside MODX version 3 web site

MODX comes clean slate so there is no ‘ready to use’ provisions for creating Blog style site. One has to set it up using tools available in the CMS.

I took an easy way out for my production site by creating blog site using free wordPress service and then feed content to MODX page. with this, the only extra you will need is Spiefeed to handle rss feed from WordPress.  But for purist approach it is certainly possible to setup blog section within MODX using few extras.

There are several articles available for creating Blog sites using MODX.  The one shown in the modx official site is somewhat dated, but the article actually have a link to the instruction/article of more recent implementation of MODX blog site.  Link is here.   Better yet, this instruction is accompanied with a package published in the github which has all chunks, a snippet and a template packaged up to duplicate the blog site that the article discusses.  A demo site is also available to check out the feel of using this template. The document states that the demo utilizes MODX 2.7.  So can I use this setup with MODX 3 site? Furthermore, the instruction assumes you want the Site to be a blogging site. Can I add ‘Blog page’ to already existing MODX site? Answer to both questions are ‘Yes’ but we need to modify some parts.

To start, I could have created each chunk and template manually following the instruction but to reduce my typing effort, I went ahead and downloaded the demo package. I also installed dependent extras (getResources, getPage, Collections, and Tagger).  Previously, I did not have any of those installed. – I am using pdoTools  to get resources and get page. – <edit> It was fairly easy to change references to getResources and getPage to equivalent pdo* snippets.

Again, the setup instruction is written for MODX version 2.7 and the site I am setting up this blog structure is version 3.0.3.  Setup also assumes the top page is a site home page. There are several area in chunks and template that refers to [[++site_start]] and this need to be changed to point to correct Resource.  I want to have a blog page as a subpage of the site.

Looking through the template and snippets that I setup with the downloaded package , I found some more modifications were needed.

I will list out those changes.

  1. My server uses Nginx and it needs additional html tag to specify base url in <head> section of blog template html. Without it, Friendly URL won’t work correctly.
    <base href="[[++site_url]]">
  2. In MODX 3, [[*class_key]] does not return “modResource”.  It returns “MODX\Revolution\modResource”.
    This means I get “MODX/Revolution\modDocument” or “MODX\Revolution\CollectionContainer” in [[*class_key]] field depending on resource selected. Two sections of “Blog Template” stops working due to this.

    1. Template tries to pull in “jumbotron_CollectionContainer” or “jumbotron chunk based on [[$jumbotron-[[]*class_key]]] tag. This tag doesn’t work in MODX 3 as it returns [[$jumbotron-MODX/Revolution/….]] which does not exist and forward slash within chunk name is probably invalid anyway.
    2. Template tries to insert [[$blog_listing]] or [[$blog_article]] based on conditional modifier [[*id:is`[[++site_start]]`:then….]] but the blog_listing page is not at [[+site_start]] resources in my use case.
      1. To mitigate both problems, I have created a system setting [[++blog_start]] in custom namespace/area and set it to id of a blog home page resource I created. Then rewrote tags as follows.
        For jumbotron section
        For container section
      2. Note: It will be probably not that difficult to create snippets and replace conditional tags here.
  3. getResources and getSnippet tags are used to aggregate child resources and parents properties are set to site home page [[++site_start]].   These needed to be changed to aforementioned [[++blog_start]].  These changes had to be made on $blog_listing chunk and $jumbotron-CollectionContainer chunk.
  4. @groups properties are hardcoded in calls to TaggerGetTags snippet.  The snippet is called from $aside chunk is setting @groups to 1 and the snippet called from $headder chunk is setting @groups to 2.  Make sure this agrees with your tagger group settings. I have first created ‘Category’ group and then ‘Archives’ group so I needed to change them to 2 and 1 respectively.
  5. Last and least 🙂   as this is just a demo template, links to “subscribe”, “search”, “Sign up”, “GitHub”, “Twitter” and “Facebook” are all mocked and pointing to itself.  You either need to remove or put actual link to them when modifying to suit your site design.

So, in order to create a Blog section within Modx 3 hosted website, using this instruction and elements in the github repo, One needs to be aware of:

  1. Modx version 3’s breaking change of the model class caused decision logics inside Blog_Template to stop working.  Rework of the logic flow was needed.
  2. Friendly url.  Nginx needs base href reference in head section.
  3. Creating a blog section other than home page location. Needed to change references to [[++site_start]] system settings to [[++blog_start]], a user created system setting
  4. Adjust the template design to fit with other area of site design.

Some more miscellaneous items to note.

  1. $blog_listing_item chunk, content placeholder has a modifier :firstp. There is a firstp snippet that is installed with the package.  I opted to replace it with ellipsis=`500` modifier to limit the content output to first 500 chars followed by ellipsis to suit my preference.
  2. Also in $blog_listing, getPage snippet uses @blog properties set. This set does not exists so the default property set will be used instead. I think idea is to create a blog property set within getPage snippet to override the default property settings in easy way, if customization is needed.

Commenting on the posts are not possible.  This need to be setup by yourself and will require Quip extra. that part is not covered by this article. One has to go back to modx documentation’s tutorial section.


IIS のurls rewrite を使ってmodxのfriendly url を有効にする。

たとえIISサーバーを使っていてもHelicon Ape というツールをIISに組み込めば、modxについてくる.htaccess をそのまま使っのfriendly url を活用することはできているわけだが、今回はIISのURL rewrite module (IIS 7 の場合は別途ダウンロードで組み込む)を使って同じことをやってみた。

IISのGUIでルールを作る作業になるが、.htaccess の記述を参考にしてやってみたら動くようになった。

modx に付属する.htfile でfurl に関連するところは 以下の部分と思われる

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

書き換えルール: 渡された文字列$1を以下のパターンにして加工する
さらに 後ろにクエリーがついている場合はそのまま渡し、 下流の処理を行わない。

IISのGUI上のRuleでは これを Inbound rule として追加するが、その内容は以下のごとくなる。

Matches Pattern, “Regular expression”
“^(.*\.html)$” <= RewriteRule の最初の部分*1 Conditions : "Matches All" {REQUEST_FILENAME} "file does not exist"  {REQUEST_FILENAME} "Directory does not exist" Action type "rewrite" index.php?q={R:1} <= RewriteRule index.php?q=$1 に匹敵 Append ques : yes <= [QSA] に匹敵 Stop Processing: yes <= [L] に匹敵 当たり前ながら、同じ条件を記述しているので、それほど迷わずにできた。 はまりそうになったところはRegular Expression の部分で.htmlを明示している部分。これをやらないとloopしてしまう。 ほかのところの条件付けでもっと綺麗に記述できるかもしれない。 とりあえず、これでOK

subfolder がアクセスできない? IIS

Modxで運用するサイトであるサブフォルダーだけアクセスできない。ManagerからはFile Treeで見ることができるのだが、フォルダーの中のイメージファイルの画像をレンダリングしない。 フロントエンドから見ると、イメージファイルの部分でサーバーエラーになっているようだ。


Configuration Error

Description: An error occurred during the processing of a configuration file required to service this request. Please review the specific error details below and modify your configuration file appropriately.

Parser Error Message: It is an error to use a section registered as allowDefinition=’MachineToApplication’ beyond application level.  This error can be caused by a virtual directory not being configured as an application in IIS.

Source Error:


Line 36:             に、ASP.NET で使用されるセキュリティ認証モードの構成
Line 37:             を有効にします。-->
Line 38: 		<authentication mode="Windows"/>
Line 39: 		<!--
Line 40:             <customErrors> セクションは、要求の実行中にハンドル



” It is an error to use a section registered as allowDefinition=’MachineToApplication’ beyond application level.” というエラー表示が出る理由には二つある。

ひとつはアプリケーションをちゃんとバーチャルダイレクトリとして設定していないこと。 これは設定を見直せばよい。


で、今回の場合、サブフォルダのファイルがアクセスできない、ということで、後者だと考え探したらやはりsubfolderに入っていたweb.configがルートのWebFoldeを発見。 考えてみればあたりまえで、このサブフォルダー、以前のテストでスタティックなサイトをやはりIISで運営していたのをmodxでダイナミックなサイトにしようとそのままコピーしていたのだ、から当然web.configもコピーしてしまっていた、というわけだった。



後記:サブフォルダーにweb.configが存在すること自体、ありうる話(フォルダーごとに書き換えのルールを変えるなど。たとえばOutboundのurl情報からサブフォルダー情報を取り除く) なのでサイトの設定によっては必要なのだが、IISのGUIを使っていれば、このマネージメントはちゃんとなされて調和のとれたweb.configが作成される。

ModX cloud

Modx cloud というのをMODXのサイトで盛んに宣伝していたのは知っていたのだが、前回フォーラムにアクセスした際、「タダでアカウントをゲット」みたいなティッカーが表示され、それなら登録だけでも、とMODXCloud.comに登録してみれば、 Dev Siteを一本無料2本無料で使えることが分かったので、早速sandbox サイトを作ってみた。

これは便利だ。サーバーの構築を気にせず、簡単にサイトをリセットしたり、バージョンアップができるようだ。 スニペットやプラグイン、新しいアイデアを試してみたいときに気軽にアクセスしてイロイロ無茶やれそうな場所ができた。

MODXというのはコアを開発している人が基本的に二人なので、開発が細い。 その分、コニュニティで協力してやらなければならないのだろうが、MODXCLOUDのプロバージョンは他のプロバイダーよりも高めの料金設定なので、Financial なサポートをするのも 覚悟がいる。 バージョンアップの節目節目にdonationをするのが今の自分にできることだ。

modx Snippet を改良したときのメンテ法

昔に作ったmySnippet というスニペットがあるとする。 そしてそれを既にサイトのい何か所にも使っているような場合。


return $output

きも:modX のrunSnippetというAPIを呼び出して、パラメーターアレイには$scriptProperties というmodxのシステムアレイ変数を使えばmySnippetのプロパティセット及びタグ内部に使ったパラメーターがすべて新しいスニペットで使える。


modx をコマンドラインからアップグレードする。

現在 Official にリリースされているmodxのバージョンは2.2.5-pl だが、結構バージョンアップが煩雑に行われていて、そのたび、バグが取れたり、使い勝手がよくなってきていて、ますます気にいってきたりするわけだけれども、ファイルサイズもだんだんと大きくなってきており、アップグレードするたびに、zipファイルをまずは自分のパソコンにおとしてきてから解凍し、外部のhost server にすべてをftp で転送するとなると、やたらに時間がかかってしまう。

しばらく前にhost 側にsshでログインし、コマンドラインからファイル展開を直接行う方法を説明しているサイトを見つけ、この方法を使って重宝しているので、ここに記しておく。


上記ページはEvoluation 用に記述してあるが、revolution でも作業は同じ。

まずはホストサーバーのssh アクセスを有効にしてコマンドラインを使えるようにしておくのが第一歩。 自分の使っているホストはコンソールパネルからsshを有効にするだけで、コンソールパネル用のユーザーネームとパスワードでアクセスできるようになった。パソコンがLinux であれば、ターミナルから直接sshを起動、 Windows の場合はPuTTYとか、CygWinなどを実装しておく必要がある。

ssh username@server.com

First things firstで、まずは 既存のmodxファイルをサーバーのrootにバックアップしておく。 sshでログインすると最初はrootフォルダーにいるのだが、そのrootの下にpublic-htmlというフォルダーがあり、web アクセスができるのはこのpublic-html フォルダーから下の階層のみという仕組みになっているのを利用してバックアップをweb からはアクセスできないrootフォルダーにzipして保存してしまおうというわけ。(下のコマンドでは’~’ でroot指定している)

zip -r ~/my-modx-folder.bk.`date "+%Y.%m.%d.%H.%M.%S"`.zip my-modx-folder

これでrootフォルダー上に my-modx-folder.bk.date_of_backup.zip というようなアーカイブファイルができる。


これはmodxの最新版のダウンロードのページに行って、ダウンロードのリンク先をコピーし、これをターミナル画面上のwget コマンドに張り付けることになる。

wget path-to-the-latest-modx.zip


unzip modx-2.2.5-pl.zip

modx-2.2.5-pl というフォルダが作成され(何千という)ファイルが展開される。

これをmy-modx-folder にコピーするのは cp -r コマンドを使うわけだが自分の環境ではcp にAlias がかかっているらしく、f parameter をつけてやらないといちいち上書きしますか、ときいてくるはめになる。
cp -rf modx-2.2.5-pl/* my-modx-folder

cd core/config
chmod 666 config.inc.php






地下室においてあるPCのWEBServerはIISで動いている。 いや、Windwos7がはいっていたので、気軽な気持ちでIISを導入し、うごかしてみたら、設定が簡単だったのと、PHPのサポートが意外と充実していたので、サーバーとして使うことにしたのだ。すでに2年ほど支障なく動いている。

もっとも、アプリケーションはPHPで動くModXだ。 asp、aspx ベースではない。Visual Studioも(タダだし)起動画面までは見てみたのだが、C#もVBも覚えるつもりがなく、 結局JavaScriptやCSSだけでWEBサイトを構築できるPHPベースのModXでうごかしている。

ひとつだけ問題があるとしたら、IISベースではFriendly URLがサポートされていないこと。 IIS自体はFURLはサポートしているのだが、別途設定しなければならない。これがApache ベースのサーバーではModXに付属してくる.htaccess ファイルで簡単に対応できる。

世の中よくしたもので、IISでこの.htaccess をそのまま使えるツールが存在する。 Helicon Ape というユーティリティなのだが、サーバー3本までは無料バージョンでサポートされている。 これを入れて、ModX側のFriendly URLのシステム設定をOnにするだけで、FURLが有効になる。 するとそれまでは
http://mysite.org/index.php? id=36

この組み合わせで半年ほど快適に使ってきたのだが、ある日突然うごかなくなってしまった。 なぜか、最初はわからなかった。
で、いろいろ調べた結果わかったのが、IISの設定。このサイト、.net frameworkをつかっていないのだからいらないだろうと、.netのサポートをIISのメニューから前の日に外していた。外した途端に動かなくなったわけで、ホームページ自体はPHPがきちんと動いて表示するが、リンクが全部だめになったのは、要するにApeが作動していなかったので、
を Apeが以下に変換、
http://mysite.org/index.php ?q=”this page.html”
http://mysite.org/index.php ?id=36 に変換
という書き換えができなくなっていたわけ。 つまりApe 自体はIISの.net frameworkの上で動いていたわけだ。


Helicon Ape is implemented as managed IIS 7 module and can be installed as .NET module on any ASP.NET-compatible IIS version. It works transparently for both server and client and can even be installed on a shared hosting account without administrative access.

.NET module だと、しっかり書いてある。(おい)


ModX Revolution2.2 とIIS の相性

modXの2.2 がリリースされてから2ヶ月ほど経ったが、今回自宅のサーバーに導入してみた。 ホストサービスのほうで運用しているサーバーはApache なのだが、自宅はWindowsに実装したIIS7だ。

で、インストールしてマネージャ画面に行ってみたら、なんとリソースツリーがない。メニューとお知らせは表示されるのだが メニューをクリックしても空白の画面が出てくるばかり。 ログアウトもできない。


サポートフォーラムに行って2.2のエントリーを眺めてみると、結構類似の問題が発生している模様、 その中で

「どういう訳か、IISではJS とCSSを圧縮するとうまく行かない」という記述があり、対策としてはPHPMyadminなどで直接mysqlデータにアクセスし、System settingの当該項目を圧縮あり(1)からなし(0)に変更すればよい、との書き込みを見つけた。




JQueryの.load()を使ってみて complete: にはまった、という話

Query ライブラリーの中に.load()というmethodがあり、これを使うと、WEBページの一部に他のページをはめ込む、ということが簡単にできる。 たとえばmain.html というページがあり、 そこに<div id=”sections”></div> というセクションをつくっておき、 この部分にcontent1.htmlというページを差し込むためには
というjavascript 一行で済む。

これを使えば、content2.html, content3.html などというページを用意しておいて、Javascriptを使ってインターアクティブに(ページを全部ロードしなおすのではなく)ページの一部だけを差し替えることができるようになるわけだ。

これって、巷にいうAjaxだが、jQuery のAjax サポートは ajaxSetup というobjectががあって、この中で、Ajax関係の諸パラメーターを前もって設定することが可能、 で、とりあえず
beforeSend: function() {
$(‘#aContainer’).css(‘background’, ‘url(images/ajax-loader.gif) no-repeat center’);
とやって、 ページをロードしたときに、前のページの表示を消し、バックグランドにロード中お待ちくださいのイメージをはっておき、ロードし終わったときに、これを取り除く、という 動作を付け加えた。

ところが実際に動かしてみると、ロードが完了して新しいページが表示された後でもイメージが消えない。 ブラウザの開発ツールで見ると、スタイルシート上、バックグランドイメージがそのまま残っている。つまり、complete: の部分が動いていない。

これで2時間ほどハマったわけだが、 結論からかいてしまう。
実は.load()というコマンドにはコールバック機能があり、 これを使って、ロードされた画面の初期化を行うためのjavascriptを指定していた($(‘#sections’).load(‘content1.html’,’doSomething’)) のだが、これがcomplete: に指定された処理を無効化してしまうようである。 jQueryの.load と complete: の部分のマニュアルをじっくり読んでそういう結論に達した。

というわけで、Complete: event ではなく Success:event に動作をぶら下げて解決。.load()ではなく、.get()を使うとすっきりしそうだが、詳しく調べてないのでこれでよしとする。

beforeSend: function() {
$(‘#aContainer’).css(‘background’, ‘url(images/ajax-loader.gif) no-repeat center’);

$ajax を使うと、もっときめ細かいAjax操作ができるそうだが、現状ではこれで十分。

一応動いている証拠は ここに

ModX/WayFinderで作ったメニュのa href部分をjqueryで一括加工し、それぞれのアイテムをクリックすると、Jumpではなく、.loadが呼び出されるようになっている。

ModXと jQuery を使ったAjax, なかなか相性がよさそうである。