Matrix Secrets
The straight-forward guide to getting the most out of Squiz‘s
MySource Matrix.
Daniel Nitsche
http://matrixsecrets.com/
Matrix Secrets by Daniel Nitsche
Copyright © 2009 Daniel Nitsche
A special thanks to Avi Miller and Raena Jackson Armitage for slapping me
around a bit when required, Sandra Nitsche for saying that she would ―buy the
book even though she doesn‘t know what it‘s about‖, and to Laura Bos, for all
her help and support, and for putting up with coming third after this book and
my iPhone.
First Edition: November 2009
All rights reserved. The content, code, and concepts in this book may not be
reproduced, stored in a retrieval system, or transmitted in any form or by any
means, without the prior written permission of the publisher, unless explicitly
permitted.
The author has made every effort to ensure the accuracy of the information and
instructions in this publication, however the information in this publication is
provided without warranty. The author will not be held liable for any direct or
indirect damages caused by the instructions, code, or information contained in
this publication.
Squiz and MySource are trademarks of Squiz Pty. Ltd. Word, PowerPoint and
SharePoint are trademarks of the Microsoft Corporation. For readability
reasons, not to infringe on these trademarks, references to the trademark have
not been made in every occurrence.
CONTENTS
FOREWORD .......................................................................... 3
PREFACE ............................................................................... 4
THE MATRIX OPEN SOURCE COMMUNITY ......................... 7
The best things in life are free ............................................................... 8
It‘s open source, of course, of course ...................................................10
IMPROVE YOUR MATRIX EXPERIENCE .............................14
Set up your browser .............................................................................. 15
Work more efficiently with Matrix ....................................................... 19
Know your limits .................................................................................. 24
MANAGE YOUR CONTENT .................................................. 27
Strategies for managing content in Matrix ......................................... 28
Internal Metadata Schemas ................................................................ 34
Improve your user‘s web browsing experience .................................. 36
Dynamic Content ................................................................................. 40
Separate your Intranet from the public website ................................ 46
BEST PRACTICES FOR YOUR MATRIX WEBSITES ............ 48
Styling content ..................................................................................... 49
Make your websites load faster ........................................................... 54
Common configuration problems ........................................................ 57
Use fewer Design Customisations ....................................................... 63
BEST PRACTICES FOR YOUR MATRIX SYSTEM ................ 70
Warranties and the language file ......................................................... 71
Matrix defaults ......................................................................................72
System maintenance ............................................................................ 78
Plan to upgrade .................................................................................... 82
Default Login Design ........................................................................... 84
Search ................................................................................................... 90
ADVANCED LISTING TECHNIQUES ................................... 93
The image gallery Asset Listing ...........................................................94
More on the image gallery Asset Listing ...........................................100
Nested Asset Listings .......................................................................... 102
Asset typing (Paint Layouts) ..............................................................108
Search listings ..................................................................................... 113
ADVANCED MATRIX TECHNIQUES................................... 115
Matrix on your desktop ...................................................................... 116
Output to a content to a file ............................................................... 118
DIY problem solving ........................................................................... 123
Triggernometry ................................................................................... 125
The Matrix API.................................................................................... 132
2
Single licence copy
FOREWORD
MySource Matrix was probably one of the first pieces of software
I truly fell in love with. It was to be a torrid love affair, full of the
requisite ups and downs of any passionate romance. Like most, I
often longed for a simple set of instructions that would make
dealing with such a tempestuous beast easier and more
gratifying. I also suspect that I‘m writing completely the wrong
style of foreword for a technical book, but such is the nature of
MySource Matrix: with it, you are capable of building anything
and (as proven by Matrix users worldwide) everything.
This book contains some of the wisdom gleaned over years of
using and abusing MySource Matrix. It is designed to make your
life as a MySource Matrix user or administrator both easier and
more gratifying – by providing both simple and complex recipes
to common (and some not-so-common) problems.
When Dan and I both worked for Squiz, it was a mark of pride
when a particularly elegant solution was discovered. As we
challenged ourselves to build more complex, more personalised
and more interactive sites, the nature of these challenges became
more intense. As you develop your sites with MySource Matrix,
you‘ll discover that things you thought were difficult become easy
and you start to realise the sheer potential of what is to come.
I hope that this book helps you begin your journey with
MySource Matrix. And if you‘re already on your way, I hope you
find a few more ports along the shore.
AVI MILLER
Former MySource Matrix Product Evangelist
Squiz Pty Ltd
Single licence copy
3
PREFACE
Why this book is important
As we‘ll explore in It’s Open Source, of course, of course, Matrix
is open source, but perhaps not as you know it. At the time of
writing, aside from the occasional blog post, there are very few
publications on Matrix that are not produced by Squiz. Why is
this a problem? Because competition is healthy, and a lack of
choice means you‘re stuck with a single point-of-view and a
single set of documentation.
If you‘re unhappy with the official Matrix documentation, there
are no real alternatives. Matrix Secrets in no way replaces the
official documentation offered by Squiz1, rather it offers practical
advice on how to get the most out of your Matrix system, either
by giving best-practice advice, or showing you some techniques
that aren‘t in the manuals.
Who should read this book?
This book is written for people who work with MySource Matrix
on a regular basis, but don‘t have the time to determine the best
ways to use the software. The common problems, pitfalls and
configurations are covered, providing working and practical
solutions.
Matrix Secrets is not a replacement for training or the manuals
provided by Squiz. If you haven‘t already had training or read at
least some of the official documentation, I‘d encourage you to do
that first.
This book builds on the basic skills needed to use Matrix which
means I am assuming you already know how to navigate the
Matrix Administration Interface, create an Asset Listing, and
have a basic understanding of web technologies like HTML and
CSS.
1
http://matrix.squiz.net/download/documentation
4
Single licence copy
As you progress through the book, the examples and concepts
become more complex. Regardless of your familiarity with
MySource Matrix, the steps and screencasts with each set of
instructions should give you an idea of what‘s possible, even if
you don‘t exactly understand the technicalities of the steps being
described.
How to read this book
matrixsecrets.com
Throughout this book reference is made to screencasts, which are
presentations of the steps described in the examples. If the steps
aren‘t making sense to you, or you just prefer to see things rather
than read about them, the screencasts are for you.
As well as the screencasts, there is also a copy of the code used in
the examples, updated information, and a page listing errata. To
access all this:
1. Email [email protected] with the details of your
purchase.
2. Wait for an email with your login details.
3. Log in to http://matrixsecrets.com/book/
Version numbers
Version numbers are not specifically mentioned anywhere in this
book. This is because much of the advice is not specific to a
particular version of Matrix.
When a feature is used that is specific to a particular version of
Matrix, it is assumed you are running the latest version of
Matrix. For updates and a page listing errata, see
http://matrixsecrets.com/book/.
Single licence copy
5
Conventions
As you read this book, you‘ll find some parts of the text are
highlighted in special ways:
This is an interesting tid-bit, pointer or aside that‘s not
critical to the point at hand.
// this is a block of HTML, CSS, JS or PHP code
// this code is also at matrixsecrets.com
This is a reference to a screencast. These steps are also
available as a screencast at the URL specified.
Steps look like this:
1. This is a Label
2. This is a Screen Name
3. This is ―Value‖ (don‘t include the quotes)
6
Single licence copy
THE MATRIX
OPEN SOURCE
COMMUNITY
Single licence copy
7
THE BEST THINGS IN LIFE
ARE FREE
A community2 of Matrix users3 and developers is growing in
Australia, and internationally in the United Kingdom and New
Zealand. Currently, there are several channels of free support
available in various forms.
To keep up to date with what’s new in
Matrix
1. Read and subscribe to the developer newsletters which
contain upcoming features, new bugs and version info.
http://matrix.squiz.net/developer/dev-newsletters
2. Read the changelogs, which documents new bugs found,
and new features for each Matrix version that is released.
http://matrix.squiz.net/developer/changelogs
To get help on a specific problem:
1. Search for an answer using the Matrix Secrets search,
which indexes the official Matrix forums and bug tracker,
the unofficial list of keywords and several communitydriven sites. http://matrixsecrets.com/
2. Post your problem on the official Matrix Forums. Current
Squiz clients can get access to a client-only area on
request. http://forums.matrix.squiz.net/
3. Check if the problem is mentioned in the Matrix Bug
Tracker. Be warned this information is largely technical,
and should only be used if an answer cannot be found in
the changelogs (above) or on the support forums. Again
an account is required, but registration is free.
http://bugs.matrix.squiz.net/
2
http://community.squiz.net/
3
http://mysourceusers.com/
8
Single licence copy
A little help from your friends
At the time of writing, the number of public facing websites
running Matrix is estimated to be over 6004. What this means for
you and your organisation, is there are potentially hundreds of
other organisations already running Matrix that can potentially
offer advice or even share resources with you.
Most websites leave little clues as to what content management
system is driving them, whether it‘s the horrendous URLs of
Lotus Notes and Vignette, or the <form> element wrapping the
entire HTML page in a Microsoft SharePoint site. Matrix is no
different in this regard, and an easy way to check if a website is
running MySource Matrix, is to view the HTML source, and look
for this comment near the top of the source code:
<!—
Running MySource Matrix
...
Page generated: 1 January 2009 16:47:42
—>
Another reliable way to find a Matrix driven website is to look for
the occurrence of __data in the URL of any PDFs, images or
Word documents. A simple way to use this information is to do a
search on Google for ―inurl:__data‖. This simple search will
reveal a long list of websites that are most likely running Matrix.
If you were looking for more specific websites that run Matrix,
such as Australian Government departments and agencies, the
search could be restricted to those types of organisations using
―inurl:__data site:.gov.au‖.
Consider pooling the resources of these organisations to benefit
your own organisation, by establishing relationships, organising
regular meetings or user groups. These groups can be especially
beneficial because they can offer independent, unbiased and
potentially free advice on how to best work with Matrix.
4
http://matrixsecrets.com/users/
Single licence copy
9
IT’S OPEN SOURCE, OF
COURSE, OF COURSE
Matrix is open source, but maybe not as you know it. The Open
Source Initiative5 defines open source as “…a development
method for software that harnesses the power of distributed
peer review and transparency of process. The promise of open
source is better quality, higher reliability, more flexibility, lower
cost, and an end to predatory vendor lock-in.‖
Sun has much the same view6, and indentifies the following
benefits:

Cutting edge innovation.

Get the benefits at no cost up front.

High quality and value.

No lock-in means your investment is safe.

More certainty about your rights to use a product.
Let‘s compare Sun‘s definition of open source to the Matrix
environment (at the time of writing).
No lock-in means your investment is safe
Sun writes, ―Interoperable, open source products built on
standards mean you can choose a vendor… if your vendor doesn't
supply what you need, substitute another vendor's products or
leverage the open source code base itself. This dramatically
lowers your risk.‖ However, there are very few (if any)
independent developers who understand and can extend and
modify Matrix: there are just as few individuals/organisations
that can provide support or training or implementation services.
As with any application, an understanding of the underlying
technologies does not imply that a developer can immediately
develop for, and support, a product. This means unless you‘re in
5
http://opensource.org/
6
http://sun.com/software/opensource/enterprise.jsp
10
Single licence copy
a position to build up an internal team of Matrix experts (and
keep them!), your choices for support are limited.
Open source is about diverse communities
The Matrix community is very small. The fact that Matrix Secrets
is the first significant and independent publication on Matrix
should demonstrate this point. The barriers to contribute to the
product are high, and there is currently little encouragement for
the community to grow. This is because:

Although Matrix is reasonably widely deployed
throughout the Australian Government, it‘s still a
relatively unknown product in the wider community. This
means there is less of a market for third party providers
(or book writers) to service and create a business around.

It‘s not clear how developers can contribute to the
product, and indeed the developer documentation on the
Matrix site is largely out of date. Almost all development
is contributed by Squiz Labs.

It‘s not clear how developers will benefit from
contributing to the code, unless directly for their
organisation.
Open source is about sharing: ideas, code,
innovation
Sun argues that a project does not ―become open source simply
by publishing its source code‖, and Matrix is no exception. This
ultimately means Matrix loses the open source benefits of
constant cutting edge innovation, high quality, and value,
because there is not a large, active community of developers
contributing towards the product, and reviewing the code.
Single licence copy
11
More certainty about your rights to use a
product
If your organisation is running a warranty supported installation
of Matrix rather than the GPL version, you may be restricted
from developing or enhancing Matrix because:

your contract might not allow modification if it‘s in
competition with Squiz‘s products;

it may void your warranty.
This means if your organisation is using any of the supported
version features, like LDAP or Active Directory integration, you
may be locked in to a single vendor, even if you choose to
discontinue your relationship with the Squiz.
Help Make Matrix more open source!
It‘s unlikely that Matrix will become more open source without
the incentive to so, and this incentive needs to come from you,
the user! To help make Matrix more open source:
12

Make it known that truly open source software is
important to your organisation.

Consider your organisation‘s need to use the non-GPL
version of Matrix. Are the additional modules essential
for your requirements?

Insist any custom or paid development is contributed
towards the GPL version of Matrix. This ensures all users
can benefit from your organisation‘s investment in the
product, not just users running a supported version.

Take care when negotiating any licensing, service level
agreements (SLAs), and other agreements. Specifically
consider how these affect your organisation‘s right to use,
modify and/or extend the product.

Participate and contribute towards the current Matrix
community, and form your own industry-based
communities and networks.
Single licence copy

Use the bug tracker7. If you think you‘ve found a bug, see
if it‘s already been reported and if it hasn‘t, report the
bug, providing as much information as possible. You
won‘t find many other content management systems that
offer such an easy and transparent way to submit and
track bugs. Using the bug tracker makes Matrix more
open source because it encourages the sharing of ideas,
code, and innovation.

Support publications like this one!
At least the source is open!
Despite the shortcomings of the current Matrix open source
model, it still has many benefits over the model used by
proprietary, licence-based content management systems.
Consider that Matrix is written in PHP, a scripted programming
language which makes the source code completely available,
potentially for modification.
In the chapter Best Practices for your Matrix System, there are
several examples of minor modifications that can be made to
Matrix to improve the user interface. While this has the potential
to void a Squiz supported warranty, changes like these are
straight-forward where they would not even be possible with
many other content management systems.
7
http://bugs.matrix.squiz.net/ (free registration is required)
Single licence copy
13
IMPROVE
YOUR
MATRIX
EXPERIENCE
Just as you‘d adjust your keyboard, chair, monitor, and fluffy
dice, it‘s a good idea to reduce your chances of mental and
physical RSI by having a think about how you‘d like to work with
Matrix.
14
Single licence copy
SET UP YOUR BROWSER
Two browsers are better than one
Matrix shouldn‘t crash regularly, but it will crash sometimes,
often taking other tabs or windows of websites with it. Having a
second web browser that you can use exclusively with the
Administration Interface will make it easier to restart your
browser if required.
Firefox 3 and Internet Explorer 7 are the two best browsers to
use for the Matrix Administration Interface because they‘re the
most widely used and tested. Other browsers will work with the
Matrix Administration Interface, but aren‘t officially supported
or may offer a slightly slower or more awkward editing
experience. Mac users not satisfied with Firefox, may want to try
Camino8.
If installing another web browser is a problem, try
downloading Mozilla Firefox, Portable Edition9. This is a
version of the popular Firefox browser which can be installed
on your desktop with no administrator permissions required.
The Asset Map
Widen the Asset Map
Smaller screens mean lots of scrolling, especially where Matrix is
concerned. By default, Matrix‘s Administration Interface is
arranged in a way that suits smaller screens, but more recent
widescreen computer monitors can make better use of your
screen space. By default, The Asset Map is only 275 pixels wide,
so if you have some more real estate available on your monitor,
why not give yourself some room to move? To increase the width
of the Asset Map:
8
http://caminobrowser.org/
9
http://portableapps.com/apps/internet/firefox_portable
Single licence copy
15
Find your User asset, or the User Group you are a member of,
and on the Preferences screen, Customise the ―Asset Map
Width‖ to at least 400 pixels, or pick a value that suits you. Once
this has been done, you‘ll need to log out and log back in to see
this change.
The Asset Map can also be widened by undocking it. Double
clicking Tree One or Tree Two will pop the Asset Map open in
a new window, which can be resized as large as you like. This is
particularly useful if you have multiple monitors, because you
can move the Asset Map to your secondary monitor.
Teleport in the Asset Map
Teleporting helps you focus on a part of the Asset Map by, for
example, only showing assets under a particular Site. Using
Teleporting, we can change the Asset Map from this:
to this:
16
Single licence copy
You can Teleport to any asset via the Teleport screen, and return
to the normal view using the ―Restore to root folder‖ button:
Teleporting can also be customised per User or User Group so
that a user is automatically teleported to a specific asset when
they log in. To do this, for each User or User Group, on the
Preferences screen set the Asset Map Root Asset.
Use the second Asset Map
As well as Teleporting, another useful feature of the Asset Map is
is the second Tree. The second Tree, labelled Tree Two, is
useful when you need to work with two separate parts of the
Asset Map at the same time. For example, if you needed to move
some assets from one site to another, open the first site in Tree
One and the second site in Tree Two. Then, when moving an
asset, click Tree Two before choosing the destination for that
asset.
Cookies
If you‘re unable to log in, you‘re seeing an unfamiliar error, or
you‘re having trouble staying logged in, chances are that clearing
your Matrix cookies will help. Here‘s how to clear your cookies:

Firefox: ―Tools‖, ―Clear Recent History‖, set Time range
to clear to ―Everything‖, and ensure ―Cookies‖ is
checked.

IE 6: ―Tools‖, ―Internet Options‖, ―Delete Cookies‖.

IE 7 & 8: ―Tools‖, ―Delete Browsing History‖, ―Delete
cookies…‖.
After you‘ve cleared your cookies, try to log in again.
Single licence copy
17
In most browsers it‘s also possible to delete cookies for just
one website. Firefox can do this quickly using the Web
Developer‘s Toolbar10, which includes a handy ―Delete
Domain Cookies‖ option.
Learn the keyboard shortcuts
Keyboard shortcuts can make your Matrix editing experience
much faster. Here‘s a handy table to remind you of each
keystroke:
IE6
IE7
Firefox
(Win)
Firefox
(Mac)
Asset Map
text resize
(select the
Asset Map
first)
Ctrl
Shift
+/-
Ctrl
Shift
+/-
Ctrl
Shift
+/-
Ctrl
Shift
+/-
Other text
resize (with
the Asset Map
not selected)
Ctrl
and move
mousewheel up
and down
N/A
(Menu
option:
―Page‖,
―Text Size‖,
―Larger‖)
Ctrl
+/(version 3+
will zoom
rather than
text resize)
Command
+/-
Save/commit
Alt + s
Alt + s
Shift + Alt
+s
Ctrl + s
Acquire locks
Alt + a
Alt + a
Shift + Alt
+a
Ctrl + a
Release Locks
Alt + r
Alt + r
Shift + Alt
+r
Ctrl + r
10
http://addons.mozilla.org/addon/60
18
Single licence copy
WORK MORE EFFICIENTLY
WITH MATRIX
Quick search
See that box in the top right of the Administration Interface? It‘s
more useful than you might think! To jump directly to an asset,
in the Quick Search box, enter:
1. An asset ID (just the number, no #).
2. URLs (eg. http://example.com/about/something).
Or enter some search terms in the Quick Search box to have
Matrix return a list of all the matching assets. Matrix will find
assets with your keywords in the name of the asset, its contents,
or in its metadata.
Build your own Search Page
As your system grows, Quick Search may become less useful.
This is because the Quick Search isn‘t restricted to just your
section of the system: it returns results from any other site or
folder. On large systems, a search could return dozens or
hundreds of matching results.
Creating your own, personal Search Page will help you find an
asset, just like it does for users of your website, without having to
expose the page to the public. Search Page assets are far more
flexible than the Quick Search, as they can be configured to your
exact requirements. Search Pages can be set up to:

search for live assets only;

find assets that haven‘t been updated recently;

search for assets in a specific part of the system.
Here‘s how you can create your own Search Page. In this
example, we‘ll create one just for Standard Pages in a particular
site:
Single licence copy
19
Screencast: http://matrixsecrets.com/book/own-search-page
1. Create a Search Page asset and on the Details screen:
a. Set Root Nodes to the Site asset to be searched.
b. Set Asset Types to Search for to ―Standard
Page‖.
c. Select all the Search Statuses.
2. On the Search Fields screen:
a. Set Allow Empty Searches? to ―Yes‖.
b. Add a New Search Field Name called ―searchfield‖.
c. Add a Data Source of type ―Include All‖.
3. On the Edit Contents screen of the ―Initial Search Page
Layout‖ (which is a child of the Search Page asset):
a. Use the —select keyword— drop down to insert
―Input field for search-field‖.
4. On the Edit Contents screen of the ―Default Format‖ asset
(which is a child of the ―Type Formats‖ Folder) click the
―<>‖ button, and replace the existing HTML with:
<a
href="/_admin/?SQ_BACKEND_PAGE=backend_sec
tion&am_section=edit_asset&assetid=%asset_
assetid%&asset_ei_screen=contents&SQ_BACKE
ND_PAGE=main"
target="sq_main">%asset_name%</a>
Once the Search Page asset is set up, simply preview the asset
and enter a search term. Clicking on any of the results links will
take you directly to the Edit Contents screen for that asset.
Alternatively in the URL substitute asset_ei_screen=content
for asset_ei_screen=details to go to the Details screen.
20
Single licence copy
Bookmarks
Although this has to be set up without the help of Matrix,
bookmarking the assets you commonly work with will greatly
reduce the time it takes to begin editing an asset. Consider:
1. Adding bookmarks for your most commonly used assets.
Do this from the public-facing part of your website and
not from within the Matrix Administration or Simple Edit
Interfaces.
2. Going to the ―Organise Bookmarks‖, or ―Manage
Favourites‖ option in the bookmarks menu of your web
browser. We‘ll change the URL of each bookmark to link
directly to the appropriate editing interface:
o
To edit using the Administration Interface add
/_admin?asset_ei_screen=contents to the end of
each bookmark.
o
To edit using the Simple Edit Interface, edit the
URL to add /_edit?asset_ei_screen=contents to
the end of each bookmark.
Change screens quickly
An often missed but very useful navigation shortcut is the drop
down menu on the top right hand side of each screen, just under
the menu bar. This menu allows you to access the different
screens of the current asset, just like right clicking on the asset in
the Asset Map.
This unfortunately doesn‘t work if editing the contents of a
Standard Page — you‘ll have to use the Asset Map method or
click the ―Back to‖ breadcrumb to get back to the last screen you
were on.
Single licence copy
21
Keep the Matrix keywords handy
The keywords in Matrix are not always at hand when you need
them. Although the WYSIWYG and several other places within
Matrix have a handy drop-down list of keywords, this list is often
incomplete, and isn‘t available when editing the design.
Here is a basic reference for the most common keywords. A more
comprehensive and up to date list, which also includes the
common Design Areas is available at:
http://matrixsecrets.com/keywords/
Keyword
Description
%asset_assetid%
The unique ID of the current asset.
%asset_name%
The name of the asset.
%asset_short_name%
The short name of the asset (often
used in menus and breadcrumbs)
%asset_url%
The full URL of the current asset.
%asset_href%
The web path or relative link of the
current asset.
%asset_thumbnail%
The <img> tag of the thumbnail
for the current asset.
%asset_metadata_X%
The value of a metadata field for
the current asset. Replace X with
the case-sensitive name of the
metadata field.
%asset_created_readable%
The date the current asset was
created.
%asset_updated_readable%
The date the current asset was last
updated.
%asset_attribute_X%
An attribute for the current asset
where X is the name of the
attribute to print.
22
Single licence copy
Binoculars
Wherever you see an icon that resembles a pair of binoculars,
you can click to reveal an asset in the Asset Map. This is useful
when you want to locate where the asset is within the context of
the Asset Map. To reveal the asset‘s location in the Asset Map,
simply click the binoculars icon.
If the asset is linked in more than one location, clicking the
binoculars will bring up a list of assets, and you‘ll need to pick
which location you want to view.
Gotcha! After using this feature, all ancestor assets (parent,
grandparent etc.) will also be selected. While Matrix assumes
you want to move or clone the multiple assets you have
selected, what you probably want to do is go to the screen of a
single asset. To select a single asset, left click the label of the
asset as you normally would, then right click to access the
asset‘s screens.
Single licence copy
23
KNOW YOUR LIMITS
The flexibility of Matrix is its main strength and its main
weakness. There‘s almost always several ways to solve a single
problem, without a clear indication of which way is best. Until
now, we‘ve focused on being more efficient with what you
already know. However, being more aware of what Matrix can do
will help you know when to press on with a particular task, and
when to ask for help.
Automating repetitive tasks
Perhaps you find yourself performing the same sorts of tasks
repeatedly – your site might contain content that generally needs
to be formatted in a similar way, contains much of the same
information, or needs to be configured in similar ways. Event
registration forms, staff profiles, or monthly reports, are all good
examples of this kind of content.
There are several features in Matrix that can help you automate
repetitive tasks. If you have a task that looks like it might be a
good candidate for automation, ask yourself two questions:
1. Will the time it takes to automate a task significantly
reduce the overall time it takes to finish the project?
2. Can the required automation be completed before the
project needs to be completed?
If the answer to both questions is yes, automation can probably
save you some time and effort. Let‘s look at some of the more
common ways we can automate tasks in Matrix.
Files/images
The Bulk File Import Tool (accessible from the ―System Tools‖
menu) can create many assets in one hit such as File, PDF, Word
etc. This tool can save a lot of time, and is worth using for
uploading more than 5 files at a time.
24
Single licence copy
Asset Listings
If it‘s in Matrix, it can be listed! Asset Listings can be used to
create almost any kind of list you need — staff profiles, lists of
documents, image galleries and more.
Deciding on whether to use an Asset Listing comes down to how
much effort is required to set up the list versus how long it would
take to manually create the same list. If you only have five items
in your list, and it‘s unlikely that this list will change, perhaps it‘s
easier to create this list by hand. If your list contains many items
that change often, an Asset Listing is probably the better choice.
The more consistent a website can be in terms of its presentation
and layout, the easier it is to list. Imagine you‘d like to create a
list of related items for each page, such as one or more lists of
related reports; if this list is always at the bottom of a page, it‘s
easy to nest this into the page‘s design so it can be listed
automatically. If the list is often split into several pieces and
spread across each page, it‘s nearly impossible to list
automatically.
Sorted? A list of assets needs to be sorted in a particular and
consistent way. Sorting by name, published date, or by a
particular attribute are common choices. In most cases, a list
of assets can also be sorted by the order they appear in the
Asset Map.
External tools (Data Sources and Web Services)
The Squiz Supported version of Matrix can integrate with many
other applications, allowing you to automatically import data
from, or export data to, other applications and share data or
functionality between applications.
Put simply, anything that uses a database can potentially be
integrated with the Squiz Supported version of Matrix. At the
time of writing, this integration is unfortunately absent from the
GPL version.
Single licence copy
25
Custom development, new versions
Despite being packed with features, there are some things Matrix
just can‘t do — or at least can‘t do well. For the right price, Squiz
can provide custom development to meet your specific
requirements. The advantage of custom development is that
Matrix can be tailored to provide exactly what your organisation
requires, making it easier to work with your content on a regular
basis.
26
Single licence copy
MANAGE
YOUR
CONTENT
Single licence copy
27
STRATEGIES FOR MANAGING
CONTENT IN MATRIX
It‘s difficult for Matrix to fulfil the role of a content management
system without putting some thought into how your organisation
will use the system. Help your organisation use Matrix more
effectively by encouraging users to share and reuse content.
Encourage content sharing
If practical to do so, give your Backend users at least read
permission to the entire system, not just the sites they work with,
because this will allow users to:

browse through other websites in your organisation to see
if there is any content that can be reused;

learn how other users have set up their site.
Encourage other business areas to reuse the content and
functionality in your site by creating a centralised shared content
folder. A shared content folder makes it clear which resources are
appropriate to be reused and provides greater opportunity for
other users to keep that content current.
Documents
Before we look at managing documents in a similar way to
managing images, you may want to consider that the best way to
manage documents on a website is not to use them at all.
Documents are inherently less shareable than other assets in
Matrix because they can‘t be directly edited, and because they
can‘t be transformed or integrated into a specific design. In fact,
just about all you can do with documents is link to them.
Documents are also:
28

more difficult to search for;

often not written in a format suitable for the web;

almost always less accessible than web pages, take longer
to download, and require additional software to open.
Single licence copy
For more good reasons not to use documents, see Jakob
Neilsen‘s alertbox article PDF: Unfit for Human
Consumption11, almost all of which also applies to Word
Documents as well as PDFs.
Where to put your Documents
When documents are required, they need to go somewhere.
Generally the two options are to put your documents:
1. Under the top-level Media folder or under an equivalent
Media folder within a section of your system. It makes
sense to categorise documents into sub-folders under this
folder, just as you would with a shared network drive. For
example, documents could be categorised by file type,
year, topic, or event.
2. Under each asset that links to the document. This means
if the Annual Report page links to annual_report.pdf,
the PDF asset would be a child of the Annual Report
page. If the PDF asset is used on other pages, it should
also be linked as a child of those pages.
Each method has its own pros and cons, and you may even want
to consider using one method for one site, and the other method
for another site.
11
http://www.useit.com/alertbox/20030714.html
Single licence copy
29
Documents under each asset
Pros
Cons
 It‘s immediately obvious
which documents relate to
an asset, increasing the
chances of that document
being maintained.
 The Asset Map becomes
more cluttered with
documents and each
document may need to be
hidden from menus.
 Documents don‘t rely on a
folder structure to be
found. If you can navigate
the website, you can
probably find the
document.
 Lacking a holistic view of
all a website‘s documents
means content reuse and
sharing is less likely, and in
fact, the duplication of
documents is more likely.
Documents in the Media folder
Pros
Cons
 All your documents are in
the same place.
 You have to use the
Linking screen to
determine where a
document is being used.
 Documents can be
categorised in any way you
please.
 It‘s easier to audit what
documents are in the
system.
 The context of a document
is less obvious.
 Large organisations will
need to work harder to
keep permissions up to
date for this folder.
Having your documents and eating them too?
It is possible to take a hybrid approach and link documents both
under the Media folder and under the child of the page that is
using the document. However, while the previous two methods
are easily enforceable through the use of Triggers (see
Triggernometry), a hybrid method is more difficult to enforce.
Assuming we did want to enforce a hybrid method, the two
problems would be:
30
Single licence copy
1. If a document is created under the Media folder, Matrix
can‘t automatically determine where that document is
being used, and so can‘t automatically link this document
under the appropriate assets.
2. If a document is created under the asset which is linking
to it, Matrix can‘t automatically determine which subfolder of the Media folder is appropriate to use.
Image Varieties
In most organisations, especially large ones, it can be difficult to
keep track of all the images used on a website. It can be
especially hard to track down an original source image when that
image has been reduced to specific dimensions for use on the
web.
If your organisation‘s current method for storing source images,
perhaps on a network drive, isn‘t meeting your business
requirements, you may find it easier to use Matrix to store these
images by creating an image repository.
Let‘s look at creating a basic image repository for these assets. In
this example, we‘ll assume your images are all being stored
under a single parent Folder asset, such as the Media folder.
1. Upload all your images under your designated Media
folder.
2. For each Image asset, go to the Varieties screen, and
create a new Variety:
a. Name: ―thumbnail‖ (for example).
b. Variety Type: ―Resize Current Image‖.
c. Constrain by: normally, you‘ll want to select
―Width‖ and enter a number in pixels.
The constraint is where the magic happens. Decreasing the size
means that 3 MB Christmas drinks photo can be reduced to a
size that won‘t take an hour to download from an iPhone.
Single licence copy
31
Look under the original image uploaded, and there will be a new
Variety asset with the name you specified in step 3a. You can use
this asset as if it were a normal image asset anywhere in the
content. The best part is: because the original image is in the
system, other Matrix users don‘t have to find this image if they
want to reuse it, and they can create other varieties of any size for
their own use.
As we cover in Triggernometry, if you have a lot of images
you can create a Trigger that will create one or more varieties
for you automatically when an image is added to the Media
folder.
The __data URL
All your File assets, such as images, PDFs and Word documents,
which are Live with Public Read permission, will have a URL
containing __data. As ugly as this may be, it‘s important because
it ensures documents are loaded without having to check for
permissions and asset status, meaning they will load as quickly
as possible. If you absolutely must have a cleaner URL, for
example, if you wanted to publicise a direct link to a PDF, there
are a couple of options you can use to change it:
1. Use
the
―Remap
Manager‖
(under
―System
Management‖) to create a redirect from your preferred
URL to the File asset.
2. Set the file to inherit its URL from the parent asset, rather
than using the __data directory. This can be done on the
Details screen, by setting Allow Unrestricted Access
to ―No‖.
32
Single licence copy
Sorting documents
Aside from manually moving assets within the Asset Map, assets
can be sorted in a particular order, such as alphabetically.
To sort a group of assets by their name, under ―System Tools‖
(see above) select Asset Sorting Tool. Then set:
1. Parent, for example, to a Folder containing your
documents.
2. Sort Type to ―Asset Field‖.
3. Sort Field to ―Short Name‖.
Single licence copy
33
INTERNAL METADATA SCHEMAS
Metadata Schemas add a large degree of flexibility to a site
within Matrix. By using a Metadata Schema, it‘s possible to add
additional information to an asset, such as summaries, keywords
or dates. In some cases, a Metadata Schema can even be used to
create a kind of custom asset.
To create an internal Metadata Schema, create a new Metadata
Schema, and:

on the Details screen set the Show On Frontend option
to ―No‖ (this can also be set per field);

apply this schema to a site or group of sites.
Setting Show On Frontend to ―No‖ means the schema and its
fields won‘t be visible as <meta> elements in the HTML of a
website.
Now let‘s look at some practical uses for this new internal
Metadata Schema. For each example, simply create a new field
for each type of information to store.
Notes, to-do list
In a team:
 track the work that needs to be completed on a page;
 make notes about content that needs to be
changed/updated;
 comment on the existing content of a page.
System wide: consider making notes from an internal
Metadata Schema more obvious by adding these notes to
your Simple Edit layout.
34
Single licence copy
Quality assurance
When migrating some content from a new system or performing
an accessibility audit on an existing site, add a Select Metadata
Field to your internal Metadata Schema to store the possible
options, for example In Progress, Completed, Error, and so on.
Review date
Keep track of when an asset should be updated, for example six
months from the time the asset was last updated, by creating a
date field for your internal Metadata Schema. This process can
be automated using Triggers (see Triggernometry).
Custom assets
Perhaps the best use of internal Metadata Schemas (next to their
actual use of storing metadata), is the ability to associate custom
data with a single asset or group of assets, and then display that
data in a sensible fashion on a website. Standard Pages can
become formatted reports. News Items can become products.
User assets can become staff profiles with biographical details
and photos.
Internal Metadata Schemas are only half the story. If the data
you‘ve just learnt how to capture now needs to be presented
on your website, you‘ll want to read Asset Typing (Paint
Layouts).
Single licence copy
35
IMPROVE YOUR USER’S WEB
BROWSING EXPERIENCE
Many of the accessibility and usability problems that may arise
on your website can‘t be fixed or even detected by a content
management system. Knowing where Matrix can‘t assist with
these issues will help you improve the overall experience a user
has when they visit your website.
Shorten URLs
http://example.com/about-our-great-company could easily
be just http://example.com/about. Matrix does a fair job of
helping in this respect, but there is room for improvement.
The Web Paths screen lets you change the URL for each asset
without breaking any links, as Matrix will automatically redirect
users who have bookmarked the old link. Be concise without
losing meaning. Shorter URLs will help with:
1. Radio, TV and print advertising, because the URLs are
easier to note down or describe verbally.
2. Users remembering the address.
3. Search engine rankings.
For important web pages that have longer URLs like:
http://example.com/reports/2009/annualgeneral/report,
consider creating a shortcut to this page, using a Redirect Page:
1. Create a Redirect Page asset, in the top level of the Site
(ie. as a child of the Site asset), and give it an appropriate
name like report09.
2. Under Location, choose the asset to redirect to.
If you preview the Redirect Page, you will automatically be
redirected to the asset chosen. Now you can distribute this short
URL as it appears on the Web Paths screen.
36
Single licence copy
Alternatively, use the Remap Manager to the same effect. The
Remap Manager (under ―System Management‖) is more
appropriate for system-wide remaps, but if you only want to
maintain a small list of redirects, you may find it easier to
keep track of Redirect Pages in the top level of your site.
Headings for headings
Ensure your content has an appropriate semantic structure. This
means:

headings should be used to structure a page using the
―Heading 1‖ drop-down and not by changing the font
size, weight or colour;

use the ―Ordered List‖ icon for a list of items with a
progression or sequence, and the ―Bulleted List‖ icon for
a list of items without an order;

use the ―abbr‖ icon for abbreviations and the ―acro‖
acronyms;

when inserting a table, fill in the ―Summary‖ attribute,
and use table headers by checking the ―First Row‖ and
―First Column‖ checkboxes.
You can find out more about the importance of semantically
meaningful content at WebAim12.
Avoid documents
Documents are almost always less accessible than a Standard
Page because they aren‘t specifically designed to be displayed in
a web browser. Standard Pages and other non-File assets will
generally:
12

be easier to update and maintain;

be more findable/searchable;

have a greater chance of being read.
http://webaim.org/techniques/semanticstructure/
Single licence copy
37
Click where?
Knowing how to write for the web is a specific skill that differs
from writing content for other media. Apart from spell checking,
Matrix can‘t assist you at all in this area. Take a course, or read
up on what it takes to write great web content.
For a practical and informative guide to writing for the web,
check out Dey Alexander‘s one day Writing for the web
workshop13 in Australia.
In New Zealand and online, Rachel McAlpine14 offers well
regarded courses in writing for the web.
Images
Do
Don’t
 Include some descriptive  Use an image to replace
alternate
text
using
text. Where possible, use
standard HTML.
Alternate text on the
Insert
Image
window.  Neglect to add an ―alt‖
Enter the alternate text as
attribute when first adding
if you were describing the
an image to Matrix. These
image over the phone. If
get used as the default for
purely decorative, leave
new images.
this blank, or enter a single
 Upload a large image file
space.
and resize the image using
 Optimise your images for
its HTML dimensions. Use
the web by resizing and
a correctly sized image or
compressing the image so
an Image Variety instead.
it‘s faster to download.
13
http://deyalexander.com.au/services/writing-workshop.html
14
http://www.contented.com/about.php
38
Single licence copy
JavaScript is not the answer
JavaScript to enhance the content of your site is fine; JavaScript
to display or link-to your content is not. As not everyone can - or
does - have JavaScript enabled, insist that your content can be
accessed regardless of JavaScript. Try disabling JavaScript in
your browser and see if your website still works:

Firefox (Windows): ―Tools‖, ―Options‖, ―Content‖,
uncheck ―Enable JavaScript‖.

Internet Explorer 6/7: ―Tools‖, ―Internet Options‖,
―Security‖, ―Custom Level‖, ―Scripting/Active Scripting‖
set to ―Disable‖.

Firefox (Mac): ―Edit Preferences‖, ―Options‖, ―Content‖,
uncheck ―Enable JavaScript‖.
Like to know more? For some great information on
accessibility, see WebAIM‘s WCAG checklist and reference15
and the W3C‘s Web Content Accessibility Guidelines (WCAG)
2.016.
For informative analysis of current usability issues, see the
regular column of the Jacob Neilson: alertbox17.
15
http://www.webaim.org/standards/wcag/checklist
16
http://www.w3.org/TR/WCAG20/
17
http://www.useit.com/alertbox
Single licence copy
39
DYNAMIC CONTENT
As with most content management systems, Matrix can be
configured to dynamically hide and show content based on
certain conditions. What might come as a surprise is the number
of ways in which content can be hidden or shown, including
permissions, the current URL, or even which website a user
previously visited. Let‘s look at the many different options Matrix
offers for dynamic content.
Hide content using permissions
First, there is standard Matrix functionality that allows assets to
be accessible or not, depending on the permissions of the current
user. Let‘s expand on that.
Screencast: http://matrixsecrets.com/book/div-permissions
Imagine a website that uses an Asset Listing to list products for
sale. Product prices and specifications are often changing, so a
user needs to be able to easily edit these products. In this
example, we could modify the Asset Listing by:
1. Editing the contents of the ―Default Format‖ and:
a. Insert a new DIV below the existing DIV which
prints asset information (in this example, product
specs).
b. Add the following to the new DIV:
<a href="%asset_href%/_edit">Edit this
product</a>
2. In the Asset Map, expand the ―Default Format‖
Bodycopy, to see the child assets.
3. On the Permissions screen of the new DIV, remove any
Read permissions for the Public User, and specifically
―Deny‖ Read permissions for the Public User.
40
Single licence copy
An ―Edit this product‖ link will now be displayed below each
product in the list and the link points to the Simple Edit interface
for that asset. Some ways we could use this technique include:

displaying a link to your organisation‘s Intranet;

displaying links to tools for editing/adding content.
This method can also hide content from logged in users, and
can be applied to any nested asset, not just DIVs.
Hide content using URLs
Hiding content using URLs allows different information to be
presented to a user depending on how they navigated to a
particular asset. This becomes useful when the same asset in
Matrix is linked to multiple locations, and therefore has multiple
web paths. For example, if you had a TV advertising campaign,
you might link an asset under a TV folder, giving it two URLs:
 http://example.com/contact
 http://example.com/tv/contact
Then, if ―tv‖ is in the URL of the current asset, we can assume the
user is responding to your TV campaign, so we can print some
additional information that is only relevant to these users.
Hide content using URLs in Designs
To hide content using URLs, edit the Design File of a Design and
add the code below to conditionally hide or show content. This
condition can be used multiple times within a Design, as long as
the id_name is different for each area.
Screencast: http://matrixsecrets.com/book/hide-on-url
<MySource_AREA id_name="HideOnURL"
design_area="show_if">
<MySource_SET name="condition"
value="server_variable"/>
Single licence copy
41
<MySource_SET name="condition_server_variable"
value="SERVER_NAME" />
<MySource_SET
name="condition_server_variable_match"
value="intranet.example.com" />
<MySource_THEN><h1>We're
Bankrupt!</h1></MySource_THEN>
<MySource_ELSE><h1>Everything's
ok</h1></MySource_ELSE>
</MySource_AREA>
This example prints the heading ―We‘re Bankrupt!‖ if the page is
accessed from intranet.example.com, otherwise the heading
reads ―Everything‘s ok‖.
Set Designs and Paint Layouts
To provide a text-only or printer-friendly version of the current
asset, we can manually specify Designs and Paint Layouts by
appending the following suffixes to a URL:

?SQ_DESIGN_NAME=design_name or;

?SQ_PAINT_LAYOUT=paint_layout_name
Typically, you‘d provide a method for swapping these with a link
in your design, such as:
<a href=”%globals_asset_href%?SQ_DESIGN=print”>Printfriendly version of this page</a>
which when clicked, would change the current Design to the
Design named ―print‖. Design names are on the Settings screen
of an asset, as the Design code of the ―Create New User Defined
Design‖ section. Paint Layouts are similarly on the Lookup
Settings screen.
Because we‘re changing the Design entirely, there are any
number of ways we can hide content using this method, such as
by not printing Design Areas, or by adding additional CSS to hide
elements on the page.
42
Single licence copy
Designs can be applied for the user‘s entire session by using:
?SQ_DESIGN_NAME=design_name&SQ_ACTION=set_design_name
and cleared using: ?SQ_ACTION=clear_design_name
Hide content using Server Variables
As well as Content Hiding Using URLs in Designs, content can
be hidden in a number of additional ways. How many ways?
Essentially everything that is a PHP server variable18 can be set
as a condition in the show_if. The full list includes some
interesting options for hiding content such as:

HTTP_REFERER – the previous page the user was just
on, that is the page that referred them to your site. This
could be used to welcome users from an industry site,
present some content for Google users, or reduce bounce
rates by offering tailored content for users.

HTTP_USER_AGENT – used sparingly, this could
encourage users to upgrade their browsers for a
particular application, or warn them of a security issue in
their current browser.

REMOTE_ADDR – is the IP address of the user visiting
your website, and can be used to show special content to
users from within your organisation or hide content from
users outside your organisation.

REQUEST_METHOD – useful for determining if the user
has just submitted a form, in which case the method will
probably be POST.
Let‘s look at an example of using Server Variables, specifically
the REMOTE_ADDR, to hide content. In the following example,
if the IP address of the user is 192.168.1.1 (a local IP address), the
after hours support phone number is shown, otherwise this
phone number is hidden.
18
http://php.net/reserved.variables.server
Single licence copy
43
<MySource_AREA id_name="internal_ip_address"
design_area="show_if">
<MySource_SET name="condition"
value="server_variable" />
<MySource_SET name="condition_server_variable"
value="REMOTE_ADDR" />
<MySource_SET
name="condition_server_variable_match"
value="192" /><!—- matches 192.* addresses —>
<MySource_THEN>
Contact Support:
+61 2 5555 5551 (Business hours only)
+61 4 5555 5555 (After hours)
</MySource_THEN>
<MySource_ELSE>
Contact Support:
+61 2 5555 5551 (Business hours only)
</MySource_ELSE>
</MySource_AREA>
Hide content using URLs in a Paint Layout
Paint Layouts can also hide content using Server Variables on the
Conditional Keywords screen of each Type Format. To replicate
the previous example, create and apply a new Paint Layout, and
on the Conditional Keywords screen of the ―Default Format‖:
Screencast: http://matrixsecrets.com/book/hide-on-ip
1. Add a new Condition Type of ―Server Variable‖ named
―show_mobile‖.
2. Set Server Variable to ―REMOTE_ADDR‖.
3. Set Pattern to 192 (which would include all IP addresses
in the 192.* range).
Then, on the Edit Contents screen of the ―Default Format‖ add:
44
Single licence copy
%asset_contents%
<p>
Contact Support:
<br>+61 5555 5551 (Business hours only)
%begin_show_mobile%
<br>+61 5555 5555 (After hours)
%end_show_mobile%
</p>
Single licence copy
45
SEPARATE YOUR INTRANET
FROM THE PUBLIC WEBSITE
For security and scalability reasons, you should strongly consider
keeping intranet content in a separate installation of Matrix,
safely tucked away in your internal network. In a single Matrix
installation, there are several ways you can accidently expose
your intranet content publically, because keeping intranet
content secure in Matrix is typically left up to each user to
manage. If you‘re not yet convinced, let‘s look at security and
scalability issues.
If you‘re already in the precarious situation of hosting public
and private content in a single Matrix system, the best way to
split the content is to make a backup of the original system,
restore this system to its new location, and delete all the
assets that aren‘t required in both systems.
Security
Files and the __data directory
When permission checking is not required for files, Matrix stores
these files in the __data directory. This reduces the load on
Matrix and serves the files much faster to the user, so chances
are you‘ll want to use this facility for files on your Intranet.
However, any document in the __data directory is available to
all domains Matrix is responding to, not just the domain the
document is associated with. This means while a URL of
http://intranet.example.com/__data/example.pdf is not
accessible because the URL is blocked externally, it may still be
accessible via a public facing external site at a URL of:
http://www.example.com/__data/example.pdf
Finding these files still requires that a user can guess the URL of
the asset, but this is not a good method of securing content.
46
Single licence copy
Accessing an asset by its ID
If the ID of an asset is known, it can be accessed from any
domain name associated with your Matrix system, simply by
appending the asset ID as a query string, for example,
http://example.com/?a=1234. This is similar to the __data
issue, where you might want to set Public Read permissions on
your Intranet content, and restrict the content via a URL only.
Backend Users
The potential for cross-site scripting and session stealing is much
greater from within the Matrix Administration Interface than it
is from the frontend because users can insert HTML, CSS and
JavaScript into any asset. If there are sensitive parts of your
Intranet that not all Backend Users should be able to see, use a
separate installation for your Intranet.
And more?
As we looked at in It’s Open Source, of Course, of Course, the fact
that Matrix is an open source product does not necessarily mean
it‘s more secure. There is little to encourage Squiz to publicise
new security exploits, nor is there any guarantee that there are
not any current exploits.
Also consider that Matrix relies on many other pieces of software
to run such as the operating system, Apache, PostgreSQL and
PHP, and therefore is only as strong as its weakest link.
Scalability
Generally the more assets in a Matrix, the slower the system will
run. The same goes for the number of users using the
Administration Interface: more users means greater load on the
system, leading to a longer load times. Having two instances of
Matrix is one way to manage the issue of an underperforming
system. While an organisation‘s intranet presence is typically
much larger than its internet counterpart, it can be one of the
most sensible ways to split an organisation‘s content.
Single licence copy
47
BEST
PRACTICES
FOR YOUR
MATRIX
WEBSITES
48
Single licence copy
STYLING CONTENT
In Microsoft Word, it doesn‘t make sense to set the font, size, and
colour of each piece of text in a document. Heading, paragraph
and page styles are set up so that the focus is on the content
rather than the style of that content, and in Matrix the same is
true. Users should have a number of styles ready to use via the
WYSIWYG editor so that each piece of content may be styled
using CSS rather than by directly inserting font, colour or size
changes. This also ensures that styles can easily be changed on a
site-wide level.
On the next page we‘ll look at how to configure styles
appropriately in your website‘s style sheet. However, let‘s first
look at the three ways these styles can be applied, all of which are
done on the Edit Contents screen of a Standard Page:
1. The WYSIWYG provides a drop-down menu of styles
which can be applied to a portion of the text in the
WYSIWYG. Select the text to be styled first, then choose
the style from the drop-down menu.
2. The ―Properties‖ window
of a DIV has a Name
field which can be
changed from ―Content
DIV XX‖ to an ID to
identify the DIV. IDs
need to be unique per
page, otherwise that
page‘s HTML will not be
valid.
3. Also on the ―Properties‖
window is the Class
field. One or more classes
can be typed into this
field, with each class
separated by a space.
Single licence copy
49
Once class names and IDs are assigned to each DIV, the content
of these DIVs can be styled to:

Align images to the left or right of text.

Apply margins, padding, or borders.

Colour, resize, bold, or italicise text.

Allow extra interactivity using JavaScript. For example
resizing, reordering, moving, and hiding the DIV or its
contents.
Remove WYSIWYG options
Don‘t give your users the freedom to style content however they
want… or they‘ll style content however they want! You probably
don‘t want to give your users access to many of the options the
default Matrix WYSIWYG editor provides, like font colour and
size.
To start with a minimal set of editing options, under ―System
Configuration‖, ―Global Preferences‖, uncheck everything under
WYSIWYG Plugins, except:

Matrix Insert Anchor

Special Chars

Table Editing

Insert Link

Matrix Apply Style

Spell Checker

Listing

Matrix Insert Link

Matrix Accessibility

Keyword Replace

Matrix Insert Image

Help
You could also turn on ―Misc Accessibility‖, and ―General‖ but
you should assess how many of your users will actually use these
options. The fewer options you give your users, the less confused
they will be.
50
Single licence copy
By setting these options in the System Configuration, you are
changing the default WYSIWYG options for all other users
and groups. These options can also be set for each User
Group or User on the Global Preferences screen of these
assets.
Configure your style sheet
As we‘ve just removed a whole lot of style options from the
WYSIWYG, we need to add these back in the form of meaningful
styles. Matrix should pick up the styles in the style sheets of the
current Design, but you won‘t want to use all of them. Using the
Styles screen of the Design, specifically pick the styles that are
appropriate for your users to use, and ensure the names of each
style are such that they their purpose will be clear to your users.
Good and bad styles
Good styles have meaning rather than format. This is important
for accessibility because it focuses the user on the meaning of the
content rather than its appearance. Because the style is not tied
to the content‘s meaning, its appearance, such as colour and size,
can be easily changed and maintained. For example:
Good
Bad
h1 {font-size:2em;}
.heading {font-size:2em;}
.note {font-size:.8em;}
.small {font-size:.8em;}
.warning {color:red;}
.red {color: red;}
.important {font-weight:
bold;}
.bold {font-weight:bold;}
The C is for Cascading
So that we can easily apply styles in the ways we‘ve just seen, let‘s
create some styles that can be applied via a DIV‘s class or ID. For
example:
Single licence copy
51
/* Float all images in this DIV to the right */
div.feature img { float: right; }
/* Float images in DIV left with margin, border */
div.profile img { float: left; margin-right: 1em;
border: 1px solid black; }
/* Highlight DIV with padding and font-size */
div.feature { padding: 2em; font-size: 1.1em; }
/* Highlight warning. Strong must be used as
colour shouldn’t be the only way the content
conveys importance (for accessibility). */
div.warning { padding: 2em; font-size: 1.1.em; }
div.warning strong { font-weight: normal;
background-color: #FA8072; }
Diagnostic styling
An interesting way to maintain some control over the styles used
on your website, and also to enforce certain accessibility
standards, is through a diagnostic style sheet. The basic premise
of a diagnostic style sheet is to inform your users via large bright
red text that there is a problem with the current page.
For example this CSS:
img[alt=””], font, center {
color: red;
font-weight: bold;
margin: 1em;
padding: 1em;
font-size : 2em;
border: 4px solid red;
}
would display a large red border around images that are missing
alt text, or HTML elements like that should no longer be used
like <font> and <center> tags.
52
Single licence copy
Using CSS selectors, these conditions can match anything you
like. Here are some more examples to get you started:

http://code.google.com/p/qa-style-sheet/

http://meyerweb.com/eric/thoughts/2007/09/07/d
iagnostic-styling/
To ensure these styles are only seen by a certain group of users
internal to your organisation, we can restrict the printing of these
styles based on the IP address of the currently logged in user:
<MySource_AREA id_name="internal_ip_address"
design_area="show_if">
<MySource_SET name="condition"
value="server_variable" />
<MySource_SET name="condition_server_variable"
value="REMOTE_ADDR" />
<MySource_SET
name="condition_server_variable_match"
value="192" /><!—- matches 192.* addresses —>
<MySource_THEN>
<style type=”text/css”>...</style>
</MySource_THEN>
</MySource_AREA>
Single licence copy
53
MAKE YOUR WEBSITES
LOAD FASTER
Most enterprise content management systems need a hand when
it comes to speed, and Matrix is no exception. While a slow
Administration Interface may cause your organisation
headaches, this pales in comparison to the impact a slow website
will have on your organisation.
Website optimisation
The Yahoo Developer Network19 has an excellent and
comprehensive guide to reducing the time a website takes to
load. Some of the recommendations that can easily be applied to
your Matrix system are:
Combine all CSS into a single external CSS file
 Use <link rel="stylesheet" … /> (instead of
@import) directly after the opening <head> tag.
 Use the CSS File asset, and set Use Static Cache File
and Strip Whitespace to ―On‖. The first option ensures
Matrix doesn‘t need to parse the contents of the CSS File
as often as it otherwise would, and the second reduces
the overall size of the CSS File, making it marginally
quicker to download.
 For background CSS images, avoid references like
url(./?a=1234). Instead use either :
url(http://example.com/__data/image.gif) or;
url(mysource_files/image.gif) or;
url(%asset_url:X%) (where X is the asset ID).
 For buttons and icons, use a single CSS sprite20 instead of
several separate images.
19
http://developer.yahoo.com/performance/rules.html
20
http://alistapart.com/articles/sprites
54
Single licence copy
Combine all JavaScript into a single file

If the JavaScript is written in-house, ensure it‘s as
lightweight as possible, and ―minified‖.

If you‘re using a JavaScript framework, consider
including it from Google‘s content delivery network21.

Include all JavaScript just before the closing </body> so
that it loads last.
Asset Listings
For Asset Listings to load faster, and to minimise their impact on
Matrix, select a single, parent Root Node rather than several
child Root Nodes. Also:

use the Direct Links Only checkbox when you don‘t
need to list more than one level of assets;

avoid Asset Grouping, especially by Metadata.
Search
For Search Results to load faster, and to minimise their impact
on your Matrix System:
21

Set Search as Public User to ―Yes‖ (if searching across
live, public content).

Set No Roles Check to ―Yes‖ (if you‘re not using Roles).

Set No Group Access Check to ―Yes‖ (if searching
across live, public content).

Consider using a third party search engine for the
majority or all of your search requirements — more on
this later.
http://code.google.com/apis/ajaxlibs/
Single licence copy
55
Caching
In the Design, edit the Design File and set all Design Areas to
have an attribute of cache=1. This allows Matrix to cache these
Design Areas.
Don‘t cache the ―body‖ Design Area because it will cache all
content for the current asset, and ignore each asset‘s caching
rules, possibly affecting the functionality of Custom Forms and
other dynamic assets.
The __data URL
Any asset that has a __data URL will load significantly faster
than assets from other URLs because no status or permission
checking is done. By default, all file assets should use __data
unless Allow unrestricted access is set to ―No‖, or the file
isn‘t live with Public Read permissions applied.
Speed check: Yahoo‘s YSlow22 and Google‘s Page Speed23 are
plug-ins for Firefox which automatically analyse and make
recommendations on how to optimise your website. Both
require the use of another excellent Firefox plugin: Firebug24.
22
http://developer.yahoo.com/yslow/
23
http://code.google.com/speed/page-speed/
24
http://getfirebug.com/
56
Single licence copy
COMMON CONFIGURATION
PROBLEMS
Without care, Matrix can provide an unpleasant experience to
your users, for example, by presenting a content-less page
instead of a 404 not found page, or by displaying a less than
helpful error message. This normally becomes a problem when
you assume Matrix is going to automate something for you, but
doesn‘t. Let‘s address the more common faux paus you‘re likely
to encounter.
Index page, 404, Archived asset
For each Site asset, ensure you have set an Index Page asset, 404
not found asset and an Archived asset. This can be done on the
Details screen of the Site asset.
Failing to set any of these options will present the user with a
content-less page in certain conditions, giving them no guidance
as to what has happened, or what they should do next.
No results were found
The default No Results Bodycopy of an Asset Listing is often
overlooked. While the default text of ―No results were found‖ is
mostly better than a content-less page, there are much better
ways to describe what‘s happening. For example:

There are no products in this category.

No houses are currently for sale in this suburb. Be
notified when new houses are available in this suburb…
As an alternative, the Page Contents (No Results) Bodycopy
could nest the content from another page. This is a good way to
provide the same message on many different asset lists. To nest
the content from another page on when there are no results in
your Asset Listing:
Single licence copy
57
1. On the Edit Contents screen of ―Page Contents (No
Results)‖, view the properties of the DIV.
2. Set the Content Type to ―Nest Content‖.
3. Save the changes – when the page reloads, choose an
asset to nest. For example, a Search Page, Sitemap asset,
or a Form asset requesting help.
Make folders functional
By default, if a Folder asset is viewed on a website, it will present
a content-less page. This may happen more often than you would
expect, considering users might access a Folder via:

Matrix search, or an external search engine;

navigating to a folder using a breadcrumb trail;

by incorrectly or manually typing a URL.
There are a couple of quick and easy ways to reduce the chances
of a user viewing a Folder asset directly and, to appropriately
guide a user when they do access a Folder asset directly.
Hide folders from breadcrumbs
One of the most common ways your users will view a Folder
asset, is if they click on link to the folder via a breadcrumb. To
remove Folder assets from the breadcrumbs, modify the Design,
and add this setting to your Asset Lineage Design Area:
Screencast: http://matrixsecrets.com/book/folder-crumb
<MySource_SET name="unwanted_asset_types"
value="folder" />
Other unwanted assets can be hidden in the same way, by adding
to the ―value‖ field, for example:
<MySource_SET name="unwanted_asset_types"
value="folder user image" />
would also hide User and Image assets from the breadcrumbs.
58
Single licence copy
List child assets
Accepting the fact that as hard as we may try, some users will
ultimately end up viewing a Folder asset directly, let‘s give some
guidance to our users by listing links to each of the children of
the current asset.
Screencast: http://matrixsecrets.com/book/folder-children
First, create an Asset Listing called ―List children‖ which will list
our child assets, and on the Details screen set:
1. Asset Types to List to ―Standard Page‖ (and ―Images‖
or other asset types your Folders might have underneath
them).
2. Root Nodes to the Root Node of the Site your Design is
applied to.
3. Direct Links Only to ―Yes‖.
4. Under Dynamic Parameters set:
a.
Parameter to ―Replacement Root node...‖ .
b. Source to ―Current Asset‖.
Second, add the following into the Design of your site:
<MySource_AREA id_name="child_listing"
design_area="nest_content" print="no">
</MySource_AREA>
<MySource_AREA id_name="check_if_folder"
design_area="show_if">
<MySource_SET name="condition"
value="asset_type"/>
<MySource_SET name="condition_types"
value="folder" />
<MySource_THEN>
<MySource_PRINT id_name="child_listing" />
</MySource_THEN>
</MySource_AREA>
Single licence copy
59
Design Customisation (or customise an existing Design
Customisation), and:
1. Customise the ―child_listing‖ nest_content Design
Area. In this new customisation, choose the ―List
children‖ Asset Listing we created in the first step.
2. Apply this new customisation as the Design for your site.
Now, if you preview a Folder asset in your site, a list of the child
assets of the current Folder should be printed. Also, previewing a
non-Folder asset should keep this list hidden.
This method is a sensible way of giving your users some
guidance if they become lost, and can be complemented by
some meaningful text on what the user should do next. If
listing child assets isn‘t appropriate for your site, consider
nesting a site map, or search box instead.
Hide unwanted search results
Every Matrix driven website has assets that don‘t directly contain
content. They may be helper assets like Asset Listings, or a folder
of Redirect Assets for external links. If these assets are a child of
the Root Node used in the search, they have the potential to
displayed in your search results.
To exclude a single asset, or a group of assets from the search
results:
Screencast: http://matrixsecrets.com/book/search-robots
1. In an existing or new Metadata Schema, create a new
Select Metadata Field called ―robots‖ with these options:
a. NOINDEX, NOFOLLOW
b. NOINDEX, FOLLOW
c. INDEX, NOFOLLOW
Leave the option Allow Empty set to ―Yes‖.
60
Single licence copy
2. Ensure that Show On Frontend is set to:
a. ―Only if Filled‖ for the Metadata Field; and
b. ―Yes‖ for the Metadata Schema.
3. In an existing or new Search Page, on the Search Fields
screen, create a new Exclude Field called ―robots‖.
4. Edit contents of the ―Initial Search Page Layout‖, and add
the following HTML (remember to first click the ―Toggle
HTML Source‖ button):
<input name="queries_robots_query"
value="NOINDEX" type="hidden" />
Now, any search via the form you‘ve just customised, will exclude
all results with ―NOINDEX‖ in the metadata. This has the added
advantage that these pages won‘t be indexed by Google or other
search engines.
The two built-in alternatives to this method, which are the Asset
Tree Weights tool, and the excluding individual Root Nodes tool,
are either difficult to use, only accessible to System
Administrators, or don‘t work for external search engines.
Robots.txt
As well as the above, a robots.txt25 file will prevent the parts of
a website you specify from showing up in Google and other
search engines
To use a robots.txt file, add a Text File asset to the root of a
website, and set Allow Unrestricted Access to ―No‖. Edit the
contents of the text file, and list what you want to hide, for
example:
User-agent: *
Disallow: /secrets
25
http://en.wikipedia.org/wiki/Robots.txt#Examples
Single licence copy
61
No web paths
If you have a group of assets that only exist for the purpose of
appearing in a list, you ideally don‘t want these assets to be
accessible to the public at all. To ensure an asset doesn‘t have a
URL, try one of the following:

Ensure the assets are only linked under an asset that has
no URL (this means the parent asset can‘t be under a Site
asset, or the Design or Media folders).

Remove the web path from the parent asset, and ensure
all the child assets are only linked under this parent asset.
Removing the parent web path should ensure that any
child assets do not inherit or build on the parent web
path, hence these assets won‘t be accessible.
Login design
In Best Practices for your Matrix System we cover customising
the Login Design for the entire system, but the Login Design can
also be customised per Site or asset. Consider what your users
should see if they attempt to access a page that is not publicly
accessible. Here‘s a hint: it‘s not a login box! Unless your
audience is likely to have login details to a site, don‘t confuse
them by providing a login box. Provide a clear message
indicating what‘s happened, why it‘s happened, and what can be
done about it.
62
Single licence copy
USE FEWER DESIGN
CUSTOMISATIONS
Matrix Design and Design Customisations offer a great degree of
flexibility in how an HTML design can be created and modified.
They are so powerful in fact, they tend to be overused and can
become real roadblocks for productivity when best practices for
using Designs are not followed. The three main problems with
Designs and Design Customisations are:
1. Designs don‘t scale.
2. Designs require more user training and more user
permissions.
3. Designs don‘t support safe edit.
Let‘s explore each of these issues in detail.
1. Designs don’t scale
Designs don‘t scale well, because there is a limit to the number of
Design Customisations a single Design can handle, depending on
the resources available to your system. Additionally, Design
Customisations are often slower to work with than other assets.
A single Design should not be used for a group of sites – or worse
– an entire system, because:
1. If a large group of assets rely on a single Design, that
Design file becomes a single point of failure. This means a
trivial error when modifying your Design, has the
potential to affect an entire website.
2. You don‘t have complete control over Design
Customisations. If a change is made to a top level Design
Customisation or the Design itself, any child Design
Customisations could be affected – or worse – removed.
3. A single Design File will ultimately becomes more
complicated than multiple Design Files would, because of
the numerous Design Areas that are required.
Single licence copy
63
The solution to this problem is to use more Designs and fewer
Design Customisations. Try and limit the number of Design
Customisations to as few as possible. In the rare case where a
large number of customisations are required, consider splitting
the Design into two.
Body classes
A good way to avoid additional customisations is to assign a class
to the <body> tag, which allows small changes in a Design such
as different colour schemes, background images, or layouts, to be
created using CSS. For example, by applying a class to the
<body> tag, we can add different background images to the
<h2> element on each page, turning this:
Into this26:
or this27:
26
http://www.flickr.com/photos/archangel_raphael/144514204/sizes/s/
27
http://www.flickr.com/photos/karamell/3581305779/sizes/s/
64
Single licence copy
If kittens and puppies aren‘t your thing, consider that any style
can be changed using this technique, which could affect anything
from the font size and colour of a heading, the border, margin
and padding of a paragraph, or even the positioning of any
element on the page. If you have sections of your site that need
their own identity, this is the way to do it.
In the above two examples, the HTML and CSS used to present
these identities were:
Screencast: http://matrixsecrets.com/book/body-css
...
<style type=”text/css”>
body.puppies h2 {
background-image: url('mysource_files/dog.jpg');
background-repeat: no-repeat;
background-position: bottom left;
padding-bottom: 180px; }
body.kittens h2 {
background-image: url('mysource_files/cat.jpg');
background-repeat: no-repeat;
background-position: bottom left;
padding-bottom: 180px; }
</style>
</head>
<body class="kittens">
...
In Matrix, to substitute ―kittens‖ for ―puppies‖, or for any other
value we might want to assign to this field, we need to create a
metadata field to hold this value.
First, we need to modify the Design so a body class can be
dynamically inserted for each asset:
<body class="%globals_metadata_bodyclass%">
Then, create a new Metadata field named ―bodyclass‖. If you
don‘t already have a Metadata Schema applied to your site,
create a new Metadata Schema and apply it to your site. Then
Single licence copy
65
simply add a new text field called ―bodyclass‖ and on the
Metadata screen of each asset in your site, fill this value with
either ―puppies‖ or ―kittens‖.
Newer versions of Matrix allow metadata values to be
cascaded, so it‘s only necessary to apply these values at the
top level of your site.
2. Designs require more training and more
permissions
Creating and modifying Design Customisations is not covered in
the basic 101 Matrix training: separate design-related training is
offered specifically for this. In addition to Designs being more
complex to work with than content, Administrator permissions
are required to apply a Design to an asset. If you require a
regular user to be able to adjust the appearance of a page, the
solution is to use fewer Design Customisations.
Let‘s look at some more alternatives.
Asset Listings for nesting content
The customisation of Nested Content Design Areas can largely be
avoided through the use of Asset Listings. In the previous
example we saw how metadata can be used to print a body class
associated with the current asset. This can be extended to print
portions of text as part of the Design, but doesn‘t work well for
content that requires formatting, or content that comes from
several assets.
Take the example of listing documents related to the current
page. If every page of a site has a different list of related
documents, we could create a customisation for every page which
then nested in a Standard Page listing the documents.
A much better way of doing this is to nest an Asset Listing into
the Design in such a way that it can list all the related documents
of the current page. For example:
66
Single licence copy
Screencast: http://matrixsecrets.com/book/related-docs
1. Create a new Asset Listing asset called ―Related
Documents‖, and on the Details screen set:
a. Asset Types to ―File‖ (inherit).
b. Root Node to the Site asset.
c. Direct Links to ―Yes‖.
d. Under Dynamic Parameters set:
i. Parameter‖to ―Replace Root node for the
listing…‖.
ii. Source to ―Current Asset‖ (Asset ID).
2. In the Design, create a new (or modify an existing)
Nested Content Design Area, and choose nest the
―Related Documents‖ Asset Listing we‘ve just created.
3. Move or link some File assets under a Standard Page that
has the Design applied, then preview that Standard Page.
You should now see a list of the documents that are children of
the current asset. This also works well with Redirect Page assets
(to list of internal or external links), or Users, for example if you
were listing staff or user profiles.
Global keywords
Where possible, use global keywords in the Design file instead of
Design Customisations. Global keywords can be used to:

Include text from the current asset:
%globals_asset_metadata_summary%
%globals_asset_name%

Include text from an arbitrary asset:
%globals_asset_contents:1234%
%globals_asset_attribute_comment:1234%

Include the URL of an asset (eliminating the need for a
Constant Button Design Area in most cases):
Single licence copy
67
<a href="http://eg.com/%globals_asset_href%">
example link</a>
<a href="%globals_asset_url%">example</a>
<a href="%globals_asset_url:1234%">example</a>

Insert a date or time:
%asset_created_X%, %asset_published_X% and
%asset_updated_X% Where X is the php date format:
php.net/manual/en/function.date.php
3. Designs don’t support Safe Edit
Designs don‘t support Safe-Edit — don‘t even think about trying
it! Of course, this means that any changes to a live Design are
visible immediately. This also means you must be very careful
when making a change to a Design, particularly when it is
applied to a large group of assets.
Theoretically, any change to a Design should be tested before it‘s
made, but practically, you may find yourself taking the risk of
making minor changes and assuming you‘ll get it right the first
time. To test a change to a Design:
1. Have a backup plan. If the new change breaks the Design,
have a copy of the original Design file on hand ready to
upload, or have an alternative design ready to apply.
2. Clone the original Design, and apply this new Design as a
―User Defined, Frontend Design‖ (named ―test‖) on the
Settings screen.
3. Make changes to the new design, and preview these
changes using by appending ?SQ_DESIGN_NAME=test to
the URL of a page. To preview an entire site use append
?SQ_ACTION=set_design_name&SQ_DESIGN_NAME=test
to the URL of a page, which will keep the test Design
applied for an entire session.
4. Apply the new Design instead of the original Design on
the Settings screen, or replicate the changes you‘ve just
made to the original Design.
68
Single licence copy
Use a text editor
If you‘re working with the Design File, it‘s a good idea to make
your changes in a text editor before copying these changes into
Matrix. This will allow you to:

make code changes in a properly highlighted, indented
and formatted way;

keep a long-term backup copy of the Design File in case a
change is made by someone else;

keep a short-term backup copy of the Design File, in case
it‘s accidently broken.
Single licence copy
69
BEST
PRACTICES
FOR YOUR
MATRIX
SYSTEM
70
Single licence copy
WARRANTIES AND THE
LANGUAGE FILE
Several of the techniques in this chapter involve making
modifications directly on the operating system Matrix runs on,
sometimes by editing the XML language file named
core/locale/en/lang_strings.xml. This language file contains
the messages and labels Matrix uses to display the user interface.
While it could be argued this isn‘t actually part of the core of
Matrix, and therefore shouldn‘t void your warranty, you should
confirm the restrictions placed on your organisation‘s warranty.
Fortunately, this file is easy to edit (it‘s in plain XML), can be
easily backed up and restored (it‘s a single file), and it should be
immediately obvious if something has gone horribly wrong. To
make changes to this file:
1. Log in directly to your test server (which hosts Matrix),
and go to the directory in which Matrix is installed.
2. Make a backup the of the lang_strings.xml file in
core/locale/en/
3. Make the desired changes to the XML file.
4. Still directly on the test server, run the command:
php /matrix/install/compile_locale.php /matrix/
(substitute /matrix/ with the location of your Matrix
installation).
5. Test the changes in the Matrix Administration Interface.
6. Repeat these steps for your live environment.
If you make a mistake, restore the backed up copy of the
lang_strings.xml file you backed up, and rerun the
compile_locale.php command.
As we‘ll see in this chapter, the lang_strings.xml file allows
us to do much more than just changing the labels and text in the
Administration Interface, it also lets us insert arbitrary HTML
and JavaScript, and modify the presentation of the interface.
Single licence copy
71
MATRIX DEFAULTS
A few of the default settings in Matrix are not ideal, especially for
users that have to use the system every day. These small changes
will improve the effectiveness of your website, and reduce your
user‘s frustration as they use the Matrix Administration
Interface.
System Configuration
72

Change the System Web Path Separator to a dash (-)
instead of an underscore (_). It‘s impossible to spot the
difference between a space and an underscore when a
URL is underlined. It can also be beneficial for search
engine optimisation (SEO) reasons.

Set Hide Errors on the Frontend to "Yes", otherwise
you might expose your users to some unfriendly PHP
errors from Matrix.

A short Lock Length is useful if your organisation has
many users editing the same portion of your site. If this
isn‘t the case, a lock length of 3600 seconds (1 hour) will
reduce the amount of locks your users need to acquire.

The Refresh Interval controls how often the top bar
refreshes, which is necessary to ensure the locks on the
current screen are maintained. The default setting of 120
seconds quickly becomes annoying because of the flicker
it generates, and because it removes any text the user has
entered in the Quick Search box. Increasing this value
will reduce the frequency of these problems, but this
value must be less that the lock length to maintain locks
(10 seconds less than the lock length should be
sufficient).

Because the ID of an asset is often used in Matrix,
especially by advanced users, it‘s useful to expose this
asset ID in the Asset Map by settting Asset Display
Name to: %asset_short_name% (%asset_assetid%)
Single licence copy
Caching
For performance reasons, caching should always be on, but
consider how long it should be before the cache on each asset
expires.
A cache expiry of 57600 seconds (16 hours) means if a user
updates their content at 5pm, the content will be viewable at 9am
the next morning. This shouldn‘t have a large effect on system
performance, but will reduce the confusion and frustration for a
user when they can‘t see their new changes the next day. The
default expiry of 24 hours is often not taken literally, so quite
reasonably, users expect their new content to be viewable the
next day.
On the Details screen of the ―Caching Manager‖ (under ―System
Management‖), set:

Caching Status to ―On‖.

Default Expiry to ―57600‖.

Public Level Caching to ―On‖.
Global Preferences
By default, users are limited to uploading files of 2 MB or smaller
to Matrix. In ―System Configuration‖, ―Global Preferences‖, set
the Max File Upload to 4 MB or greater.
This setting is also controlled by two PHP settings on the server
Matrix is hosted on. These settings will also need to be changed
by changing the values in php.ini of:

post_max_size;

upload_max_filesize.
These values should be set to the same size as the Max File
Upload, or larger if you think this might need to be increased
again in the future.
Single licence copy
73
HIPO Configuration
The number of assets that cause a HIPO job to be initiated,
known as the HIPO threshold, is generally too low by default.
A low HIPO threshold will actually slow down the process of
acquiring locks and editing metadata, permissions, and statuses
in certain situations, because it will force the HIPO progress
pop-up to be displayed. It can also cause an annoying flicker in
your web browser as this progress screen loads and completes.
To fix this, in "System Configuration", "HIPO Configuration", set
the thresholds to 10 assets for the following functions:

Edit Metadata Threshold

Purge Trash Threshold

Clone Asset Threshold

Permissions Threshold

Workflow Schemas Threshold

Lookups Updating Threshold

Acquire Lock Threshold

Edit Status Threshold
Increasing these thresholds has the potential to add more
load to your server, so experimenting with the 10 asset
threshold limit is recommended.
74
Single licence copy
Make HIPO actions more obvious
Consider this screen that appears when moving an asset:
What action is being performed here and what will the result be?
The information is there, but it requires the users full attention
to assess what is about to happen. The full attention of a user is
not something easily acquired, especially when this particular
screen could be presented to a user several times in one day.
We know most users, ourselves included, are inherently lazy
when it comes to reading messages like this, and the result is that
it becomes all too easy to click the Next button, and to
accidentally move something to the trash. This essentially
negates any use this confirmation screen has.
Let‘s look at two examples where we can make these actions
more obvious. For both these examples, follow the process for
editing the lang_strings.xml file as described at the start of
this chapter.
Single licence copy
75
Deleting an asset
Screencast: http://matrixsecrets.com/book/hipo-delete
Locate and modify this portion of the lang_strings.xml file, and
run the compile_locale.php script as previously described.
<string source="hipo_confirm_move_trash">
Please confirm that you are moving %s asset(s)
&lt;span style="font-size: 2em;"&gt;to the
trash&lt;/span&gt;.
</string>
This will change the original HIPO screen from this:
To this:
76
Single licence copy
Moving an asset
Screencast: http://matrixsecrets.com/book/hipo-move
Locate and modify this portion of the lang_strings.xml file, and
run the compile_locale.php script as previously described.
<string source="hipo_confirm_move_under">
Please confirm that you are moving the following
asset(s) to under &lt;span style="font-size:
1.5em;"&gt;"%s"&lt;/span&gt;:
</string>
<string source="hipo_from_under">
&lt;span style="font-size:2em;"&gt;%1$s
&lt;/span&gt; from under "%2$s"
</string>
This will change the original HIPO screen from this:
To this:
Single licence copy
77
SYSTEM MAINTENANCE
In order to keep your Matrix system running like it did the first
day you installed it, there are several settings and maintenance
tasks that need taking care of.
Stop the logging!
The Matrix database‘s sq_internal_msg table often gets so
large that it affects the speed of the Administration Interface.
This table is used to generate the information on the Logs screen,
but is also stored on the file system of the web server. If you don‘t
need this information to be accessible from the Logs screen,
under ―System Configuration‖ -> ―Messaging Service
Configuration‖, move the * from Log to Database White List,
to Log To Database Black List.
Alternatively, only log the information that you absolutely need,
and on the server that hosts your Matrix System, set up a cron
job to regularly run the scripts/remove_internal_messages.php
script.
Use a Proxy Server
You won‘t find many large or high traffic installations of Matrix
that don‘t use some sort of proxy server. If your users are already
experiencing some performance issues with either the loading of
your website or the Administration Interface, ensure Matrix
caching is turned on and investigate installing a reverse proxy
server (typically a Squid server).
The Squiz Supported version of Matrix includes Triggers to
clear the Squid cache automatically, but not the GPL version.
This needs to be taken into account if you‘re running the GPL
version because you can‘t easily clear the cache on individual
assets. This means content will at worst not be displayed until
the cache expires, which can typically be up to 24 hours.
78
Single licence copy
Use a static server
A static server can be used to serve all your static content like
PDF files, images, and Word Documents. Doing this also allows
you to more easily ensure content has appropriate expires or
cache-control headers, and that these files are potentially
compressed.
In ―System Configuration‖ set a System Static URL, then set
up a separate web server (ideally something lightweight like
lighttpd28) to serve content from mysource_root/data/public.
As per Yahoo‘s performance best practices29, this also allows you
to split components across domains, allowing browsers to
download more content in parallel.
PostgreSQL
Performing regular vacuuming30 of your PostgreSQL database
frees up its internal memory, and is essential to ensuring the
database keeps running smoothly and efficiently.
If Matrix seems slow to perform certain tasks, you can configure
PostgreSQL to log slow statements to the server system logs by
adding to postgresql.conf:
log_min_error_statement = 5000ms
and monitor your server‘s system logs for any SQL statements
that appear.
You‘ll typically need to configure syslog to see these logs:
postgresql.org/docs/8.3/static/runtime-configlogging.html#RUNTIME-CONFIG-LOGGING-WHEN
28
http://www.lighttpd.net/
29
http://developer.yahoo.com/performance/rules.html
30
http://developer.postgresql.org/pgdocs/postgres/routine-vacuuming.html
Single licence copy
79
Empty the Trash
On the server your Matrix system is hosted on, add an entry to
the cron tab to regularly run the scripts/purge_trash.php
script, to ensure the Trash does not become overfilled with
assets.
When is the Trash next emptied?
If the trash is emptied on a regular basis, it‘s wise to advise users
when this will occur. If you‘re not overly keen on talking to
people, the purge_trash.php script can be modified to rename
the Trash, so it warns users when the Trash will next be emptied.
Simply
add
a
few
lines
of
code
to
your
scripts/purge_trash.php script, just before the line if
(!empty($linkid)) {.
This code is free for use under the BSD licence31.
Screencast: http://matrixsecrets.com/book/trash-update
// Pass the third argument as the number of days
// till the next purge_trash script run
// Using this value, we will rename the trash.
if (isset($_SERVER['argv'][3])) {
$date_to_empty = date("D jS",
mktime(0,0,0,date("m"),
date("d")+$_SERVER['argv'][3],date("Y")));
$sql = "UPDATE sq_ast SET short_name = 'Trash
(Next emptied " . $date_to_empty . ")' where
assetid = '$trash_folder->id';";
$query = MatrixDAL::preparePdoQuery($sql);
$result = MatrixDAL::executePdoOne($query);
}
31
http://creativecommons.org/licenses/BSD/
80
Single licence copy
Then, add an integer when calling the purge_trash.php script to
indicate the number of days until the next collection:
php purge_trash.php /var/www/matrix-3-20-0/ 10 7
where ―7‖ is the number of days till the next purge, and ―10‖ is
the (existing) variable that defines the root node to empty the
trash of (the trash asset has an ID of 10).
Now, refresh the Asset Map and you should see something along
the lines of Trash (Next emptied Thu 8th). Again, this
modification is considered part of the core of Matrix, but is easy
to track, change or rollback.
PHP accelerators
If your system is performing badly, consider using eAccelerator32
or APC33 for your Matrix installation. They‘re no silver bullet, but
have been known to improve response times in some
installations, by caching parts of the code Matrix uses to display
your website, or to run the Administration Interface.
PHP accelerators aren‘t necessarily something you can just
switch on, so you‘ll also have to consider appropriate time to
configure, install, and test the accelerator. For example, you may
only want to compile .inc files which contain Matrix source
code and not .php files which Matrix uses for caching.
32
http://eaccelerator.net/
33
http://php.net/apc/
Single licence copy
81
PLAN TO UPGRADE
Matrix has fairly short release cycles compared to other content
management systems. At the time of writing, a major version of
Matrix is released three times a year, with minor releases every
month34. Failing to plan for these releases may leave your users
frustrated through a lack of features or worse, through one or
more bugs.
Don’t be a beta tester
Unless there is a killer bug that is stopping your users from
working, don‘t immediately upgrade to a new major release: wait
the extra month for the .1 release. As with any other software, the
first ―stable‖ release is much more likely to have major bugs than
the .1, .2 or .3 releases.
Keeping up to date with minor releases will generally make
major upgrades more straight-forward, but it‘s still advisable to
review the changelog35 before an upgrade, to assess the benefits
of each version.
Test your upgrades
Don‘t assume an upgrade won‘t break something or even
everything. Develop a test plan to test different critical parts of
Matrix functionality, and run it before and after any upgrade.
Some example test steps could be to ensure:
1. Search is returning the same set of results.
2. Workflow if functioning correctly.
3. Design and Design Customisations
presenting your website.
are
correctly
4. Standard Pages can be created, edited, made live and
deleted.
5. Triggers are still functioning correctly.
34
http://matrix.squiz.net/developer/release-dates
35
http://matrix.squiz.net/developer/changelogs
82
Single licence copy
Custom assets
Introducing any custom code to your system increases the
complexity of upgrading. Custom assets may bear additional cost
to your organisation if they are not compatible with future
versions of Matrix. Use caution when committing to using
custom assets in your system, and consider the future cost and
time implications. If custom assets are necessary, consider
running a separate, custom, instance of Matrix in which the
required custom assets will reside, allowing a standard instance
of Matrix to run untouched.
Single licence copy
83
DEFAULT LOGIN DESIGN
The Login Design is the interface that's displayed when a user
needs to login, or when a user doesn‘t have permission to access
a page. The default Login Design has some quirks which you may
want to consider addressing, otherwise you‘re likely to suffer
many support requests asking why a user can‘t login.
Error messages
Without customisation, a user will see a login box in the
following circumstances:

If the user is not logged in, and the current asset is not
live, and does not have public read permissions.

If the user is logged in, but doesn‘t have sufficient
permissions to view the current asset.
This second condition is where most of the trouble lies: if a user
sees a login box, their first instinct is to assume they‘re not
logged in (because they typically disregard the small ―You do not
have permission to access…‖ message), and will attempt to log in
to the system. Worse still is the situation where a public user
(whom has no exposure to Matrix) is presented with this login
box, as it‘s not clear what action to take next.
Let‘s attempt to fix some of these issues with some new
messages:
Condition
Original Message
(in tiny writing)
New Message
(in big writing)
User not logged
in, no permission
to access current
page
You do not have
permission to access
Asset Name
Login Required: A
username and
password is needed to
access this page
User logged in, no
permission to
access current
page
You do not have
permission to access
Asset Name
Oops! You (user)
don't have permission
to view this page
Please contact X for
84
Single licence copy
Non-backend user
tries to access
Admin. Interface
You need to be a
backend user in order
to access the backend
assistance
Is the login box necessary? Especially in public facing
websites, consider hiding the login box as the next example
does. Users are drawn to login boxes, so if the majority of
your users don‘t need to login, don‘t include a login box. At
the very least, make the login box less prominent than any
other login or permission information you‘re trying to
convey.
Here is a standards-based design that is a good start to
improving the Login Design, which can be easily customised to
suit your organisation.
It‘s best to create a new Login Design, and apply this via the
Settings screen for each Site. If you want to change the default
Login Design, you should do this on a test system first, because
an error in this file could prevent any user (including you) from
logging into the system.
To change the default Login Design on your test system, edit the
Design File under ―System Management‖ -> ―System Design‖ ->
―login_design‖. If the Login Design breaks during this process,
try logging in by appending ?FORCE_BACKUP_LOGIN=1 to the
URL.
This code is free for use under the BSD licence36.
Screencast: http://matrixsecrets.com/book/login-design
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0
Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1strict.dtd">
<html>
<head>
36
http://creativecommons.org/licenses/BSD
Single licence copy
85
<title>Organisation Name: Login Required</title>
<style type="text/css">
body {
font-family: "Helvetica", sans-serif;
margin: 0; padding: 4em 0 0 0; }
h1 {
display: block; padding: .5em 1em;
background-color: #ffb6c1;
border: 1px solid red; border-width: 1px 0 1px
0; }
h1 span { display: block; font-size: .7em; }
form { min-width: 47em; overflow: auto; }
/* LOGIN FORM CONTROLS */
#login-form {
margin: 0 auto; padding: 1em 0;
width: 20em;
overflow: auto;
border: 5px solid #666666; background-color:
#F1F1F1; }
label, input {
float: left; font-size: 1.1em;
line-height: 1.5em; margin-bottom: .3em; }
label { clear: left; width: 7em; text-align:
right; }
input { margin-left: 1em; }
#log_in_out_button { margin: .5em 0 0 8em; }
/* CONDITIONALLY HIDE ELEMENTS */
/* Hide username and password is needed to access
this page if:
1. Username/password invalid
2. Login Key incorrect */
h1 span.Invalid span, h1 span.incorrect span {
display: none; }
/* Otherwise, show this message/subheading */
h1 span span { display: block; font-size: 1em; }
/* USER IS NOT LOGGED IN */
86
Single licence copy
.not-logged-in #login-form, .not-logged-in h1 {
display:block;}
.not-logged-in #no-permission { display:none; }
/* USER LOGGED IN, BUT NO PERMISSION TO ACCESS
THIS PAGE */
#login-form, h1 { display: none; }
#no-permission {
display: block; margin: 0 0 1em 0; padding: 3em;
font-size: 2em; font-weight: bold;
border: 1px solid red; border-width: 1px 0 1px
0;
background-color: #ffb6c1; }
#no-permission span { font-size: .7em; display:
block; }
</style>
</head>
<body class="<MySource_PRINT id_name="__global__"
var="current_user" default="not-logged-in" attr=""
/>">
<h1 id="no-permission">
Oops!
<span>You (<MySource_PRINT id_name="__global__"
var="current_user" default="not-logged-in"
attr="name" />) don't have permission to view this
page</span>
<span>Please contact [email protected] for
assistance, or <a id="login-show"
href="#login">login</a>.</span>
</h1>
<MySource_AREA id_name="login_form"
design_area="login_form">
<MySource_LOGIN_SECTION>
<div id="login-form-wrapper">
<MySource_SET name="give_username_focus"
value="true" />
<MySource_SET name="forward_www_vars"
Single licence copy
87
value="true" />
<MySource_PRINT var="form_open" />
<h1>
Login Required:
<span id="sq-message" class="<MySource_PRINT
var="system_messages" /> <MySource_PRINT
var="login_message" />">
<span>A username and password is needed to
access this page</span>
<MySource_PRINT var="system_messages" />
</span>
</h1>
<div id="login-form">
<label
for="SQ_LOGIN_USERNAME">Username:</label>
<MySource_PRINT var="username_box" size="10"
/>
<label
for="SQ_LOGIN_PASSWORD">Password:</label>
<MySource_PRINT var="password_box" size="10"
/>
<MySource_PRINT var="submit_button"
value="Login" />
</div>
<MySource_PRINT var="form_close" />
</div>
</MySource_LOGIN_SECTION>
</MySource_AREA>
</body>
</html>
88
Single licence copy
Again, these messages can also be changed in the file:
lang_strings.xml file using the method previously
discussed. HTML can be added using HTML encoding (for
example &lt; will be converted to <).
Single licence copy
89
SEARCH
Most content management systems only offer basic search
functionality, and Matrix is no exception. Although this author is
biased because at the time of writing, he works for an enterprise
search engine vendor, an enterprise search engine can offer a lot
over the standard Matrix Search, including:

Better quality results. The algorithms used by enterprise
search engines are more sophisticated, and normally
return better results out of the box than Matrix.

Customisable. Results can be finetuned based on the
business requirements of your organisation. Results can
easily be added, removed, upweighted or downweighted
based on any number of criteria. Specific results can be
featured based on specific queries.

Features. Query expansions (thesaurus/synonyms),
faceted navigation, query suggestions, best bets and more
are available in most enterprise search engines.

Performance. Search results will be returned much faster
than the standard Matrix search.

Scalability. Search in Matrix is very resource intensive,
and can affect all aspects of Matrix performance, from
delivering a front-end page to the user, to using the
Administration Interface. Enterprise search engines can
remove this load from Matrix, freeing up resources for
Matrix to perform other tasks.
Performance
If enterprise search isn‘t an option, let‘s look at the ways you can
reduce the load Search may place on your Matrix system.
90
Single licence copy
Global Search Options
On the Details of the ―Search Manager‖, set the following
options:

Minimum Word Length: 4 is the default, and
appropriate for most systems, but a higher value will
reduce the size of the search index, and typically improve
performance. This setting doesn‘t affect Oracle-based
systems.

White Word List: anything specific to your
organisation or locality. Acronyms shorter than the
Minimum Word Length are most important here
(state or province and organisational abbreviations would
be the most common examples).

Contains Search set to ―No‖. This option normally
returns less relevant results anyway, and it‘s unusual to
find this option enabled by default in an enterprise search
engine.

Noise Word List: enterprise search engines have an
internal set of stop words which are not indexed, but
Matrix only ships with 4 of these words: a, the, it, this.
Adding a better list of these words should reduce the size
of your index, and hence the amount of load put on the
system. Wikipedia37 typically has links to several lists of
pre-defined stop words to use in the ―Noise Word List‖.
A list of keywords indexed in a particular system can be
generated using the following SQL statement on your database:
SELECT value, count(value)
FROM sq_sch_idx GROUP BY value
ORDER BY count DESC
at which point it becomes clear that content, page, and contents
should also be added to the list.
37
http://en.wikipedia.org/wiki/Stop_words
Single licence copy
91
Search Pages
To improve the performance of Search Page assets, set these
options on the Details screen:
 Search as Public User to ―Yes‖ (if this is a public
search across live assets).
 No Roles Check to ―Yes‖ (if you‘re not using roles).
 No Group Access Check to ―Yes‖ (if this is a public
search across live assets).
92
Single licence copy
ADVANCED
LISTING
TECHNIQUES
Asset Listings are such a core part of Matrix that it‘s essential to
know how they work. If you learn to love them, with a little
manipulation they can do just about anything.
As we progress through this chapter, we build on each example
to create more sophisticated Asset Listings. If you‘re following
along with the examples, it‘s best to complete each one before
moving on to the next.
Single licence copy
93
THE IMAGE GALLERY ASSET
LISTING
Matrix doesn‘t need an image gallery asset because an Asset
Listing can do everything an image gallery can do - and more.
Let‘s start with a basic example of how to create an image gallery,
and gradually extend this to be more like the image sharing
website flickr38.
Asset Listing basics: the Image Gallery
Screencast: http://matrixsecrets.com/book/image-gallery
In this example, we want to create a functional image gallery,
complete with thumbnails and group headings. To begin, create a
Folder asset called ―Image Gallery‖, and create child assets of the
Image Gallery Folder as follows:
Each Image has an Image Variety called ―thumbnail‖ which is
250 pixels wide. If you‘re not familiar with Image Varieties, see
the section on Image Varieties in Manage Your Content.
38
http://flickr.com/
94
Single licence copy
Now, let‘s display and group these images by their parent folder:
1. Create an Asset Listing named ―Image Gallery List‖ and
on the Details screen set:
a. Asset Types to List to ―Image‖.
b. Root Nodes to the ―Image Gallery‖ folder.
c. List Format to ―Custom Grouping‖.
2. On the Asset Grouping screen, add a new group of type
―Parent Asset‖ and check Direct Parent Only.
3. Edit the contents of ―Group Level 1 Format‖ and insert:
<h1>%group_name%</h1> %group_listing%
4. Edit the contents of ―Default Format‖ and insert:
<a href="%asset_href%">
<img src="%image_v_thumbnail_url%"
alt="%asset_attribute_alt%"></a>
Preview the Asset Listing and you should have a functional image
gallery, complete with thumbnails and group headings. As we‘ll
soon see, this is only the beginning of what is possible with Asset
Listings.
Dynamic Asset Listings: flickr-style gallery
Flickr gives users the option of downloading each image in a
number of different sizes. Let‘s extend our existing image gallery
to do the same thing.
First, for each image, ensure there is a ―small‖ variety of 250
pixels wide, and a ―medium‖ variety of 500 pixels wide.
Secondly, to list each of our Image Varieties, create a new Asset
Listing called ―Image Sizes‖. Take note of the asset ID. Then:
1. On the Details screen set of the ―Image Sizes‖ Asset
Listing, set:
a. Asset Types to List to ―Image Variety‖ and
―Image‖.
b. Root Nodes to the ―Image Gallery‖ Folder.
Single licence copy
95
c. Minimum Depth/Height to ―0‖ (zero).
d. Under Dynamic Parameters set:
i. Parameter to ―Replacement Root
node…‖.
ii. Source to ―GET Variable Name‖.
iii. Get Variable Name to ―assetid‖.
2. On the Display Formats screen, add a New Type
Format of ―Image‖.
3. Edit the ―Image Format‖ to include:
<a href="%asset_url%">Original Size<br>
<img src="%image_v_medium_url%"
alt="%asset_attribute_alt%"></a>
4. Edit the ―Page Contents‖ to include:
<img src="%image_v_medium_url%"
alt="%asset_attribute_alt%"></a>
<a href="%asset_href%">Full size</a>
%asset_listing%
5. Edit the ―Default Format‖ to include:
<a href="%asset_href%">%asset_name%</a>
Lastly, modify the original ―Image Gallery List‖ Asset Listing and
update the ―Default Format‖ to:
<a href="./?a=1234?assetid=%asset_assetid%">
<img src="%image_v_thumbnail_url%"
alt="%asset_attribute_alt%"></a>
Replace ―1234‖ with the asset ID of the ―Images Sizes‖ Asset
Listing you noted down earlier.
Preview the ―Image Gallery List‖ Asset Listing, and now when
you click on an image, you should see a list of the available
varieties, along with the medium size image, just as you would
when using flickr.
96
Single licence copy
Add user comments using the Asset Builder
Another feature of flickr is the commenting system, which allows
users to comment on the images uploaded to the site. Let‘s add a
commenting system to our image gallery using an Asset Builder
and another Asset Listing.
First, create a Folder asset named ―Comments‖. Secondly, create
an Asset Builder asset and:
1. On the Details screen set:
a. Asset Types to Create to ―Comment‖.
b. Create Status to ―Live‖.
2. On the Create Locations screen set:
a.
Fixed Create Locations to the ―Comments‖
folder.
b. Additional Location Data Sources:
i. Parameter of ―Additional Create
Locations‖.
ii. Source of ―GET Variable Name‖.
iii. GET Variable Name of ―assetid‖.
c. Default Link Type to ―NOTICE‖.
d. Permitted Tree Locations to the ―Image
Gallery‖ folder.
e. Permitted Asset Types to ―Image‖.
Secondly, edit the ―Page Contents‖ of the ―Image Sizes‖ Asset
Listing, and:
1. At the bottom of the page, create a new DIV with a
Content Type of ―Nest Content‖.
2. Using the new Nest Content DIV, choose the Asset
Builder we have just created.
Single licence copy
97
Preview the ―Image Gallery‖ Asset Listing, and you should now
be able to add comments to each Image asset. Next, we‘ll learn
how to list these comments.
Ideally when adding comments we would have added each
Comment asset as the child of the appropriate Image asset.
However, Matrix doesn‘t allow this type of linking which is
why we set the ―Default Link Type‖ to Notice – more on
Notice linking later.
Listing user comments
Now that users can add comments to each Image, let‘s create
another Asset Listing to display them.
Create another Asset Listing named ―List Comments‖, and:
1. On the Details screen set:
a. Asset Types to List to ―Comment‖.
b. Root Nodes to the ―Image Gallery‖ Folder.
c. Direct Links Only to ―Yes‖.
d. Link Types to ―NOTICE‖.
e. Under Dynamic Parameters
i. Parameter to ―Replacement Root
node…‖.
ii. Source to ―GET Variable Name‖.
iii. Get Variable Name to ―assetid‖.
2. Edit the ―Default Format‖ to:
<h2>%asset_attribute_name%</h2>
<p>%asset_attribute_comment%</p>
3. Edit the ―Page Contents‖ of the ―Image Sizes‖ Asset
Listing and:
a. At the bottom of the page, create a new DIV with a
Content Type of ―Nest Content‖.
98
Single licence copy
b. Using the new Nest Content DIV, choose the ―List
Comments‖ Asset Listing we have just created.
Preview the ―Image Gallery List‖ asset, and there you have it! A
flickr-style image gallery with comments. Before we move on,
let‘s examine a few points in finer detail.
Single licence copy
99
MORE ON THE IMAGE
GALLERY ASSET LISTING
Display comments before the comment form
In most blogs, the comment form appears below the existing
comments rather than in our example, where the comment form
appeared first.
However moving the Asset Builder so that it displays the
comment form before the list of comments causes one major
problem: when a user submits a comment, it won‘t appear until
the page refreshes due to the order in which Matrix processes
nested assets.
To fix this problem, the ―List Comments‖ Asset Listing needs to
be nested inside the Asset Builder. Using our image gallery
example:
Screencast: http://matrixsecrets.com/book/comments-order
1. In the ―Page Contents‖ of the ―Image Sizes‖ Asset Listing:
a. Remove the DIV which nests the ―List Comments‖
Asset Listing.
2. In the Asset Builder, edit the contents of the ―Not Logged
In‖, ―Logged in‖ and ―Created‖ bodycopies:
a. Create a new DIV with a ―Content Type‖ of ―Nest
Content‖ at the top of the page.
b. Using the new Nest Content DIVs, choose the
―List Comments‖ asset.
Although more complicated than the original example, this
ensures user comments will appear as soon as they are posted.
List anything!
Asset Listings can list a whole lot more than just images, but
don‘t take my word on the power of Asset Listings: try it yourself!
100
Single licence copy
Most assets in Matrix can be listed, consider listing:

User assets for a staff directory;

Redirect assets for external links;

RSS Feeds;

User Workspaces for assets relating to a user;

Calendar Events, Bodycopy DIVs, Data Records, and
other Asset Listings!
Now that we‘ve skimmed the surface of what Asset Listings can
do, let‘s delve a little deeper.
Notice link Asset Listing
In our image gallery example, it wasn‘t possible to link Comment
assets underneath the Image assets, which made the listing of
comments more difficult. To work around this, we manipulated
the standard ―Notice‖ link functionality to create an association
between each Image and Comment asset.
Notice links are created in Matrix when a standard <a
href="./?a=1234">hyperlink</a> is added to the contents of
a Page. Along with other types of links, the Linking screen will
show all the types of links associated with a particular asset. In
the case of Notice links however, these links are often displayed
on the page being linked from, rather than the page being linked
to. Notice links are also used for:

Links to thumbnails (link type: ―thumbnail‖)

Redirect assets (link type: ―redirect_asset‖)

Root nodes (link type: ―root‖)

Site 404 pages (link type: ―not_found‖)

Nested Content (link type: ―nested_asset‖)

And more!
Single licence copy
101
NESTED ASSET LISTINGS
A nested Asset Listing is an Asset Listing which nests an
additional Asset Listing in its Default Format Bodycopy. This
essentially means you‘re creating a list of lists. Although this is
quite an advanced topic, as you‘ll see from the following
examples, nesting Asset Listings allows you to do things that
aren‘t possible with a single Asset Listing.
Inherited Thumbnails
Thumbnails are a great way to associate an image with an asset,
and are especially good for Using fewer Design Customisations.
Applying a thumbnail on the Details screen doesn‘t actually do
anything by default, but typically a reference to the thumbnail
image would be inserted into the Design or a Paint Layout using
the %asset_thumbnail% keyword.
Both these options take an ―all or nothing‖ approach in that a
thumbnail needs to be applied to every single asset in a site. For
assets that don‘t have a thumbnail, no image (or worse a broken
image) will be displayed. However, by building on what we‘ve
learnt through Nested and Notice Link Asset Listings, we can
apply thumbnails to a single asset, and let this thumbnail
―cascade‖ to all its children.
Let‘s assume we want to display the thumbnail as a background
image via CSS. If the current page has a thumbnail applied, we
will display that, otherwise we will traverse up the asset tree to
find the next asset that has a thumbnail, and display that. The
CSS we want to ultimately display is:
<style type="text/css">
h1 { background-image: url(grandparent.jpg); }
h1 { background-image: url(parent.jpg); }
h1 { background-image: url(current.jpg); }
</style>
We can‘t use Matrix to list just a single thumbnail, so we‘re going
to use CSS specificity to override the background image. In this
example, current.jpg overrides parent.jpg which itself
102
Single licence copy
overrides grandparent.jpg because of the order of each of the
CSS statements in the document. Where a thumbnail doesn‘t
exist at a certain level, we‘ll just print .thumb {} which won‘t
have any effect on our styling.
Screencast: http://matrixsecrets.com/book/thumbnails
First, create an Asset Listing named ―Display Thumbnail‖ and:
1. On the Details screen set:
a. Asset Types to List to ―Image‖.
b. Root Nodes to the Root Node of your Site.
c. Direct Links Only to ―Yes‖.
d. Link Types to ―NOTICE‖.
e. Link Value to ―thumbnail‖.
f.
Enable Link Value Filtering to ―Yes‖.
g. Assets Per Page to ―1‖.
h. Customise No Results Bodycopy to ―No‖.
i.
Under Dynamic Parameters set:
i. Parameter to ―Replacement Root
node…‖.
ii. Source to ―SESSION Variable Name‖.
iii. SESSION Variable Name to
list_current_asset_id
2. Edit the contents of the ―Page Contents‖ and set the DIV
properties to a Presentation and Content Type of
―Raw HTML‖.
3. Edit the contents of the ―Default Format‖ and set the DIV
properties to a Presentation and Content Type of
―Raw HTML‖ and insert:
background-image: url(%asset_url%);
Then, create another Asset Listing named ―List Parent‖ and:
Single licence copy
103
1. On the Details screen, set:
a. Asset Types to List to ―Standard Page‖ and
―Site‖.
b. Root Nodes to the Root Node of your Site.
c. Lookup Direction to ―Up the tree‖.
d. Minimum Depth/Height to ―0‖.
e. List Format to ―Custom Grouping‖.
f.
Under Dynamic Parameters set:
i.
Parameter to ―Replacement Root
node...‖ .
ii. Source to ―Current Asset‖.
2. On the Asset Grouping screen add a new group level ―at
the top level‖ of type ―Parent Asset‖.
3. Edit the contents of the ―Page Contents‖ and set the DIV
properties to a Presentation and Content Type of
―Raw HTML‖.
4. Edit the contents of the ―Default Format‖ and:
a. Set the properties of the first DIV to a
Presentation and Content Type of ―Raw
HTML‖ and insert:
h1 {
b. Create a new DIV below the first DIV with a
Presentation of ―Raw HTML‖ and a Content
Type of ―Nest Content‖ and nest the ―Display
Thumbnail‖ Asset Listing.
c. Create a new DIV below the second DIV with a
Presentation and Content Type of ―Raw
HTML‖ and insert:
}
Finally, add a Nested Content Design Area to the Design (in the
<head></head>), and nest the ―List Parent‖ Asset Listing. Now a
104
Single licence copy
thumbnail can be applied to an asset at any level, and it will
display behind the <h1> element via the CSS!
This configuration builds on Notice Link Listing and Nested
Asset Listings, but also incorporates a couple of extra tricks:

A Minimum Depth/Height of ―0‖ includes the Root
Node in the list. This ensures that if the current asset has
a thumbnail, it is included in the list.

Grouping the assets ensures the order of the assets is (for
example) grandparent, parent, current asset (instead of
the reverse which is the default ―no sort‖ order).
List assets in their Asset Map order
An Asset Listing with Direct Links Only set to ―Yes‖ presents
the resulting assets in the same order they appear in the asset
map (like the menu_normal Design Area). This is especially
handy when assets need to be listed in an arbitrary order rather
than sorted by a particular attribute. However, if you want more
than one level of asset to be listed in the asset map order, the
answer is not Asset Grouping, but to nest one Asset Listing inside
the other:
Screencast: http://matrixsecrets.com/book/asset-map-order
1. Create an Asset Listing named ―Top Level List‖ and on
the Details screen, set:
a. Asset Types to List to ―Standard Page‖.
b. Root Nodes to the Root Node of your Site.
c. Direct Links Only to ―Yes‖.
2. Clone the ―Top Level List‖ Asset Listing you‘ve just
created, and on the Details screen set:
a. Page Name and Page Short Name to ―Second
Level List‖.
b. Under Dynamic Parameters set
Single licence copy
105
i. Parameter to ―Replacement Root
node…‖.
ii. Source to ―SESSION Variable Name‖.
iii. SESSION Variable Name to
list_current_asset_id
3. In the ―Second Level List‖, edit ―Page Contents (No
Results)‖ and delete the ―No results were found‖ text.
4. In the ―Second Level List‖, edit the ―Default Format‖ to:
Level 2: %asset_name_linked%
5. Insert a new Nest Content DIV below the existing DIV,
and nest the ―Second Level List‖ asset.
Finally, add a Nested Content Design Area to the Design, and
nest the ―Top Level List‖ Asset Listing. Now if you preview any
an asset, you will see a two level listing of assets, in the order
these assets appear in the Asset Map.
This technique can also be used instead of Asset Grouping
where a group should display even if it has no children.
Print an annual report using Asset Contents
In the last example, we simply listed the link to each asset, but
what if we wanted to list more? For example, your organisation
may publish an Annual Report that is comprised of many
different structured assets. This makes sense in a web
environment, but makes it difficult if the user wants to read or
print the entire document as a whole.
We‘ve just seen how Nested Asset Listings can be used to
represent the structure of assets within the Asset Map: this
concept can also be applied to listing the contents of a group of
assets.
Simply modify the ―Default Format‖ of the ―Second Level List‖ in
the previous example to use the %asset_contents% keyword,
and the HTML formatted contents of each asset will be printed
106
Single licence copy
within the Asset Listing. Combined with some appropriate
formatting of the ―Default Format‖ and ―Page Contents‖
Bodycopies, the report can be formatted in virtually any format
you want.
%asset_contents% also includes formatting from the Paint
Layout applied to that asset. The entire Nested Asset Listing
can be replicated in this way, by nesting another Asset Listing
into the Type Format of the Paint Layout. If you‘d rather
avoid the complexities of nesting Paint Layouts, simply use
the %asset_contents_raw% keyword instead.
Single licence copy
107
ASSET TYPING (PAINT LAYOUTS)
Designs act on the parts of your website that aren‘t content, such
as the header, footer and menu. Conversely Paint Layouts affect
just the content, specifically the Page Body Design Area.
Paint Layouts are a powerful tool, especially when combined
with an internal Metadata Schema, and can be the basis for
creating your own custom assets within Matrix. Paint Layouts
allow you to easily, and entirely change the presentation of an
asset, based on that assets type.
To illustrate this, let‘s expand on the idea of internal Metadata
Schemas, and create a catalogue of DVD assets, similar to that of
Netflix39, Quickflix40 and Webflicks41.
Screencast: http://matrixsecrets.com/book/asset-typing
Start by creating a Folder asset called “DVDs” which will
hold these assets. Then:
Create a Metadata Schema
1. Create a Metadata Schema called ―DVD Catalogue‖, with
a Section called ―Catalogue‖.
2. To the ―Catalogue‖ section, add a:
a. Date Field called ―release.date‖ (with a Min
Date of 1990).
b. Text Field called ―classification‖.
c. Select Field called ―genre‖ with options of:
―Action‖, and ―Drama‖.
3. Apply and cascade this schema to the ―DVDs‖ Folder.
39
http://www.netflix.com
40
http://www.quickflix.com.au/
41
http://www.webflicks.com.au/
108
Single licence copy
Create a Paint Layout
1. Create a new Paint Layout named ―Catalogue‖.
2. On the Details screen, add a Custom Asset Type for
―Multiple Page Pages‖ and ―News Items‖.
3. Apply this Paint Layout to the ―DVDs‖ Folder (on the
Lookup Settings screen).
Add 3 DVD movies
Add 3 News Item assets to the ―DVDs‖ Folder, and populate the
content and metadata fields. Use the ―News Headline‖ for the
title of the movie, the ―Summary‖ field for a brief synopsis, and
the metadata fields for the other details.
If you‘re stuck for ideas for the dummy data, try:

The Dark Knight, 2008, Rated: M, Action

Fight Club, 1998, Rated: R, Action

The Joy Luck Club, 1993, Rated: M, Drama
Edit the Paint Layout
Edit the contents of the ―News Item Format‖ to include:
<h1>%asset_name%
(%asset_metadata_release.date%)</h1>
<div id="summary">%asset_attribute_summary%</div>
<dl>
<dt>Type</dt><dd>Movie</dd>
<dt>Genre</dt><dd>%asset_metadata_genre%</dd>
<dt>Classification</dt>
<dd>%asset_metadata_classification%</dd>
</dl>
Preview one of the News Item assets to see the beginnings of a
usable Paint Layout. Next, we‘ll extend this example even further
to handle different types of assets, or in this case, DVDs.
Single licence copy
109
But DVDs aren‘t news items? Don‘t stress – assets in Matrix
can, and have always been used for data other than their
originally intended purpose. The label of an asset attribute
isn‘t important it‘s what you do with it that counts.
Paint Layouts allow you to use any field for any purpose. If
your users are likely to be confused by the labelling, look at
creating an Asset Builder for these assets, as Asset Builders
allow you to label fields in any way you like. The Simple Edit
interface can also be customised in this way.
TV shows (multi-typing)
While Netflix, and Quickflix both offer TV shows as well as
movies, Webflicks has a nice feature of listing other DVDs
available from the same TV series. Because Paint Layouts can be
applied to an entire section of your site, and then customised
based on their type, using different asset types to represent
different content types (or DVD types in this case), we can easily
customise the presentation of each DVD based on its type.
To allow for this functionality, let‘s use Multiple Page Pages to
represent the TV shows, and:
Add a DVD TV Series
1. Create a Multiple Page asset named ―Get Smart‖ and
populate the metadata.
2. On the Pages screen, add two Multiple Page Pages:
―Season 1‖ and ―Season 2‖.
Edit the Paint Layout
Edit the contents of the ―Multiple Page Page Format‖ to include:
<h1>%asset_name%
(%asset_metadata_release.date%)</h1>
<div id="summary">%asset_contents%</div>
110
Single licence copy
<dl>
<dt>Type</dt><dd>TV Series</dd>
<dt>Genre</dt><dd>%asset_metadata_genre%</dd>
<dt>Classification</dt>
<dd>%asset_metadata_classification%</dd>
</dl>
<!— %multiple_page_assetid% —>
<h2>Other
%globals_asset_name:%multiple_page_assetid%
DVDs in this series</h2>
%toc_unordered%
Preview the Multiple Page, and there you have it – a Webflicks
style listing of the current DVD/TV series, with links to other
DVDs in the series. Also note:

Previewing one of the News Items still displays these
DVDs in the original format. This should give you a
glimpse into the power of asset typing.

Previewing the parent Multiple Page actually displays the
first Multiple Page Page. This is by design, and cannot be
changed. Applying a type format for Multiple Pages won‘t
work.
Nested keywords: not strictly a supported feature, but the
above example actually combines two keywords together to
list the asset name of the parent Multiple Page asset. This
works because Matrix first parses the keyword for
%multiple_page_assetid%, which is then available for use
in the %globals_asset_name:X% keyword (where X is the
asset ID).
Single licence copy
111
Keep it simple
If something can be done via a Design, use a Design. If you‘re
about to apply a Paint Layout to an entire Site, you‘re probably
over-thinking it. Consider that:

Paint Layouts are optional, and therefore add complexity
to any implementation;

less users know how to use/modify Paint Layouts
(remember Paint Layouts are hidden on the Lookup
Settings screen);

older versions of Matrix require Paint Layouts to be
applied by URL, rather than by asset, and are therefore
less robust.
The finishing touch: edit the ―Folder Format‖ and nest a
Dynamic Asset Listing (see The Image Gallery Asset Listing)
in this Bodycopy. This would allow the Folder to list all the
DVDs under it. You could even put all the DVDs into
categories represented by Folder assets, and have the Asset
Listing also list these Folder assets.
112
Single licence copy
SEARCH LISTINGS
Despite everything we‘ve just learnt about Asset Listings, there is
one thing that Asset Listings can‘t do well: conditionally list
assets.
Asset Listings can only filter assets on very specific asset
attributes like asset type, link value and root node. Search Pages
on the other hand, allow assets to be conditionally filtered based
on any attribute, any content or any metadata associated with
these assets.
Extending on the Webflicks example in Asset Typing (Paint
Layouts), let‘s create a Search Page asset which creates a list of
DVDs with a common attribute. If you haven‘t already followed
the steps in the Asset Typing (Paint Layouts) chapter, you‘ll
need to follow those steps first.
Screencast: http://matrixsecrets.com/book/search-listings
The Father’s Day DVD list
Create a Search Page asset named ―Father‘s Day‖, and on the
Details screen set:
1. Root Nodes to the ―DVDs‖ Folder.
2. Asset Types to Search for to ―News Item‖ and
―Multiple Page‖.
3. Select all Search Statuses.
4. Under ―Stored Search‖ set Stored Query Location
a. Parameter to ―Search all fields‖.
b. Source to ―Current Asset‖.
c. After committing, set Current Asset to
―Keyword‖ to ―asset_metadata_genre‖.
5. Show the Results page to ―Yes‖.
Single licence copy
113
On the Search Fields screen:
1. Create a new Search Field named ―all‖.
2. Add a Data Source of ―Include All‖.
3. Set Word Logic to ―Any Word‖.
Now, apply the ―DVD Catalogue‖ Metadata Schema to the Search
Page, and on the Metadata screen, set the ―genre‖ to ―Action‖.
Preview the Search Page, and you should see:

Get Smart

The Dark Knight

Fight Club
If you were expecting to see The Joy Luck Club, well yes, I like
that movie too, but apparently not many Dads do.
This basic idea can easily be extended to search for single or
multiple keywords within the name, or even the content of an
asset, for example searching for:
 multiple genres like action and comedy;
 all DVDs from a single year or date range;
 all DVDs with the word ―fight‖ in the title.
One big advantage a Search Page asset has over an Asset
Listing is it doesn‘t rely (as much) on the user to correctly
categorise or position an asset. Where an Asset Listing
requires an asset to be in a particular section of your site, a
Search Page asset, just like a regular search, allows assets to
be located anywhere in your system.
114
Single licence copy
ADVANCED
MATRIX
TECHNIQUES
Single licence copy
115
MATRIX ON YOUR DESKTOP
Sometimes you need a test area to work in, or want to try
something you wouldn‘t normally have access to. Sometimes you
just want to break something. For these reasons and more, it can
be very handy to have a second test version of Matrix that you
can do what you want with.
Enter the Virtualisation. Virtualisation allows you to run Matrix
right on your desktop. Virtualisation allows you to run a
complete operating system within an existing Windows, Mac OS
X, or Linux installation.
For example, Mac users may use virtualisation software like
VMware Fusion or Parallels when they want to run a Windows
only application like Internet Explorer on their Mac.
System Requirements

Administrator rights to your computer (so you can install
some software).

A minimum of 4000 Megabytes (4 GB) of free space.

A minimum of 512 Megabytes of RAM.
This process also requires you to download about 1 GB of data.
Screencast: http://matrixsecrets.com/demo/
Download and install VirtualBox
Download the latest version of VirtualBox42 (under "VirtualBox
binaries"). Once downloaded, install VirtualBox, selecting all the
default options.
42
http://www.virtualbox.org/wiki/Downloads
116
Single licence copy
Download the Matrix Virtual Machine (VM)
The compressed version of the Matrix Virtual Machine43 needs to
be extracted and uncompressed. Extract the Virtual Machine file
"matrixsecrets.vdi" to a location you will remember.
Install the Matrix VM
1. Start VirtualBox.
2. Create a "New Machine" and follow the steps in the
Wizard:
a. Name the VM, for example Matrix 3.24.0).
b. Set the Operating System to "Linux".
c. Set the Version to "Ubuntu".
d. Use the default setting for base memory
(RAM) (256mb is the minimum you should use if
possible).
e. Click the "Existing..." button to choose a Virtual
Hard Disk.
f.
Click the "Add" button to add a new Virtual Hard
Disk.
g. Choose the "matrixsecrets.vdi" file which you
extracted earlier.
h. Click the "Select" button to choose this Virtual
Hard Disk, and click "Next" and/or "Finish" to
exit the Wizard.
Done!
You should now have a Virtual Machine in your list that will be
"Powered Off". Click the "Start" button to boot the VM, and
follow the onscreen instructions.
43
http://matrixsecrets.com/demo/
Single licence copy
117
OUTPUT CONTENT TO A FILE
As well as HTML and text, Matrix can be configured to directly
output XML, CSV, RTF and even Word and Excel documents, so
that users can directly download and work with these files.
In Manage your Content, we looked at some of the
disadvantages documents have over regular HTML pages. While
this advice still applies, especially for information your
organisation needs to provide to the public, occasionally it can be
useful to output the content of a page as a file. Some examples of
why you might want to output to a file format include:

to allow staff to download an XML file so it can be
imported into another system;

to generate a Word Document which needs to filled in,
signed and faxed;

to create an Excel Document, which can then be used to
generate a graph.
The technique for outputting to each format is essentially the
same: we trick the browser into thinking it‘s downloading a
particular type of file instead of a regular HTML page. To do this,
we need to create a special design that can be applied to an asset,
or a group of assets in Matrix.
For each file type, we‘ll specifically look at the code that needs to
be included in the Design file, but generally, the code will be as
follows:
<MySource_PRINT id_name="__global__"
var="content_type"
content_type="X" />
<MySource_AREA id_name="page_body"
design_area="body" />
<MySource_PRINT id_name="__global__"
var="content_attachment" extension="Y" />
For each file type, we need to substitute X for the file type, and Y
for the file extension. It‘s also important that any asset these
Designs are applied to has all its DIVs set with a Presentation
118
Single licence copy
and Content Type of ―Raw HTML‖, otherwise Matrix will insert
<div> tags where we don‘t want them.
Now let‘s look at how to configure the Design for each type of file.
RTF documents
RTF documents are more widely supported than Word
Documents, allow for the rich formatting for text, and don‘t
contain Macros/potential viruses.
To output the content of a page as a RTF document, create and
apply a Design as follows:
Screencast: http://matrixsecrets.com/book/file-rtf
<MySource_PRINT id_name="__global__"
var="content_type" content_type="application/rtf"
/>
<MySource_AREA id_name="page_body"
design_area="body" />
<MySource_PRINT id_name="__global__"
var="content_attachment" extension="rtf" />
Next, create and save an RTF document in Microsoft Word, or
any of the many other text editing applications that can save as
RTF.
Finally, open the document in a text editor like Notepad, and
paste the entire raw text into the Page Contents DIV.
Now, if you preview the asset that has the RTF Design applied to
it, your browser should prompt you to save the RTF file.
Word documents
Pre-2007 versions of Microsoft Word used a proprietary file
format which was very difficult for other applications to work
with. Office 2007 (and older versions of Word using a
compatibility update) uses an XML format: .docx instead of the
old .doc. Although this is comprised of XML, its file format is
compressed and is therefore still difficult to use within Matrix. A
Single licence copy
119
nice way around this problem is to use plain old HTML, as this is
something Word does understand.
To output the content of a page as a Word document, create and
apply a Design as follows:
Screencast: http://matrixsecrets.com/book/file-word
<MySource_PRINT id_name="__global__"
var="content_type"
content_type="application/msword" />
<MySource_PRINT id_name="__global__"
var="content_attachment" extension="doc" />
<html>
<body>
<MySource_AREA id_name="page_body"
design_area="body" />
</body>
</html>
If you now preview an asset with this Design applied, your
browser or operating system should attempt to open the file in
Microsoft Word. From there, you save the Document into a Word
format and switch the View back to ―Page Layout‖ (from ―Online
Layout‖).
Excel documents
To output the content of a page as an Excel document, create and
apply a Design as follows:
Screencast: http://matrixsecrets.com/book/file-excel
<MySource_PRINT id_name="__global__"
var="content_type"
content_type="application/msexcel" />
<MySource_PRINT id_name="__global__"
var="content_attachment" extension="xls" />
<MySource_AREA id_name="page_body"
design_area="body" />
120
Single licence copy
Once the Design is applied, create a simple spreadsheet in
Microsoft Excel and save the file as an ―XML Spreadsheet‖. Open
this saved XML file in a text editor and paste the contents into
your page.
If you now preview an asset with this Design applied, your
browser or operating system should attempt to open the file in
Microsoft Excel.
Asset Listing iCal
In the previous examples, the data we inserted into our files was
static. Let‘s extend these examples by inserting dynamic data via
an Asset Listing, and creating an iCal formatted calendar.
Screencast: http://matrixsecrets.com/book/file-ical
First, we need to create an Asset Listing to list Calendar assets.
As in the previous examples, it‘s important this Asset Listing has
all its DIVs set to have a Presentation and Content Type of
―Raw HTML‖, otherwise Matrix will insert <div> tags where we
don‘t want them.
Then format the Asset Listing Page Contents as:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//iCal title//NONSGML v1.0//EN
%asset_listing%
END:VCALENDAR
And format the Asset Listing Type Format as:
BEGIN:VEVENT
DTSTART:%event_start_time_ical%
DTEND:%event_end_time_ical%
SUMMARY:%asset_attribute_description%
END:VEVENT
Finally, create a Design, and apply it to the Asset Listing:
Single licence copy
121
<MySource_PRINT id_name="__global__"
var="content_type" content_type="text/calendar" />
<MySource_area id_name="body" design_area="body"
/>
Now, if you preview this Asset Listing, your browser should
launch the application that handles iCal files.
122
Single licence copy
DIY PROBLEM SOLVING
This is an advanced topic and requires directly editing the PHP
source of Matrix. This will void any warranty you have with
Squiz, but may be useful if you‘re supporting your own system, or
if there is a bug you need to find a workaround for urgently.
Some bugs or problems in Matrix can be difficult to diagnose,
especially when you can‘t see the error output. A handy function
called error_log exists to output a message or variable to the
Matrix Log Manager.
For example, the Linux distribution Debian Etch installs a
version of tidy from September 1, 2005 by default. This version
of tidy doesn‘t include the ―preserve entities‖ option, and causes
tidy to fail. However Matrix simply calls tidy, and doesn‘t pass
back any of its messages or errors. To address this problem, we
can directly edit the file html_tidy.inc which is in
/matrix/fudge/wysiwyg/plugins/html_tidy/ (where /matrix is
the directory in which Matrix is installed) to include:
exec($command, $tidy, $return);
// Add this line to find out what tidy is doing.
error_log('tidy: ' . $command);
Now that we‘ve added this extra line of code to Matrix, we need
to initiate the command by saving some content in a WYSIWYG
cell. Once we do this, the tidy command is executed and the
output is printed to the Matrix error log, which can be accessed
on the Details Screen of the ―Log Manager‖.
In this example, the relevant output from the Log Manager is:
/bin/echo 'HTML PUBLIC "-//W3C//DTD HTML 4.01
Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
name=”description” content=”test content" />
Some test content'.
| /usr/bin/tidy -iq –asxhtml
—preserve-entities 1—show-body-only 1
—show-errors 1—show-warnings 1—wrap 0—quote-marks 1
—word-2000 1—force-output 1—char-encoding latin1
Single licence copy
123
-access 1—new-inline-tags sq_wysiwyg_embed_movie",
"sq_wysiwyg_embed_youtube 2>&1
and if we then try and execute this command on the server
Matrix is installed on, we receive the error ―Config: unknown
option: preserve-entities‖ (ie. the version of tidy installed does
not support that parameter).
Using this function has two benefits:
1. If you organisation has someone with PHP skills
internally, they may be able to fix or patch a problem
quickly.
2. It can provide greater insight into the issue, and
potentially initiate a quicker turn around for bug fixing
and support issues, because more information can be
provided to developers.
If you do decide to act on the information in the error log, it‘s
important to consider how this will affect your warranty.
124
Single licence copy
TRIGGERNOMETRY
Triggers are a flexible way to automatically perform a variety of
actions, or to automate repetitive tasks within Matrix, based on a
specific set of conditions.
Let‘s look at some of the more common uses for Triggers.
Keep Triggers specific. Triggers can affect system
performance and should be used with caution. Make Triggers
as specific as possible, and review Triggers on a regular basis.
Clear the cache
Users shouldn‘t have to clear the cache of an asset whenever it‘s
updated, so let‘s do it for them. To automatically clear the cache
when a user updates an asset, create a Trigger with:

Event of ―Status Changed‖.

Condition of ―Asset Status‖ of ―Live‖.

Action (1) of ―Clear Matrix Cache‖.

o
Check ―Include Current Asset‖.
o
Level of ―Selected assets and their dependants‖.
Action (2) (if available and applicable): ―Clear Squid
Cache‖, with ―Include Current Asset‖ checked.
This assumes users are using ―Safe Edit‖ and not editing live
pages, otherwise, use the ―Asset Updated‖ event instead.
Send an email
Typically you‘ll want to send an email using Triggers for one of
two reasons: first, to send an email when it wouldn‘t otherwise
be possible within Matrix or secondly, to be notified when an
event in the system occurs. Looking at the latter, let‘s send an
email whenever a Search Page asset is created, to help monitor
the use of these resource-heavy assets. To do this, we create a
Trigger with:
Single licence copy
125

Event of ―Asset Created‖.

Condition of ―Asset is of type‖ of ―Search Page‖.

Action of ―Send Email‖.
o
Choose a User asset, User Group asset, or enter an
email address to send to.
o
Add a From address, Subject and Body.
Now, whenever a Search Page asset is created, you can be
notified about it.
Review an asset in six months time
A common piece of functionality people look for in a content
management system, is the ability to remind users when an asset
should be reviewed for its content. For example, let‘s set an asset
to ―Up for review‖ six months after an asset is updated. To do
this, create a trigger with:

Event of ―Status Changed‖.

Condition:

o
Asset Status of ―Live‖.
o
Asset is of type to ―Standard Page‖.
Action of ―Set Metadata Field Date‖.
o
Choose (and create if necessary) a Metadata Date
field to use to record the date when the asset
should be reviewed (use an internal Metadata
Schema as mentioned previously).
o
Set the offset to six months.
In this case, we assume we only want to review Standard Pages,
because DIVs, Asset Listings, Images etc. normally don‘t need to
be reviewed. Again, this assumes users are using ―Safe Edit‖ and
not editing live pages. It‘s possible to use the ―Asset Updated‖
event in this case, but this event happens more often and does
not always indicate a page has actually been updated. For
126
Single licence copy
example, an Asset Updated event will be triggered if a page is
modified, but the changes are never made live.
Reminders
Before the Metadata time option was added to Triggers,
reviewing an asset relied on its ―Up For Review‖ status, which
could also be initiated via Triggers. When an asset‘s status is set
to ―Up For Review‖, the users in the first step of any applied
Workflow Schema and the users with Administer permissions to
the current asset, will be emailed that the asset needs to be
updated.
Using this functionality is no longer recommended because it‘s
less flexible, requires workflow, and puts far more load on the
system. Automatic reminders can be problematic for other
reasons. Consider:

Who should the reminder be sent to? Is this user/email
address associated with the asset in some way, or is the
association arbitrary? What happens when the user
leaves the organisation temporarily or permanently?

If such a reminder is in place, what happens when a large
section of a website goes live at the same time? Should
hundreds of reminder emails (one for each asset) be sent?
If automatic reminders are a must for your organisation
regardless of these issues, copy the Send an Email trigger, and
change:

Event to ―Status Changed‖.

Conditions to:
o
Asset Status of ―Live‖.
o
Asset is of type to ―Standard Page‖.
If you‘re after something a little more manageable, see the
Asset Management Interface in The Matrix API.
Single licence copy
127
A more specific review date
So far, we‘ve looked at changing the review date of the current
asset, however, it‘s sometimes useful to apply the review date to
an asset other than the asset just updated. For example, an Asset
Listing of news items might never be updated, rather, new assets
would be created as children of the Asset Listing. In this case,
change the trigger to:

Event of ―Asset Created‖.

Condition to ―Tree Location‖ (set Asset is under to
the Asset Listing).

Action: as before, but choose the Asset Listing rather
than the current asset.
Image Varieties
In Encourage Content Sharing, we saw how Image Varieties can
be used to manage a collection of images. While there will always
be cases where an image needs to be a custom size, it‘s easy to
define a standard set of image sizes for use across an entire
Matrix system. An example Trigger could be:

Event of ―Asset Created‖.

Under Condition set

o
Asset is of type to ―Image‖.
o
(optional) Tree Location to the Media Folder.
Action to Create Image Variety.
o
Check ―Ignore Permissions‖.
o
Name to ―thumbnail‖, constrain Width of ―100‖.
o
Name to ―medium‖, constrain Width of ―300‖.
Batching
The Batching screen on the Trigger Manager allows you to
simulate a trigger action on a single asset, or a group of assets.
This is useful for testing Triggers, but also allows you to perform
128
Single licence copy
a once off action on a large group of assets. For example, if you
wanted to create a Folder asset under every Standard Page, a
Trigger based on an action of ―Asset Created‖, could easily be set
up to create a new Folder asset as a child of the current asset.
Then, on the Batching screen, set the ―Target Node‖ to an entire
site, and check the ―Asset Created‖ event. This tells Matrix to
simulate the Asset Created event on all assets specified, which
then fires the Trigger we‘ve just created.
This sort of action will be resource intensive, and should be
done when the server is under minimal load.
Enforce business rules
If there is a business rule within your organisation that can‘t be
enforced using standard Matrix functionality, chances are it can
be enforced using Triggers. This works using the ―fail‖ action of a
Trigger, which prevents the action the user was attempting to
perform from occurring. Some examples of this could be:

Preventing the creation and use of certain types of assets
like Sites, Roles, Users and so on for security or
performance reasons.

Preventing the creation of certain types of assets in
certain locations, for example, the creation of Image or
File assets outside the Media Folder.
To create a Trigger which prevents a File asset from being
created outside the Media Folder, set:

Event to Before Asset Created.

Conditions:

o
Tree Location to any Site outside of the Media
Folder.
o
Asset is of type to ―Image‖.
Action: Fail, with Trigger an error of type set to
Error, and include a descriptive error message.
Single licence copy
129
If a user then tries to create a File asset outside of the Media
Folder, that will receive a Matrix error, with the message you
specified in the Error section of the Trigger.
If the Trigger an error of type option is set to ―Notice‖ or
―Warning‖, the asset will still be created, but the user will receive
a warning with a message. As opposed to the ―Error‖, the
―Notice‖ and ―Warning‖ messages are fairly subtle and could be
missed.
Create a collection of assets
A collection of assets can be useful when trying to represent a set
of data across multiple pages or assets, as we saw in Asset Typing
(Paint Layouts). Because this group of assets will often be
presented using a Paint Layout, and the assets need to be of a
certain type, in a certain format.
Screencast: http://matrixsecrets.com/book/asset-collection
Consider if we wanted to create the following set of assets to
represent an annual report:
Whenever a standard page named Annual Report is created, we
can use two Triggers to create this structure by setting:

Event to ―Asset Created‖.

Condition, Tree Location of ―Asset is under‖ to the
site which will contain the annual reports.

Action to ―Create Asset‖ and:
130
Single licence copy
o
Create a new Standard Page: ―Executive
Summary‖.
o
Create a new Standard Page: ―Sales Targets‖.
o
Create a new Standard Page: ―Staffing‖.
Then for the second level of assets, set:

Event to ―Asset Created‖.

Condition, Attribute Value to ―Standard Page‖
attribute Name equals ―Sales Targets‖.

Action to ―Create Asset‖ and:
o
Create a new Standard Page: ―Summary Table‖.
o
Create a new Folder: ―Attachments‖.
Now, if you try and create a new Standard Page named Annual
Report 2010, you should see additional assets created in the
structure we specified.
URL based actions: many asset actions can be performed by
specifying parameters via a URL, and using the ―Asset
Accessed‖ event and the ―URL matches‖ condition. This
functionality is greatly enhanced using JavaScript API asset.
Single licence copy
131
THE MATRIX API
The DB Data Source asset is used to integrate Matrix with other
database-driven systems, and it allows the execution of SQL code
on an external system. However, the DB Data Source asset can
also be configured to point at the very system it‘s running in.
This means all of the raw data within your Matrix system can
now be accessed from within Matrix! Let‘s look at some examples
of exactly what this means.
The following instructions are for a PostgreSQL installation.
If your installation of Matrix uses Oracle, consult with your
Oracle DBA for specific connection details, and SQL syntax.
Configure the connection
Screencast: http://matrixsecrets.com/book/matrix-api
1. Create a DB Data Source asset.
2. On the Details screen enter your connection details. A
standard Matrix install will have (adjust as necessary):

Username set to ―matrix‖.

Password (leave blank).

Complete DSN to
pgsql:dbname=mysource_matrix
3. On the Query Builder screen, add to the SQL Query field:
SELECT * FROM sq_ast LIMIT 10; and commit the
changes.
If the connection is successful, the Query Builder screen should
present a list of ―Available Keywords‖, and the DB Data Source
will now have ten child assets, each with the results of the query.
The following sections will have you dealing directly with the
database that Matrix needs to function. An incorrectly
executed SQL statement can severely harm or
132
Single licence copy
completely break your installation of Matrix, so
proceed with caution. Ideally, you should never run untested
SQL queries on a production installation of Matrix or connect to
the DB as a user who can alter data.
Retrieving data
Before running these queries, create a separate read-only
user with access to only the tables you specify. Use the
createuser command (answering no to all questions), then
in your database execute GRANT SELECT ON sq_ast TO
readuser; substituting sq_ast for each table that needs to
be used.
Although these queries can be performed directly on the
database, you might find yourself in a situation where you don‘t
have direct access to the Matrix database, or you need to provide
some information to someone that wouldn‘t normally have direct
database access.
Once these queries are performed, the Details screen of each
Data Source Record Set will display the data requested.
Who has the locks on the HIPO Herder?
Older versions of Matrix don‘t tell you who has locks on the
HIPO Herder, which is a problem when a HIPO job of yours
becomes stuck.
SELECT a.name
FROM sq_lock l, sq_ast a
WHERE l.sq_lock = 'hipo_herder'
AND l.userid = a.assetid;
The size of the message table
This table can become unmanageably large, and often needs to
be cleaned up via the scripts/remove_internal_message.php
script. To determine exactly how big the table is:
Single licence copy
133
SELECT COUNT(msgid) FROM sq_internal_msg;
All User assets that are Under Construction
If a user enters their password incorrectly three times in a row,
their User asset will be set to Under Construction, meaning they
can‘t login again until this asset is set Live again.
This list could be handy for your helpdesk when users call to say
they can‘t login to Matrix.
SELECT name, assetid
FROM sq_ast
WHERE type_code like '%user'
AND status = '2';
Raw number of assets in the system
Assuming there are 44 assets in the system when Matrix is first
installed (this varies between Matrix installations), this SQL
statement will calculate the raw number of assets in your Matrix
system. ―Raw‖ refers to the fact that a Standard Page has one
Page Contents Bodycopy, and at least one Content DIV and
WYSIWYG content type, and so all these assets count toward the
total number of assets.
SELECT (count(assetid)-44) as ASSETS
FROM sq_ast;
Number of non-dependent assets in the system
A more accurate count of the number of assets in your system
can be estimated by only counting non-dependent assets.
Dependent assets are those assets that are required for the main
asset to function, such as the Page Contents Bodycopy from our
previous example. Again, we assume there are 44 assets in the
system when Matrix is first installed.
SELECT count(distinct a.assetid)
FROM sq_ast a, sq_ast_lnk l
134
Single licence copy
WHERE cast(a.assetid as int) > 44
AND l.is_dependant != '1'
AND l.minorid = a.assetid
As well as the fact that assets are deleted in Matrix (and asset Ids
are never reused), dependent assets are the reason you can‘t
simply take the asset ID of the newest asset as an accurate count
of the number of assets in the system.
List all assets updated in the last week
This can be especially handy for keeping track of what changes
are being made system-wide, or for an estimate of how much
editing is occurring on your system over a given time.
SELECT a.updated, a.assetid, l.url
FROM sq_ast a, sq_ast_lookup l
WHERE a.updated > current_date - integer '7'
AND a.assetid = l.assetid;
Listing data
Now that we know how to access all the juicy bits of data Matrix
holds, let‘s do something with this data. To list all assets updated
in the last week, use the SQL above in the DB Data Source asset,
then create an Asset Listing, and:
1. On the Details screen set:
a. Asset Types to List to ―Data Source Record
Set‖.
b. Root Nodes to the DB Data Source asset.
2. Edit the contents of the ―Default Format‖ and insert:
(%ds__assetid%) %ds__url% - %ds__updated%
Preview the Asset Listing, and you should see a list of all the
assets updated in the last week including their asset IDs, URLs
and dates updated.
Single licence copy
135
As the keywords in DB Data Source assets are dynamically
generated (based on the query), they are only listed on the
Query Builder screen of the DB Data Source after the query
has been run. These keywords default to the name of the
columns being selected, but these keywords can be renamed
using AS in your SQL. For example: SELECT assetid AS
ID from sq_ast; will rename the assetid field to ID.
Dynamically listing and retrieving data
Expanding on the previous example of assets updated in the last
week, let‘s generate the same list of assets but restrict the list to
assets updated in the last week by the current user only. To do
this, we want to create a SQL statement of:
SELECT a.updated, a.assetid, l.url
FROM sq_ast a, sq_ast_lookup l
WHERE a.updated_userid = '12'
AND a.updated > current_date - integer '7'
AND a.assetid = l.assetid;
where we will substitute ‗12‘ for the asset ID of the current user.
On the Dynamic Variables screen of the DB Data Source asset we
created in the previous example:
1. Add a new Dynamic Variable with the Name of ―user‖
and an empty Default Value.
2. Add a new Data Mapping with a Parameter of
―Variable: user‖ and a Source of ―Current User‖.
3. Set the Source/Current User to ―Keyword‖ and enter
asset_assetid
Now, on the Query Builder screen, enter the query as:
SELECT a.updated, a.assetid, l.url
FROM sq_ast a, sq_ast_lookup l
WHERE a.updated_userid = %%user%%
AND a.updated > current_date - integer '7'
AND a.assetid = l.assetid;
136
Single licence copy
Preview the Asset Listing, and you should see the same list of
assets updated in the last week as in our previous example, but
this time, the list is restricted to assets updated by the user you
are logged in as.
More dynamism is possible by using any attribute from the
current user, current asset, current site, or a POST, GET or
Session variable, just as you would when using Asset Listings.
Also as with Asset Listings, simply nest the DB Data Source
into the Design and it will start using these dynamic
variables.
The Asset Management Interface
As we looked at in Triggernometry, there are some problems
with using the Up For Review status (and email Triggers) which
are used to remind users to review content. A much nicer
alternative could be the idea of an ―Asset Management Interface‖
– somewhere that users can log in to in order to view a list of all
the assets they are responsible for, sorted by the date they were
last updated. This interface could also include information on:
1. Asset status.
2. Asset name and other asset attributes.
3. A link to the Administration Interface to directly edit the
asset.
To create this interface, start by adding this query to the DB Data
Source asset we used in the previous example:
SELECT DISTINCT a.assetid, a.name, a.updated,
a.status
FROM sq_ast a, sq_ast_perm p
WHERE a.type_code = 'page_standard'
AND a.assetid = p.assetid
AND (p.userid = %%user%% OR p.userid IN
(SELECT majorid
FROM sq_ast_lnk
WHERE minorid = %%user%%
Single licence copy
137
LIMIT 100))
AND p.permission >= '2' AND p.granted = '1'
ORDER BY a.status, a.updated
LIMIT 200
This query:
1. Selects the asset ID, name, last updated date and status
code of assets.
2. Limits the selection to Standard Pages that:
a. the current user has been directly granted Write
permission or Administrator permission; or
b. a group the current user is a direct member of has
been granted Write or Administrator permission.
3. Limits the selection to 200 assets.
Depending on the statuses of the assets being listed, it may be
necessary to use the CASE function in PostgreSQL (DECODE
in Oracle) to order the assets in the way you want, based on
the status code of each asset.
If your system uses LDAP users instead of regular Matrix
users, substitute SELECT majorid FROM sq_ast_lnk WHERE
minorid = %%user%% LIMIT 100 with SELECT majorid
FROM sq_shdw_ast_lnk WHERE minorid = %%userid%%
LIMIT 100
The major benefits of this interface include:
1. There is less load on Matrix because it doesn‘t need to
send hundreds or thousands of emails whenever each
asset needs to be reviewed, and it doesn‘t need to change
statuses between Live and Up For Review.
2. A user won‘t receive hundreds of emails at the same time
six months after a site goes live.
138
Single licence copy
3. The user gets a simple and immediate overview of the
content they are working with, and can provide users with
shortcuts to edit each asset. This is especially important
for sites with complicated subject-based information
architecture.
Essentially, this should make the job of managing content much
easier for your users.
Matrix database tables
To get you started on creating some queries of your own, here are
the main tables that you‘ll want to work with. Tables do
occasionally change between versions, so have a peek at the data
that‘s in a table for your system before trying to use it.
Table name
Description
sq_ast
Stores just about every asset in Matrix
(including the default installed assets like the
Root User, Media Folder etc.), including its
assetid, type_code, name, short_name and
details of who last updated the asset, and when.
To get more details on an asset, you‘ll need to
join this table with the other tables below.
sq_ast_attr_val
Contains values of attributes for each asset (also
see sq_ast_attr for the attributes for each
asset). Initial values are stored in default_val
column; once these values are changed the
custom_val column is used.
sq_ast_lnk
Different link types for assets to determine:
asset location/parent, designs, paint layouts,
hyperlinks from other assets (notice links) and
more.
sq_ast_lookup
The full URL(s) for each asset.
sq_ast_lookup_value
Assets that Designs and Paint Layouts are
Single licence copy
139
applied to.
sq_ast_mdata_val
The metadata value(s) for each asset.
sq_ast_url
URLs applied to Site assets (and the Designs,
Media and Users folders).
sq_cache
Where the caching system stores its data.
sq_hipo_job
Whenever a HIPO Job is required, this table
temporarily stores its progress (also where
HIPOs go to die). The data in this table is
mostly ―serialised‖, so it‘s hard to do much
other than list/delete jobs.
sq_internal_msg
Everything specified in ―System Configuration‖
-> ―Messaging Service Configuration‖.
sq_lock
Locks to ensure only one user edits an asset at a
time.
sq_rb_*
Archives of the data in other tables used if
Rollback is enabled.
sq_sch_idx
The search index used for Search assets, and the
Quick Search.
sq_shdw_ast_lnk
Used to link Shadow Assets, which are assets
whose attributes aren‘t actually stored in Matrix
(like LDAP users), under other assets.
Almost every query you perform on the Matrix DB will
require a join, because most information is distributed across
more than one table. If your SQL isn‘t quite up to scratch, it‘s
worth learning the basics before attempting to extract even
the most basic of information from Matrix.
140
Single licence copy
Single licence copy
141