tag:blogger.com,1999:blog-118048452024-03-05T05:24:44.342+01:00FinnotypeWriting technical contentAntti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comBlogger30125tag:blogger.com,1999:blog-11804845.post-5917704204278906492014-01-14T17:37:00.001+01:002014-01-15T09:11:41.416+01:00Duplicate heading anchors in ConfluenceThere's a bug in Confluence 4.2 that generates identical IDs for same-name heading elements (<a href="https://jira.atlassian.com/browse/CONF-17962" target="_blank">CONF-17962</a>). The issue is fixed in Confluence 4.3 but here is a workaround for those stuck with Confluence 4.2 or earlier.<br />
<br />
Multiple same-name headings on the same page are OK. In fact, they are quite common. When I document objects that have similar properties I need to repeat headings. The problem in Confluence 4.2 is that you can't link to such headings (anchors). The link always points to the first occurrence of the heading.<br />
<br />
<b>Example</b>: I use the following heading structure in <a href="http://documentation.magnolia-cms.com/display/DOCS/Message+types" target="_blank">message types</a> documentation:<br />
<ul>
<li>Banners</li>
<ul>
<li>Behavior</li>
<li>Levels</li>
<li>Examples</li>
<li>Looks like</li>
<li>How to show</li>
</ul>
<li>Alerts</li>
<ul>
<li>Behavior</li>
<li>Levels</li>
<li>Examples</li>
<li>Looks like</li>
<li>How to show</li>
</ul>
<li>Notifications</li>
<ul>
<li>Behavior</li>
<li>Levels</li>
<li>Examples</li>
<li>Looks like</li>
<li>How to show</li>
</ul>
</ul>
<div>
<br />
Confluence generates IDs using a pattern where page title and heading are concatenated with a hyphen in between:</div>
<pre class="brush:text"><page title>-<heading name></pre>
<br />
<div>
As a result, the IDs of all my "Behavior" headings are identical:<br />
<pre class="brush:text"><h3 id="Messagestypes-Behavior">Behavior</h3>
<h3 id="Messagestypes-Behavior">Behavior</h3>
<h3 id="Messagestypes-Behavior">Behavior</h3>
</pre>
<br /></div>
<div>
<b>Workaround</b>. Add the <a href="https://confluence.atlassian.com/display/CONF42/Working+with+Anchors" target="_blank">Anchor macro</a> in front of the lower level heading. Set the anchor name to the upper level heading followed by a hyphen.</div>
<div>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="http://3.bp.blogspot.com/-CO37calTmHA/UtVhM24WraI/AAAAAAAAMQU/Ow7erEMnKDI/s1600/anchor-macro.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="121" src="http://3.bp.blogspot.com/-CO37calTmHA/UtVhM24WraI/AAAAAAAAMQU/Ow7erEMnKDI/s640/anchor-macro.png" width="640" /></a></div>
<br />
This creates unique IDs:<br />
<pre class="brush:text"><h3 id="Messagestypes-Banners-Behavior">Behavior</h3>
<h3 id="Messagestypes-Alerts-Behavior">Behavior</h3>
<h3 id="Messagestypes-Notifications-Behavior">Behavior</h3></pre>
<div>
<br /></div>
<br /></div>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-33331353244721853632013-12-18T14:38:00.001+01:002014-01-10T15:36:54.628+01:00Keyboard shortcuts that look like keysI spotted this CSS class being used in Chrome keyboard shortcut help. I applied the style to our <a href="http://documentation.magnolia-cms.com/display/DOCS/Keyboard+shortcuts" target="_blank">keyboard shortcut documentation</a> at Magnolia. Now the shortcuts look like actual keys. That was a quick way to add a bit of polish.<br />
<pre class="brush:css;toolbar:false;gutter:false">.kbd {
background-color: #f7f7f7;
border: 1px solid #ccc;
color: #333;
font-size: 13px;
line-height: 1.4;
text-shadow: 0 1px 0 #fff;
font-family: Arial,Helvetica,sans-serif;
display: inline-block;
padding: 0.1em 0.6em;
margin: 0 0.1em;
white-space: nowrap;
-webkit-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
-moz-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
border-radius: 3px;
}
</pre>
<br />
Here's the result:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgf5VHngGT5cewTOIKDaIYmMd930ZlW05aYqmTH7dzX-g2_jEI4C_kvz1ntTfROPfqWCYUfiVSSQzVhi7FC_GdWe7Twa587YHsP55SFZl_17a1E_Mp3ziI2BOPMPoJshEVHrEextQ/s1600/keyboard-shortcuts.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgf5VHngGT5cewTOIKDaIYmMd930ZlW05aYqmTH7dzX-g2_jEI4C_kvz1ntTfROPfqWCYUfiVSSQzVhi7FC_GdWe7Twa587YHsP55SFZl_17a1E_Mp3ziI2BOPMPoJshEVHrEextQ/s1600/keyboard-shortcuts.png" /></a></div>
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-68527476188662415502013-09-23T09:24:00.000+02:002013-09-23T09:47:06.576+02:00Doc Jam 2013<a href="http://www.magnolia-cms.com/conference.html" target="_blank">Magnolia Conference 2013</a> has left town. Time to sum up the results. I organized a Doc Jam session to collect feedback on documentation.<br />
<br />
If you haven't been to a jam session before, it's pretty simple:<br />
<ol>
<li>Name a documentation topic that is missing.</li>
<li>Help us write a table of contents for it.</li>
</ol>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEimW8TUqFnYt9ZHjqgB8_9_ftQg2PcvXiaMi0aYKfZrh43NqXcCusKaOjzVI0Uzm9x0-bDvvPqUHW3YDP9fLl0epFK18B9rBiLE3cWpgql9jvf2wuer9yXOImdbRsq8yr9orSX9GA/s1600/doc-jam.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEimW8TUqFnYt9ZHjqgB8_9_ftQg2PcvXiaMi0aYKfZrh43NqXcCusKaOjzVI0Uzm9x0-bDvvPqUHW3YDP9fLl0epFK18B9rBiLE3cWpgql9jvf2wuer9yXOImdbRsq8yr9orSX9GA/s1600/doc-jam.jpg" /></a></div>
<br />
Here are the top three topics proposed by the attendees.<br />
<br />
<b>1. Managing system health</b><br />
<ul>
<li>How can an administrator tell a system is healthy?</li>
<li>Symptoms and numbers to watch out for (too many nodes?)</li>
<li>Collecting system statistics.</li>
<li>Events to log routinely vs. events to log when in trouble.</li>
<li>Serious vs. harmless log entries</li>
<li>Issue scenarios like what to do when the search stops returning results.</li>
<li>Idea! Create a Health app that provides vital stats.</li>
</ul>
<br />
<b>2. Replicating your environment</b><br />
<ul>
<li>Replicating a complete site to a dev or test environment. </li>
<li>Configuration to change after cloning.</li>
<li>Changing subscribers to avoid publishing content to production.</li>
</ul>
<ul>
</ul>
<br />
<b>3. Activation (publishing) best practices</b><br />
<ul>
<li>Nodes that are OK to activate from author to public.</li>
<li>Nodes that are not OK to activate such as the anonymous role.</li>
</ul>
<br />
Thank you to everyone who proposed topics. We will write about them and post updates.<br />
<br />
If you didn't get a chance to attend the conference, post your request on the <a href="http://forum.magnolia-cms.com/forum/threads.html?forumId=caf52257-62a1-40c4-8da7-cefb66785062&page=1" target="_blank">Magnolia forum</a>. See you next year!<br />
<br />
<br />
<br />
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comBasel, Switzerland47.557421 7.592572700000005247.4716905 7.4312112000000052 47.643151499999995 7.7539342000000051tag:blogger.com,1999:blog-11804845.post-8297333416034067912013-09-12T13:09:00.001+02:002013-09-12T13:09:21.452+02:00Five tips about writing for translation<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjzO6ROHZF2dmqTFT7XsWZgVA6AbPVa7xbW7E_cdCxLj0FuhcDnIeLDk_-wOiqiyTkOzdUp0c-SKFRcBEYUcvKIhX4IO1Ydnq2TjKjVPi-7RMzI7KXGRg2R6doEFwXoiKr1cA3z3A/s1600/pulse-example.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjzO6ROHZF2dmqTFT7XsWZgVA6AbPVa7xbW7E_cdCxLj0FuhcDnIeLDk_-wOiqiyTkOzdUp0c-SKFRcBEYUcvKIhX4IO1Ydnq2TjKjVPi-7RMzI7KXGRg2R6doEFwXoiKr1cA3z3A/s1600/pulse-example.png" /></a></div>
<br />
It is not easy to write text that translates well. We just started translating <a href="http://documentation.magnolia-cms.com/display/DOCS/Magnolia+5+Documentation" target="_blank">Magnolia CMS documentation</a> into Chinese. Here are five insights we learned on the way that make work easier for authors and translators.<br />
<br />
<b>1. Chinese Wikipedia is your friend</b><br />
<br />
Many software terms are well known in their original English form and may not need translation. For proprietary and established terms, check if Chinese Wikipedia translated them.<br />
<br />
If Wikipedia translates the term, you probably should too:<br />
<ul>
<li><a href="http://zh.wikipedia.org/wiki/Web%E5%AE%B9%E5%99%A8">http://zh.wikipedia.org/wiki/Web容器</a></li>
<li><a href="http://en.wikipedia.org/wiki/Web_container">http://en.wikipedia.org/wiki/Web_container</a></li>
</ul>
If Wikipedia does not translate the term, you likely don't need to either.<br />
<ul>
<li><a href="http://zh.wikipedia.org/wiki/Java_Servlet">http://zh.wikipedia.org/wiki/Java_Servlet</a></li>
<li><a href="http://en.wikipedia.org/wiki/Java_Servlet">http://en.wikipedia.org/wiki/Java_Servlet</a></li>
</ul>
<br />
Using commonly accepted, established terms avoids a lot of confusion. Users who read general documentation about the Java platform and Web technologies can apply the terms they learned.<br />
<br />
<b>2. Lower case and upper case don't exist in Chinese</b><br />
<br />
In English we use capital letters to distinguish proper nouns from common nouns. For example, we call the Magnolia message center the "<a href="http://www.magnolia-cms.com/product/features/the-pulse.html" target="_blank">Pulse</a>". It is called the Pulse because it gives you vital information about the state of the system and your workload. When you hold a finger on someone's wrist you get an overall idea of how well they are doing: no pulse = not good. Similarly, the Pulse informs you about tasks and issues you must address.<br />
<br />
All clear? Good.<br />
<br />
In Chinese, the pulse on your wrist and the Pulse are both 脉搏. Same word, identical spelling. Chinese readers cannot tell the difference. Funny as it may be, if they saw a literal translation of "Go to the Pulse and..." they might check their wrist and feel confused.<br />
<br />
In translation we left the English word intact and qualified it. Pulse 信息中心 ("Pulse messaging center") implies that Pulse is a term that has a special meaning.<br />
<br />
<b>3. Cultural jokes don't work</b><br />
<br />
Jokes, puns and expressions that rely on colloquial English translate poorly. Even if the translator knows the meaning of the English expression, there may not be an equivalent in the target language.<br />
<br />
This is usually not a big problem in technical texts which are matter-of-fact and contain few cultural references. But as a writer you need to be alert. We got caught by two obscure expressions in one week: <a href="http://finnotype.blogspot.ch/2013/09/translating-jokes-into-chinese.html" target="_blank">Location, location, location</a> and <a href="http://documentation.magnolia-cms.com/display/DOCS/Configuring+an+app" target="_blank">on-the-fly</a>.<br />
<br />
<b>4. Identify text that doesn't need to be translated</b><br />
<br />
If readers never see the text, why translate it? An example is our <a href="http://documentation.magnolia-cms.com/display/DOCS/_Inclusions+library" target="_blank">Inclusions library</a> where we keep reusable chunks of content. We include the content on other pages. Reuse prevents duplication and makes changes easier - you change the chunk once and the change propagates to wherever the chunk is used.<br />
<br />
The inclusion library page and its children are not displayed in the table contents. In fact, readers actually never hit those pages. The library is just an organizational tool for us editors.<br />
<br />
So we did not translate any inclusion library page titles. We only translated the body text of each chunk since that's what gets blended into Chinese context. This saves us a little bit of time. Interestingly, it is also the only section of Chinese documentation that non-Chinese speakers can still easily identify thanks to the English page titles.<br />
<br />
<b>5. Get help</b><br />
<br />
This last tip is not about writing but the translation process.<br />
<br />
Hire a native speaker with translation experience. I was fortunate to find a Chinese translator who has worked on the Java platform. She is Web-savvy and is planted right in the Magnolia development team in Beijing. Reachable directly, no looping through middlemen, fast turnaround. This arrangement is working very well.<br />
<br />
We also chose a translation agency in case we need to farm out lots of text on a tight deadline. The agency is based in China. We did the homework and had several agencies submit samples, then picked the best.<br />
<br />
<br />
<br />
Got tips about writing text that translates well? Leave a comment.<br />
<br />
<br />
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-62913823533288297412013-09-06T10:18:00.002+02:002013-09-06T10:58:49.983+02:00Translating jokes into ChineseIn Magnolia 5 technical documentation we have a page titled <a href="http://documentation.magnolia-cms.com/display/DOCS/Location%2C+location%2C+location" target="_blank">Location, location, location</a>. The page explains how the system identifies where you are with a URL history fragment.<br />
<br />
Examples:<br />
<br />
I am in the <a href="http://documentation.magnolia-cms.com/display/DOCS/Pages+app" target="_blank">Pages app</a>, editing a page named <span style="font-family: Courier New, Courier, monospace;">about</span>:<br />
<pre class="brush:xml;toolbar:false;gutter:false">#app:pages:detail;/demo-project/about:edit</pre>
<br />
I am in the <a href="http://documentation.magnolia-cms.com/display/DOCS/Contacts+app" target="_blank">Contacts app</a>, viewing a contact named <span style="font-family: Courier New, Courier, monospace;">ldavinci</span>:<br />
<pre class="brush:xml;toolbar:false;gutter:false">#app:contacts:browser;/ldavinci:treeview:</pre>
<br />
Very nifty! This means you can bookmark any location and go back there instantly.<br />
<br />
The document about location fragments is very technical. But the title is a pun. The phrase "location, location, location" is used in real estate for the three most important factors in determining the desirability of a property. The phrase was coined by Harold Samuel, a British real estate tycoon.<br />
<br />
This in an example of a <i>safe joke</i> technical text. Native English speakers get the punchline and have a giggle. But even non-native readers get the point. For them, the repetition emphasizes importance.<br />
<br />
Then things got tricky.<br />
<br />
How do you translate the page title into another language? We are translating technical documentation into Simplified Chinese and we need ground rules regarding what is translatable.<br />
<br />
What would you do?<br />
<ol>
<li>Translate the title as is? (Location, location location)</li>
</ol>
<blockquote class="tr_bq">
位置位置位置</blockquote>
<ol start="2">
<li>Remove the repetition and translate "Location" once?</li>
</ol>
<blockquote class="tr_bq">
位置</blockquote>
<ol start="3">
<li>Keep both languages? We do this with proper nouns that are not translatable such as the Pulse messaging center (Pulse信息中心).</li>
</ol>
<blockquote class="tr_bq">
Location位置</blockquote>
We went with option 2. The pun just doesn't work in Chinese, nor does the repetition really. It was better to focus on clear message than muddling it with an obscure pun.<br />
<br />
But we sure had fun finding the solution. :)<br />
<br />
<br />
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-16736375570371353132013-07-17T09:29:00.000+02:002013-07-17T11:10:23.310+02:00Magnolia Academy launchedWe are launching <a href="http://academy.magnolia-cms.com/display/MA/Magnolia+Academy" target="_blank">Magnolia Academy</a> today. It is a new independent learning resource that teaches Magnolia 5 step-by-step. Code samples, exercises, tests and videos help you learn in a way that suits you best.<br />
<br />
<div style="text-align: center;">
<iframe allowfullscreen="" frameborder="0" height="281" src="//www.youtube.com/embed/6fwDJP9LHek?rel=0" width="500"></iframe>
</div>
<br />
Magnolia Academy targets learners across the globe: a developer in Beijing who wants to put a star on their CV or a system admin in São Paulo who does not have access to classroom training.<br />
<br />
The idea of online courses was raised as we realized that we cannot offer personal training everywhere in the world. Magnolia's growth projections for the next two years made the situation imminent. As problems go, this one is a very nice problem to have. It's good to have growing demand. Responding to that demand just needs quick acting.<br />
<br />
The Documentation, Services and Development teams at Magnolia collaborated to produce online learning modules that range from basic system setup and project best practices to templating and app development.<br />
<br />
<a href="http://academy.magnolia-cms.com/display/MA/Magnolia+Academy" target="_blank">Check it out</a> and post your <a href="http://forum.magnolia-cms.com/forum/thread.html?threadId=2888ab12-77b8-464b-95c4-62a825558aae#44be7358-296a-4a5f-bd84-a52ac3df6408" target="_blank">feedback on the forum</a>.<br />
<br />
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-17252040551814914202013-07-10T14:40:00.001+02:002013-07-10T14:41:57.582+02:00Do you still write "click"?It is a telltale sign of failed user experience when you need to write "click" in technical documentation.<br />
<br />
When did you last read the Twitter user guide? Me neither. Using Twitter is pretty self-evident. Just look at the app and tweet. You don't need documentation.<br />
<br />
Self-explanatory tasks need no docs. They should be intuitive enough to complete by looking at the user interface and relying on past knowledge.<br />
<br />
Creating a folder? Moving a file? Cropping an image? Everyday stuff that should be obvious.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgP45lDdql2MKc7LUlfSI8jPK4dVdiEW8g_99me0OZ2S7SQMtN2N-LF70lFcnKKOtAb3_aH_E4Ajbpy3vhJE6h9AqRxvRg2Ytq7XZn_BkQclcDNZsAs7hdwzRMMKiL0YKV7a012eg/s1600/m5-assets.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgP45lDdql2MKc7LUlfSI8jPK4dVdiEW8g_99me0OZ2S7SQMtN2N-LF70lFcnKKOtAb3_aH_E4Ajbpy3vhJE6h9AqRxvRg2Ytq7XZn_BkQclcDNZsAs7hdwzRMMKiL0YKV7a012eg/s1600/m5-assets.png" /></a></div>
<br />
A huge amount of effort goes into perfecting the user experience in consumer apps. Intuitive UX can lift an app above its competition just as disastrous UX can sink it.<br />
<br />
Great UX is infectious. It sets user expectations. Users start demanding that software at the workplace be just as simple. In that way, consumer software forces enterprise software to adapt.<br />
<br />
For <a href="http://www.magnolia-cms.com/product.html" target="_blank">Magnolia 5</a>, we broke our necks to make Web content management simple. Instead of features galore, we focused on simplicity.<br />
<br />
For the same reason, as a technical writer, I avoid writing things like "click" in <a href="http://wiki.magnolia-cms.com/display/DOCS/Magnolia+5+Documentation" target="_blank">Magnolia documentation</a>. I try to focus on configuration, customization and best practices instead. That's where docs are really needed.<br />
<br />
Other examples that set my alarm bell ringing:<br />
<ul>
<li><i>Check the box to select...</i></li>
<li><i>Press ENTER to submit...</i></li>
<li><i>Double-click the item to open...</i></li>
</ul>
<br />
Are you still writing such phrases? Pause and ask: are you compensating for bad usability?<br />
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-35934258854008986592012-11-15T17:03:00.001+01:002012-11-15T23:11:17.732+01:00Semantic Web still a pipe dreamEleven years ago Tim Berners-Lee said that the next logical step for the World Wide Web was <a href="http://en.wikipedia.org/wiki/Semantic_Web" target="_blank">semantic</a>. The idea was that one day machines could read and understand Web pages. Content would be tagged in a meaningful way: a date would be tagged as a date and an address as an address. Relevance would replace ambiguity. Finding, sharing and combining information would become easier.<br />
<div>
<br /></div>
<div>
Today the semantic Web remains a pipe dream. Here is quick proof:<br />
<div>
<div>
<ol>
<li>When in Basel, Switzerland, go to <a href="http://goo.gl/news/J0WN" target="_blank">Google News</a>.</li>
<li>Look at the top stories.</li>
</ol>
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgUrKRmiK0FydjUbo2f-IBTwjYHxFJ54Om9UjRnIeiLVL6GCB5rrPWUi_zkxzoPHRay5xBTewLytdN-Ig1iDYThg_49WupU1Re6oU-gYNEEq5KK5meX1Wq2NskuZLyoqHd26_120g/s1600/bs.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="471" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgUrKRmiK0FydjUbo2f-IBTwjYHxFJ54Om9UjRnIeiLVL6GCB5rrPWUi_zkxzoPHRay5xBTewLytdN-Ig1iDYThg_49WupU1Re6oU-gYNEEq5KK5meX1Wq2NskuZLyoqHd26_120g/s500/bs.png" width="500" /></a></div>
<div>
<br /></div>
<div>
See a bunch of stories about bank liquidity requirements? Minimum capital levels for financial institutions? How are these stories relevant to you being in Basel?</div>
<div>
<br /></div>
<div>
They are not. Google is doing simple string matching. It detects your geographical location to Basel. It then finds news stories that say "Basel". It doesn't know that the <a href="http://en.wikipedia.org/wiki/Basel_III" target="_blank">Basel III agreement</a> that regulates bank capital adequacy just happens to be named after the city where it was written.</div>
<div>
<br /></div>
<div>
If Google looked at the <a href="http://en.wikipedia.org/wiki/Dateline" target="_blank">dateline</a> of the news item it could see that the story was not written in Basel. It could see that the story is not relevant to you. If all stories <i>had </i>datelines Google might have a chance to do so.<br />
<br />
It's a mess. The <a href="http://documentation.magnolia-cms.com/templates/microformats.html" target="_blank">technology for semantic Web exists</a>. Tagging content is a no-brainer. But we humans are not very good at applying it. We are messy and illogical in our ways. I suppose it is appropriate that we suffer from irrelevant content as a result.</div>
</div>
</div>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-23964076022429760772012-10-16T16:41:00.000+02:002014-04-29T13:48:17.988+02:00Infographics in Technical WritingHave you seen the recent boom in infographics? Everybody and their mom is doing them. Infographics are used to illustrate <a href="http://www.closr.it/show/AUMoiYi7oGE">complex data</a>, <a href="http://mashable.com/2012/09/25/the-evolution-of-digital-advertising-infographic/">timelines</a>, <a href="http://mashable.com/2012/09/12/iphone-apple-stock-price/">trends</a>, <a href="http://miguelinclosedcaption.tumblr.com/post/3526501838/infographic-poster-2-photography-cheat-sheet">cheat sheets</a> and <a href="http://pinterest.com/mashable/infographics/" target="_blank">much more</a>. They make complex processes easier to understand and visualize trends that you can't see with the naked eye.<br />
<br />
Can infographics be used in technical documentation? At Magnolia we drew a <a href="http://documentation.magnolia-cms.com/display/DOCS/Migration">roadmap</a> for migrating from Magnolia CMS 4.4 to 4.5. It is a winding road that involves many tasks. Each milestone is explained on a wiki page in detail.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="http://3.bp.blogspot.com/-W78Op13r_ks/UtPS3geQHyI/AAAAAAAAMOk/IUEiffX0VPE/s1600/migration-process-roadmap-5.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="http://3.bp.blogspot.com/-W78Op13r_ks/UtPS3geQHyI/AAAAAAAAMOk/IUEiffX0VPE/s640/migration-process-roadmap-5.png" height="640" width="219" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
Here are the design guidelines I used in case you want to create an infographic of your own.<br />
<br />
<b>Use a diagram tool</b> such as Visio or OmniGraffle. You will be using lots of boxes and connectors and resizing and scaling the elements. Working with vector shapes is easier and results in a sharp image.<br />
<br />
<b>Max width 1000 px</b>. Keep the width under 1000 pixels. This is a size that everyone can see without scrolling horizontally. Screen resolution does not matter. All modern displays can easily display a 1000 px wide image. What matters is the browser window size. Not everybody browses in full-screen mode. I know this because Google Analytics provides a handy <a href="http://analytics.blogspot.ch/2012/06/new-feature-conduct-browser-size.html">Browser Size</a> visualizer. It tells me that 90% of visitors to the <a href="http://wiki.magnolia-cms.com/display/WIKI/Community+Wiki" target="_blank">Magnolia wiki</a> see the migration roadmap without horizontal scrolling. That's a comfortable margin.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhouxP-a5mrO3KlQfghyphenhyphenkXs6Xliy-4o2ElY2LL0RcAh1rF6qU82z4ImfEOL8AiFJPhOgOzEkrV86xrp8GnGs-AuyTA3kMfvHY2rLSrJ-ubxs2QxKVsZIGj2xGX8kEXv-nFacEBLqQ/s1600/browser-size-graph.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhouxP-a5mrO3KlQfghyphenhyphenkXs6Xliy-4o2ElY2LL0RcAh1rF6qU82z4ImfEOL8AiFJPhOgOzEkrV86xrp8GnGs-AuyTA3kMfvHY2rLSrJ-ubxs2QxKVsZIGj2xGX8kEXv-nFacEBLqQ/s500/browser-size-graph.png" height="279" width="500" /></a></div>
<br />
<b>Max height = 3 x width</b>. I made up this rule. I don't like excessive vertical scrolling either. If your infographic is intended for printing, a tall image will spill on too many pages.<br />
<br />
<b>Legible, large fonts</b>. Corporate identity might dictate the font you must use. Fortunately, you have a large canvas so go big. The purpose of an infographic is not to show all the gritty details. The point is to abstract the details and show trends and conclusions. If you use an infographic to support technical documentation then put details in the supporting documentation pages. There is a temptation to cram lots of tiny items into the image. Resist, my friend.<br />
<br />
<b>Cut clippings and use them in the supporting documentation</b>. If you do a roadmap diagram like I did, you may want to cut it up and use the pieces to illustrate the supporting documentation. They will create visual connections that make the reader go "oh yeah this is the step I already saw in the big picture."<br />
<br />
Inspiration and examples:<br />
<ul>
<li><a href="http://pinterest.com/mashable/infographics/">Pinterest.com: infographics</a></li>
<li><a href="http://www.coolinfographics.com/">Cool Infographics</a></li>
<li>Did you know that Florence Nightingale was not only a nurse but also a statistician? Check out <a href="http://en.wikipedia.org/wiki/File:Nightingale-mortality.jpg">this early polar area diagram</a> illustrating the causes of mortality during the Crimean War.</li>
</ul>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-88162612167534000452012-04-02T16:59:00.000+02:002014-01-13T12:51:16.462+01:00Start a puzzle, learn about your colleagues– Austrasse, that's in my neighborhood!<br />
– Wettstein, I know where that is!<br />
– The river is almost complete.<br />
<br />
<div class="separator" style="clear: both; margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhf7T_3BHa5NyD00zPw1uEp_1EmKTx9D-d2b7HbaaBjRHbSRCteVlkNI1UD_Ag1F_UWuWQW6gpiAbKcOEKUW3OuI3K6XPloRveXx5nSyYrTWHiVnFQpFcY4wdgGRsjLFZ3jrJBWbw/s1600/basel-puzzle.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhf7T_3BHa5NyD00zPw1uEp_1EmKTx9D-d2b7HbaaBjRHbSRCteVlkNI1UD_Ag1F_UWuWQW6gpiAbKcOEKUW3OuI3K6XPloRveXx5nSyYrTWHiVnFQpFcY4wdgGRsjLFZ3jrJBWbw/s1600/basel-puzzle.jpg" style="cursor: move;" /></a></div>
<br />
We set up a thousand-piece <a href="http://www.helvetiq.ch/en/puzzles/45-mypuzzle-basel-7640139530165.html">Basel city map puzzle</a> at one of the desks at Magnolia. (Yes, we sometimes work too.) The puzzle is made by Helvetiq, the company that makes the <a href="http://www.helvetiq.ch/en/games/21-helvetiq.html">trivia quiz game</a> of the same name.<br />
<br />
It turns out that a puzzle is a great way to learn about your co-workers. This is useful if you have <a href="http://www.magnolia-cms.com/our-company/jobs.html">lots of new staff like at Magnolia</a>.<br />
<div class="separator" style="clear: both; text-align: center;">
<br /></div>
People walk by the desk and solve a piece here, another there, explaining where they live and how they know the city. I can't imagine a better ice breaker.Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-40390630854246923062012-01-17T14:13:00.000+01:002012-01-23T10:34:10.873+01:00Picnik for collaborative screenshots<b>Update!</b> Picnik <a href="http://blog.picnik.com/2012/01/official-announcement-picnik-is-closing/">is closing on April 19, 2012</a>. This is sad news. I really liked working with the product. Please sign the <a href="http://signon.org/sign/dont-close-picnik">Don't Close Picnik petition</a>! A subset of Picnik features is available in the Google+ Creative Kit but, crucially, the Photo Bucket is not. This means that the custom circles and arrows we use to annotate images are gone.<br />
<br />
<hr />
<br />
At Magnolia, we recently started using <a href="http://www.picnik.com/">Picnik</a> to annotate screenshots. We wanted a casual but obvious way to draw the reader's attention to an image detail. In this post I explain why we chose Picnik and how it is working so far.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEit28ATdvTXTKgjyXxmqk_UDEx9ODjlqsdQbVyRuPObpR8upX7I-b1WxAsuvFV2-g9qkZxzJaJ6kzjKynpN0iR7A3fNuKVLQluqMRlWQ9hNeUoYZ-bpfKTZiKIGC6DCNtKRaOR8wQ/s1600/AdminCentral-search-box.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEit28ATdvTXTKgjyXxmqk_UDEx9ODjlqsdQbVyRuPObpR8upX7I-b1WxAsuvFV2-g9qkZxzJaJ6kzjKynpN0iR7A3fNuKVLQluqMRlWQ9hNeUoYZ-bpfKTZiKIGC6DCNtKRaOR8wQ/s1600/AdminCentral-search-box.png" /></a></div>
<br />
Picnik is a photo editor that runs in the browser. You may have seen it as the embedded photo editor in Picasa Web Albums. The requirements that drove us to a Web-based tool were:<br />
<ol>
<li><b>No OS lock-in</b>. We have technical writers working on Windows 7, Vista and Mac OSX. It is difficult to find a screenshot tool that works on all those platforms. <a href="http://skitch.com/">Skitch</a> is awesome on the Mac but a Windows version is <a href="http://techie-buzz.com/annoucements/skitch-now-free-for-all-users-coming-soon-to-a-all-platforms.html">still only hearsay</a>.</li>
<li><b>Consistent annotations.</b> Annotations are the circles and arrows we add to screenshots to draw the reader's attention to whatever it is we write about. While any screenshot tool can take a plain screenshot, adding consistent annotation shapes is difficult unless everybody uses the same tool. Documentation ends up looking amateurish and poor if the shapes are not consistent.</li>
<li><b>Casual, hand-drawn look</b>. We wanted a casual, edgy look. Straight lines and rectangles are difficult to see on a UI that already has lots of straight lines. They also look incredibly boring. If you annotated something on a piece of paper, you would grab a pen and circle it. <i>That's</i> the look we wanted.</li>
<li><b>Shared storage</b>. Web-based tools promise cloud storage. Why should everybody take the same screenshot when a perfectly good example exists in a shared library? Why draw your own arrows with a shaky mouse if there's a nice-looking arrow in the toolbox?</li>
</ol>
<div>
I must emphasize that Picnik really isn't a screenshoot tool. It's a photo editor whose features are clearly geared towards processing photos. It's great for assembling favorite shots into a Christmas card but for taking a screenshot you still need a local tool, which is fine for us.</div>
<div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<h2>
Picnik features we love and curse</h2>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<b>Uploading</b> an image is a snap. The image is opened in the editor immediately so no unnecessary browsing is needed. Besides upload, you can open an image from Flickr, Facebook and several other popular services. </div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi5w6fp1GJpykvM6YOEv5YMcNIUVdHvPDxbDz5e7TTqGwMbUykEbMb-04O5u0rEjKAN9RoyAw4fmZeW5mKa1tJ_d8JO4t9i19fScfSqjPdrxKo1HtPYrqPOMQG8zqhAu-NhVSaLUw/s1600/upload.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi5w6fp1GJpykvM6YOEv5YMcNIUVdHvPDxbDz5e7TTqGwMbUykEbMb-04O5u0rEjKAN9RoyAw4fmZeW5mKa1tJ_d8JO4t9i19fScfSqjPdrxKo1HtPYrqPOMQG8zqhAu-NhVSaLUw/s1600/upload.png" /></a></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<b>Resizing</b> to new dimensions works as expected. The quality of the reduced image is not as good as if you used Photoshop. The image is fuzzier, which can be a problem. Text in a screenshot must stay sharp and readable in smaller size too. To get around the issue, we either crop to the relevant area or keep the shot full-size. Modern browsers do a very good job at resizing in the viewport, certainly no worse than Picnik.</div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgPaDwLWhZF-MnCwGHZx9d7ejHUlZnHvSsbJ5EAcn7TWvE0x0ceXWy8yg98noILqg-GgyM2cqgADIc-kuQ0zvnwnjz-ku9bXW9aLxKmfA2H5S8Yo3u_V7Jnf8DtrkSnpF1m30X6BQ/s1600/resize.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgPaDwLWhZF-MnCwGHZx9d7ejHUlZnHvSsbJ5EAcn7TWvE0x0ceXWy8yg98noILqg-GgyM2cqgADIc-kuQ0zvnwnjz-ku9bXW9aLxKmfA2H5S8Yo3u_V7Jnf8DtrkSnpF1m30X6BQ/s1600/resize.png" /></a></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<b>Canvas</b> as a concept does not exist as in Picnik. When you need more room around the image, add a border. The border can be any color and width. Make it white and you effectively have a bigger canvas.</div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgHzp44XzWE_wu1vWe8D4ETS9aCPVfEaZHS2dI7t-c_wlIKme_SvlCpsS88DLASIrDuc4HOgZDe73BfcnYHTyeg03esfMas4sfNPmyhovPtgUBehkr7IpBktaDctt0Sbf04hcLxAQ/s1600/border.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgHzp44XzWE_wu1vWe8D4ETS9aCPVfEaZHS2dI7t-c_wlIKme_SvlCpsS88DLASIrDuc4HOgZDe73BfcnYHTyeg03esfMas4sfNPmyhovPtgUBehkr7IpBktaDctt0Sbf04hcLxAQ/s1600/border.png" /></a></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<b>Shapes</b>. I drew a collection of annotation shapes by hand in Skitch and saved them as PNG files. Then I uploaded them into a Picasa Web Album that is visible in the Photo Basket in Picnik. Now anybody in the team can drag-and-drop symbols onto an image. This solves the requirement that all writers use the same symbols to produce a consistent look and feel.</div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgNQY_E49M62Nag6gVEmK5mVV3LMPfEJmrxIv6VPhFICa6kTdb_bfwCFJjNk8AnSNN4IOP9sRrgl4GDH8jT05EM-y6sWRN7oSqPnYrrmb5C2_v_YO7AG8CDjGmnp93wnVcboWNGrw/s1600/photo-basket-3.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgNQY_E49M62Nag6gVEmK5mVV3LMPfEJmrxIv6VPhFICa6kTdb_bfwCFJjNk8AnSNN4IOP9sRrgl4GDH8jT05EM-y6sWRN7oSqPnYrrmb5C2_v_YO7AG8CDjGmnp93wnVcboWNGrw/s1600/photo-basket-3.png" /></a></div>
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<b>Text</b>. Picnik has a huge variety of fonts to choose from. They are very hip and cool, which means they are perfect for a scary Halloween photo but not so great when you need readable text. We chose a font called <i>Just Me Again Down Here</i> by Kimberly Geswein. It's a good compromise between hand-drawn look and readability. We matched the font size to the shape stroke width.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhL9hivNp9QN8rfXaAEaRMv1ss_a2xDZOy5FEAx5hnhydqo4SG-G31mJgupxch7ai3yFWhQWFS4qYF5tNVgGIwRMjNwGegxHHmeGOvHwrR3OT66MYjANO8t20yi4lQV4qY6Hrz9bw/s1600/text-1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhL9hivNp9QN8rfXaAEaRMv1ss_a2xDZOy5FEAx5hnhydqo4SG-G31mJgupxch7ai3yFWhQWFS4qYF5tNVgGIwRMjNwGegxHHmeGOvHwrR3OT66MYjANO8t20yi4lQV4qY6Hrz9bw/s1600/text-1.png" /></a></div>
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<b>Sharing and layers</b> are my biggest grievance with Picnik. I <a href="https://groups.google.com/a/googleproductforums.com/forum/#!topic/picnik/0ya28aWCebc/discussion">asked on the help forum</a> why sharing is so weird. Bottom line: edits are stored on the image owner's Picnik account and are not accessible to other users. This means that while you can save an image to a Picasa Web Album, other team members won't be able to edit it. The image is flat to them. This is a shame because picking up from where another use left would be fantastic. As for the shapes, we put them in a common Picasa account which all technical writers register in their Picnik. So at least the shapes are available to everyone.</div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br />
So there you have it. Picnik works for us now. Drop a comment if you solved similar requirements in your team with something else.</div>
</div>Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comBasle, Switzerland47.557421 7.592572747.5145585 7.5136087 47.600283499999996 7.6715367tag:blogger.com,1999:blog-11804845.post-46829552765190593902012-01-16T15:32:00.000+01:002012-01-16T15:32:42.566+01:00Twitter-style character counter for textareasIn this post I show how to improve textarea usability with a Twitter-style character counter.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiOqH62Yll001qp3P04sWyhRcmV6Z8LMdG4SRFNcM2PSlxhlqlmmWNqWEXeRrQG3Mlz3YKcrk6iE88878oIOzTnATi7TM_sRyNbe8-gTxLpKOuC27PdpKEnu9PPb9pIBhCeY2zbLA/s1600/counter-complete.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiOqH62Yll001qp3P04sWyhRcmV6Z8LMdG4SRFNcM2PSlxhlqlmmWNqWEXeRrQG3Mlz3YKcrk6iE88878oIOzTnATi7TM_sRyNbe8-gTxLpKOuC27PdpKEnu9PPb9pIBhCeY2zbLA/s1600/counter-complete.png" /></a></div>
<br />
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
Validating form input length is a common strategy for reducing errors. So common in fact that the <a href="http://reference.sitepoint.com/html/input/maxlength">HTML specification</a> provides a <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">maxlength</span> attribute for <span class="Apple-style-span" style="font-family: inherit;">input</span> fields. Starting with <a href="http://www.w3schools.com/html5/att_textarea_maxlength.asp">HTML5</a>, multiline <span class="Apple-style-span" style="font-family: inherit;">textarea</span> fields support the attribute too!</div>
<br />
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><textarea id="message" rows=4 maxlength="100" /></span></div>
<br />
Since it is always better to <b>prevent</b> an error than catch one the user already made, here are two ways to improve textarea usability in <a href="http://www.magnolia-cms.com/">Magnolia CMS</a>, making sure the user knows how many characters are allowed.<br />
<br />
<h2>
Display the character limit</h2>
The obvious improvement is to display the character limit. In Magnolia CMS, you set the limit on the form field. The system saves it to a <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">maxLength</span> property in the repository.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg__yIigi4thmP0vacIYtSmVZEaC2zeRQQu9PonCbe-_OzOudlkxyykQt4MSt1z1TpMNy07xVvikm8n1zE30n1zeqA3Hgl9CQ5e5BzIgxwzt64r7ry00HoLO8jGcSoeGkKpRObHZA/s1600/input-dialog.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="305" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg__yIigi4thmP0vacIYtSmVZEaC2zeRQQu9PonCbe-_OzOudlkxyykQt4MSt1z1TpMNy07xVvikm8n1zE30n1zeqA3Hgl9CQ5e5BzIgxwzt64r7ry00HoLO8jGcSoeGkKpRObHZA/s400/input-dialog.png" width="400" /></a></div>
<br />
Render the length on the page:<br />
<ol>
<li>Copy the <a href="http://svn.magnolia-cms.com/svn/community/modules/magnolia-module-form/tags/magnolia-module-form-1.3.1/src/main/resources/form/paragraphs/formEdit.ftl"><span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">formEdit.ftl</span></a> script which renders input controls.</li>
<li>Create folder <b>Templating Kit > Templates</b> > <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/form/paragraphs</span><span class="Apple-style-span" style="font-family: inherit;">.</span></li>
<li>Create a new template script <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">formEdit</span> and paste the copied script into it.</li>
<li>Render the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">maxLength</span> property in the textarea element on line 21.</li>
<li>Render it visibly to the user:<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> ${content.maxLength!'50'}</span></li>
<li>Enable the script and refresh the <a href="http://demo.magnolia-cms.com/demo-project/service/contact.html">Contact form</a> page.</li>
</ol>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEil6xT9Of84wp8UY4ADvgGnEsK0FLjQaC9j3UdADLtkHSzY5naZ53EdQZ0QvoHwMnGpUDcCWSBXnhFeRt_Vpjcnc1h7Bf3fVmOLleGpV4ixwd85BZ8FPdiZDZoEz6PDT4LXnMKesA/s1600/maxlength-rendered.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEil6xT9Of84wp8UY4ADvgGnEsK0FLjQaC9j3UdADLtkHSzY5naZ53EdQZ0QvoHwMnGpUDcCWSBXnhFeRt_Vpjcnc1h7Bf3fVmOLleGpV4ixwd85BZ8FPdiZDZoEz6PDT4LXnMKesA/s1600/maxlength-rendered.png" /></a></div>
<br />
<br />
<h2>
Twitter-style character counter</h2>
How does the user know they are approaching the limit? <a href="http://cssglobe.com/post/7161/jquery-plugin-simplest-twitterlike-dynamic-character-count-for-textareas">jQuery Charcount plugin</a> adds a Twitter-style character counter. As the user types text, the plugin counts unused characters. When a limit is exceeded, the counter turns red.<br />
<div class="separator" style="clear: both; margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px; text-align: center;">
</div>
<br />
Start by <a href="http://cssglobe.com/lab/charcount/charcount.zip">downloading</a> the jQuery Charcount plugin kit:<br />
<ul>
<li><b>jQuery.js</b> is the core jQuery script. Magnolia CMS already has it.</li>
<li><b>charCount.js</b> counts the characters and draws the counter. </li>
<li><b>CSS styles</b> sets the alarm color.</li>
<li><b>01.html</b> is an example page.</li>
</ul>
<br />
<ul>
</ul>
<b>Step 1: Add the Charcount script as a resource</b><br />
<ol>
<li>Go to <b>Templating Kit > Resources ></b> <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/templating-kit/js/all</span>.</li>
<li>Under <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">all</span>, add a new JavaScript resource <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">charCount</span>.</li>
<li>In the <b>Advanced</b> tab, set <b>Extension</b> to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">js</span>.</li>
<li>Paste the downloaded charCount.js script into the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">charCount</span> item.</li>
<li>Change line 35 to read the textarea ID from the element:<br /><span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">var available = $(obj).attr('maxlength') - count;</span></li>
</ol>
<br />
<b>Step 2: Warn when 10 characters are left</b><br />
<ol>
<li>Copy the document.ready function from the example <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">01.html</span> file.</li>
<li>Paste it in the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">charCount</span> script before the closing <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">})(jQuery);</span> line.</li>
<li>Change <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">#message2</span> to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">textarea</span>. We are getting the IDs dynamically.</li>
<li>Set the warning to 10.</li>
</ol>
The end of your script should now look like this:<br />
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
</div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> $(document).ready(function(){ </span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> //custom usage</span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> $("textarea").charCount({</span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> warning: 10</span><span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">,</span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> counterText: 'Characters left: ' </span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> });</span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> }); </span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> </span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">})(jQuery);</span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<br />
<b>Step 3: Make the counter red on warning</b><br />
<ol>
<li>In <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/templating-kit/themes/pop/css</span>, create a new sheet <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">charCount</span>.</li>
<li>On the <b>Advanced</b> tab, set <b>Extension</b> to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">css</span><span class="Apple-style-span" style="font-family: inherit;">.</span></li>
<li>Set <b>Model Class</b> to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">info.magnolia.module.templatingkit.resources.STKResourceModel</span>.</li>
<li>Paste the following style in the <b>Content</b> box:</li>
</ol>
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">.form-wrapper div span.warning {</span><br />
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> color:red;</span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> font-weight:bold; !important</span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"> }</span></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
<br /></div>
<div>
<b>Step 4: Include the new style in the theme</b></div>
<div>
<ol>
<li>In <b>Templating Kit > Themes ></b> <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/pop/cssFiles</span>, copy <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">styles</span> to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">charCount</span>.</li>
<li>Set <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">link</span> property to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/resources/templating-kit/themes/pop/css/charCount.css</span>.</li>
</ol>
</div>
<div>
<br />
<b>Step 5: Try it!</b></div>
<div>
<br /></div>
<div>
Reload the <a href="http://demo.magnolia-cms.com/demo-project/service/contact.html">Contact</a> page. Now the page has a counter that starts counting back from the limit.</div>
<div>
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiyizSt2G3_nYN83N87JiwOX9azcV9tfGkluux7l9CWjMiiTWG6d7AewEmCixKx_8XCaplVIQdS5YNuEfU78aAs9wN9dszSAfcXIBEB3k5CBnU_qPXB43v70AgeVwRMU2LirSrPtg/s1600/counter.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiyizSt2G3_nYN83N87JiwOX9azcV9tfGkluux7l9CWjMiiTWG6d7AewEmCixKx_8XCaplVIQdS5YNuEfU78aAs9wN9dszSAfcXIBEB3k5CBnU_qPXB43v70AgeVwRMU2LirSrPtg/s1600/counter.png" /></a></div>
<br /></div>
<div>
Type some text into the box. When 10 characters are left, the counter turns red.</div>
<div>
<br /></div>
<div class="separator" style="clear: both; margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiOqH62Yll001qp3P04sWyhRcmV6Z8LMdG4SRFNcM2PSlxhlqlmmWNqWEXeRrQG3Mlz3YKcrk6iE88878oIOzTnATi7TM_sRyNbe8-gTxLpKOuC27PdpKEnu9PPb9pIBhCeY2zbLA/s1600/counter-complete.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiOqH62Yll001qp3P04sWyhRcmV6Z8LMdG4SRFNcM2PSlxhlqlmmWNqWEXeRrQG3Mlz3YKcrk6iE88878oIOzTnATi7TM_sRyNbe8-gTxLpKOuC27PdpKEnu9PPb9pIBhCeY2zbLA/s1600/counter-complete.png" style="cursor: move;" /></a></div>
<div>
<br /></div>
<br />
<br />
<br />Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-70714806440128470572011-04-05T21:30:00.001+02:002011-04-05T21:34:45.007+02:00Coupons with Imaging moduleIn this post I show you how to create coupons using the <a href="http://documentation.magnolia-cms.com/modules/imaging.html">Magnolia Imaging module</a>. I start with a background image and overlay the special promotion text. Campaign specific details are managed in the Data module while static text is configured in the Imaging module.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjW0vnu3dPO49omiEUyCfRgnwSJMj813fEpoc5g1wOQysmSFBh14vCxhTSAFCMDGXuMLyhDHsy1Ux7Jv-liiXWT0ENeLRVJhyphenhyphennV0bS3vXtoqU8D4ZHSRIu829adVSIkhQg-L4QaWw/s1600/finished-coupon.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjW0vnu3dPO49omiEUyCfRgnwSJMj813fEpoc5g1wOQysmSFBh14vCxhTSAFCMDGXuMLyhDHsy1Ux7Jv-liiXWT0ENeLRVJhyphenhyphennV0bS3vXtoqU8D4ZHSRIu829adVSIkhQg-L4QaWw/s1600/finished-coupon.png" /></a></div><br />
Let's start by registering an <a href="http://documentation.magnolia-cms.com/modules/imaging.html#Imagegenerator">image generator</a>. For this purpose I use the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">ImageOperationChain</span> generator since it allows me to execute multiple image operations one after the other. My image operation chain will be called <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">coupon</span> and it outputs PNG files.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEheQKGuS8_MIbx2ONMzLweSVEdc28HomrVEx-3FENN4_ZY8o1G2cWVyspyNyghfPEANWhQsEAdO8ZS1youbf6Qfzkk2G-mz_0a4UdpYWuHYocB6GrgTR6i1mC-n7-H0_yfSgLHHTA/s1600/coupon-1-generator.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEheQKGuS8_MIbx2ONMzLweSVEdc28HomrVEx-3FENN4_ZY8o1G2cWVyspyNyghfPEANWhQsEAdO8ZS1youbf6Qfzkk2G-mz_0a4UdpYWuHYocB6GrgTR6i1mC-n7-H0_yfSgLHHTA/s1600/coupon-1-generator.png" /></a></div><br />
The first image operation in the chain, <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">loadImage</span>, loads a background graphic. I am using the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><a href="http://documentation.magnolia-cms.com/modules/imaging.html#Loadingimagefromclasspath">ClassPathImageLoader</a></span> class which can retrieve an image from the classpath. (You can also load from <a href="http://documentation.magnolia-cms.com/modules/imaging.html#LoadinganimagefromDMSworkspace">DMS</a>, <a href="http://documentation.magnolia-cms.com/modules/imaging.html#Loadinganimagefromwebsiteworkspace">website </a>or <a href="http://documentation.magnolia-cms.com/modules/imaging.html#LoadinganimagefromURL">external URL</a>.) By default, a Magnolia webapp's classpath includes any JARs in <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/WEB-INF/lib</span> and any classes and resources in <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/WEB-INF/classes</span>. I copied my background graphic into the latter and named it <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">coupon.png</span>. Here's the operation configuration.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi4zEwjtMj_DWgNnlwWsjlqjUNM6D8Y2l-a9fNXVE7GoNhy4saiYLF2AZP5QCHQ3qG-jZsrDyMtZe-2Zv3XiAcUZz2aAVSGd-6WADDHFc1qbXTiwro94LyvNEfZaaC-qe-1fB15KA/s1600/operation-loadImage.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi4zEwjtMj_DWgNnlwWsjlqjUNM6D8Y2l-a9fNXVE7GoNhy4saiYLF2AZP5QCHQ3qG-jZsrDyMtZe-2Zv3XiAcUZz2aAVSGd-6WADDHFc1qbXTiwro94LyvNEfZaaC-qe-1fB15KA/s1600/operation-loadImage.png" /></a></div><br />
When I request the image I need to pass an existing page in the URL. This is how the parameter provider factory works. I can see the image at <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://<host>/<instance>/.imaging/coupon/website.png</span>. This is a Christmas coupon with some red lights and space for text below.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiFucEcsdS8w-LV8I1-M7Ap8N0zN9qfrOTR37wnPcmq1QHlGmujbcr2nObSBQgwxhJC1zRbftI7kpOlfhN6_jgpaSvAxWm19jQilfS8Zl_ndrhBRSfVlHezrWW1FhPARH5gvC5SjQ/s1600/coupon.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiFucEcsdS8w-LV8I1-M7Ap8N0zN9qfrOTR37wnPcmq1QHlGmujbcr2nObSBQgwxhJC1zRbftI7kpOlfhN6_jgpaSvAxWm19jQilfS8Zl_ndrhBRSfVlHezrWW1FhPARH5gvC5SjQ/s1600/coupon.jpg" /></a></div><br />
<h2>Campaign management in Data module</h2>For managing the campaigns I created a custom data type in the <a href="http://documentation.magnolia-cms.com/modules/data.html">Data module</a>. The campaign entry dialog allows editors to enter a discount percentage, product and validity period. I entered a Christmas campaign that offers 25% discount on a single in-store product.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiAdiyLGqs0VLst6a_MY6uq2mQEV_rhOg_ivUOkITXauUgfhYOcXwzu30JqHt5BYMQHo7REmIsj2JnfV93g8mKP0oeyTS3SJ9Ox4WjbwnGbfCGZT0QaPP1v4J9u6HyDKfUaWSRwuw/s1600/dialog-campaign.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiAdiyLGqs0VLst6a_MY6uq2mQEV_rhOg_ivUOkITXauUgfhYOcXwzu30JqHt5BYMQHo7REmIsj2JnfV93g8mKP0oeyTS3SJ9Ox4WjbwnGbfCGZT0QaPP1v4J9u6HyDKfUaWSRwuw/s1600/dialog-campaign.png" /></a></div><br />
The Data module stores the information in the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">data</span> workspace. The discount percentage, for example, is stored in <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/campaign/Christmas/percentage</span>.<br />
<br />
<h2>Text overlay</h2>The <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">TextFromNode</span> class can retrieve content from any workspace and overlay it on top of the image. In the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">percentage</span> operation I fetch the discount percentage from the Data module. I need to pass the workspace name and path in the request URL, <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://<host>/<instance>/.imaging/coupon/data/campaign/Christmas.png</span>.<br />
<br />
The <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">percentSymbol</span> operation overlays the % symbol using the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">FixedText</span> class. The symbol is given in the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">text</span> property. This works fine for static strings that don't change often. See <a href="http://documentation.magnolia-cms.com/modules/imaging.html#Textoverlay">Text overlay</a> to learn about the nodes and valid values.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhWo5lDKY6Vo8P8jVhyo89vG94EIKAZ7LE_RCWCmZOMw3DFQOew9maHIRkjTJoYXK360f-8A1srQzVR4n6P5QxvwOfVaCSllYajfKGyH1gxV5HrYC6gyZpmYCjN7g-A6CRrn1R7Yg/s1600/operation-percentage.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhWo5lDKY6Vo8P8jVhyo89vG94EIKAZ7LE_RCWCmZOMw3DFQOew9maHIRkjTJoYXK360f-8A1srQzVR4n6P5QxvwOfVaCSllYajfKGyH1gxV5HrYC6gyZpmYCjN7g-A6CRrn1R7Yg/s1600/operation-percentage.png" /></a></div><br />
I added the text "off" also as fixed text and requested the image. Here's what is looks like at this point.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh5XbhJ8KRlDGqTw_YDvJ6p2dpGOZfWjXghuv4CrySG9xlgKHACIzUafhurvtJRvcsIhwhAbkVnMoRE2alCBQIq3tNsqtrG9rJJgdayNK8K0e4dXJPMwVKmWuES5fvnvWeQXPpOCA/s1600/coupon-3-percentage.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh5XbhJ8KRlDGqTw_YDvJ6p2dpGOZfWjXghuv4CrySG9xlgKHACIzUafhurvtJRvcsIhwhAbkVnMoRE2alCBQIq3tNsqtrG9rJJgdayNK8K0e4dXJPMwVKmWuES5fvnvWeQXPpOCA/s1600/coupon-3-percentage.png" /></a></div><br />
Adding the product description, validity period and legal disclaimers works in a similar fashion. Changing typeface, font size and positioning I was able to make the design more interesting. Here's the final result.<br />
<br />
<div style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjW0vnu3dPO49omiEUyCfRgnwSJMj813fEpoc5g1wOQysmSFBh14vCxhTSAFCMDGXuMLyhDHsy1Ux7Jv-liiXWT0ENeLRVJhyphenhyphennV0bS3vXtoqU8D4ZHSRIu829adVSIkhQg-L4QaWw/s1600/finished-coupon.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjW0vnu3dPO49omiEUyCfRgnwSJMj813fEpoc5g1wOQysmSFBh14vCxhTSAFCMDGXuMLyhDHsy1Ux7Jv-liiXWT0ENeLRVJhyphenhyphennV0bS3vXtoqU8D4ZHSRIu829adVSIkhQg-L4QaWw/s1600/finished-coupon.png" /></a></div><br />
When the next campaign kicks in, all you need to do is ask your graphic designer for a new background image and create a campaign data item in the Data module.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgzGolasBbqxcYjx1WuS6lWOsOU8-uNBj5Pz8P2Q-y3SZEZVJI5eWUXv8stOQmj3r9RJV0Rjj3j8aO0VS_1gkZQYao8evdR3JycIf2-CqKUAAZGopt51j51nP03q1NPc9eu8juaAQ/s1600/Winter.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgzGolasBbqxcYjx1WuS6lWOsOU8-uNBj5Pz8P2Q-y3SZEZVJI5eWUXv8stOQmj3r9RJV0Rjj3j8aO0VS_1gkZQYao8evdR3JycIf2-CqKUAAZGopt51j51nP03q1NPc9eu8juaAQ/s1600/Winter.png" /></a></div><div class="separator" style="clear: both; text-align: left;"><br />
</div><div class="separator" style="clear: both; text-align: left;">Background image credit: <a href="http://www.flickr.com/photos/macalicious/2094567877/">George Deputee</a> and <a href="http://www.flickr.com/photos/juliancolton/5360064817/">Juliancolton2 </a>on Flickr.</div>Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-72160730808025321202011-03-31T10:14:00.002+02:002011-03-31T10:39:56.167+02:00Controlling AdminCentral accessAdminCentral is a Magnolia CMS user interface where administrators and editors work. In this post I show how to configure menu permissions for a custom user role.<br />
<br />
AdminCentral provides menus for common tasks. When you click a menu, workable items are displayed on the right.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg3bgcVJ87U-j2PWt0B2uesEOVFcL1_DqyG7TScLS9TuUsauA-4PhbC6XJUHfDW2pRVmnJn_cLH6L4hKDO4bbxfsMZSRQ66ViVxEN7Vwakgon93Jmgvxnrtio1cwE-4ChPHyxhscQ/s1600/AC-menus-440.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg3bgcVJ87U-j2PWt0B2uesEOVFcL1_DqyG7TScLS9TuUsauA-4PhbC6XJUHfDW2pRVmnJn_cLH6L4hKDO4bbxfsMZSRQ66ViVxEN7Vwakgon93Jmgvxnrtio1cwE-4ChPHyxhscQ/s1600/AC-menus-440.png" /></a></div><div class="separator" style="clear: both; text-align: left;"><br />
</div><div class="separator" style="clear: both; text-align: left;"></div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">You can hide menus and move them around to promote often-used items or deny permission to items that users should not be able to access. Magnolia CMS ships with typical roles such as superuser, editor and publisher. While a superuser can see everything, editors only see items that are relevant to their job.</div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;"><br />
</div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;"><h2>Permissions for custom roles</h2></div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">Suppose your organization has a very specialized editor role, Category Editor, who is responsible for maintaining a taxonomy of categories. Categories are tags that help site visitors find related, interesting content.</div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;"><br />
</div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">Categories are managed in a custom data type under the <b>Data</b> menu. The <a href="http://demoauthor.magnolia-cms.com/.magnolia/pages/adminCentral.html">demo-project website</a> has an example taxonomy consisting of categories such as Culture, Family and Finance. The Category Editor needs access to the <b>Data > Category</b> menu only.</div><div><div><div class="separator" style="clear: both; text-align: auto;"><br />
</div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjgrzUNrR-fnHC5pN7WWMk2iVCiJLXXcyF6-DIWu4njlaS5u8mji2otBKNUVdysxRtOOV8idT1rUZ581ntZkwtH0byzmzZkjfgz1aAQH_70G431DUWsT9K44sBVWx2_6aUu4DmAOg/s1600/Category-menu-440.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjgrzUNrR-fnHC5pN7WWMk2iVCiJLXXcyF6-DIWu4njlaS5u8mji2otBKNUVdysxRtOOV8idT1rUZ581ntZkwtH0byzmzZkjfgz1aAQH_70G431DUWsT9K44sBVWx2_6aUu4DmAOg/s1600/Category-menu-440.png" /></a></div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;"><br />
</div></div><div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">You can approach setting permissions for this role in two ways:</div></div></div><div><ul><li><b>Top down</b>: Start with a more powerful editor role and remove permissions until only the ability to edit categories is left.</li>
<li><b>Bottom up</b>: Start with zero permissions and keep adding until the Category Editor can do their job. </li>
</ul></div><div><b><span class="Apple-style-span" style="font-weight: normal;"><b></b></span></b><br />
<div><div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">Magnolia CMS ships with a <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">demo-project-base</span> role that provides many basic permissions common to all users. It's a good starting point so let's choose the first option: top down.<br />
<br />
</div></div><h2>Create category-editor role</h2></div><div>Create new role <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">category-editor</span> and new user <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">jsmith</span>. Assign roles <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">demo-project-base</span> and <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">category-editor</span> to user <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">jsmith</span>.</div><div><br />
</div><div>Now open another browser instance and sign in as <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">jsmith</span>. You should see three menus: <b>Website</b>, <b>Documents </b>and <b>Data</b>.</div><div><br />
</div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgM4R2ptKYf_2Y2tJzfIrrs2XLxoqdMG-0ffQdXNRXy_yRaBTZY9CHZFypexMM9C_cp7EkApRWSca7UuYliep1oapdu_B3aBqJKg9mwWo4uiDuranhL6INHUV3jIz3pzr8a8mIPMA/s1600/Category-too-many-440.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgM4R2ptKYf_2Y2tJzfIrrs2XLxoqdMG-0ffQdXNRXy_yRaBTZY9CHZFypexMM9C_cp7EkApRWSca7UuYliep1oapdu_B3aBqJKg9mwWo4uiDuranhL6INHUV3jIz3pzr8a8mIPMA/s1600/Category-too-many-440.png" /></a></div><div><br />
The Category Editor doesn't need the first two menus or the <b>Contact</b> submenu so let's remove them.<br />
<br />
</div><div><h2>Hide menus</h2>Edit the <a href="http://documentation.magnolia-cms.com/administration/security/accesscontrollists.html">access control lists (ACL)</a> attached to the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">category-editor</span> role. Deny access to the following nodes in the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">config</span> workspace:<br />
<ul><li><span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/modules/adminInterface/config/menu/website$</span></li>
<li><span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/modules/adminInterface/config/menu/dms$</span></li>
<li><span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/modules/adminInterface/config/menu/data/Contact$</span></li>
</ul>The <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">demo-project-base</span> role already grants access to the same nodes so you need to make the deny rules "win". If a user has multiple ACLs through role and group assignment that specifically list the requested resource, the ACL with the <b>longest pattern</b> determines the permission. The order of the rules is not considered. This is a critical point. Use the <a href="http://documentation.magnolia-cms.com/administration/security/accesscontrollists.html#Markingtheendofapath">dollar sign ($) to mark the end of the path</a>, which makes the deny rule longer.<br />
<br />
Here's what the Category Editor sees after the ACLs have been applied. Menus are now perfect but the editor cannot edit the data items. Categories have a crossed-out pen icon to indicate this.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgaeGYzA9XtLJwJv8YsY-F8f45DeDuTrqdce-xj433PAGxbfc28TaTthOaVjhv0Z3p_BnCi7WhzCX3P06rrltDUp2CT9-oNzRLAkbHNQCq_C7YRRRKo18RDxocPPPRnqKKTcC54_g/s1600/Category-uneditable-440.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgaeGYzA9XtLJwJv8YsY-F8f45DeDuTrqdce-xj433PAGxbfc28TaTthOaVjhv0Z3p_BnCi7WhzCX3P06rrltDUp2CT9-oNzRLAkbHNQCq_C7YRRRKo18RDxocPPPRnqKKTcC54_g/s1600/Category-uneditable-440.png" /></a></div><div class="separator" style="clear: both; text-align: left;"><br />
</div></div><div><h2>Grant access to data</h2></div><div>Add an ACL in the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">data</span> workspace that grants Read/Write permission to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/categorization</span> node. Now the items are editable.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhx9NPCq5GU_GzjIAyQBdiWYh5B9jOk_F7tBqpOf6Wkn1CwWvTdNdyeVidpYvfZRte8HNeJmARb09x3pkGw9twseWtEHFolHzkXTOPMyUflSPn_dYukyy84k2Dd3S0FOsCdSfjfdg/s1600/Category-editable.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhx9NPCq5GU_GzjIAyQBdiWYh5B9jOk_F7tBqpOf6Wkn1CwWvTdNdyeVidpYvfZRte8HNeJmARb09x3pkGw9twseWtEHFolHzkXTOPMyUflSPn_dYukyy84k2Dd3S0FOsCdSfjfdg/s1600/Category-editable.png" /></a></div><br />
<h2>Lock the backdoor!</h2><div class="separator" style="clear: both; text-align: center;"></div>Menus are not the only way to access content in AdminCentral. They just provide convenient access to often-used items. If you are restricting access per security, not just for convenience, make sure you lock down the content too:<br />
<ul><li><b>Workspaces</b> store the actual content. Make sure that any role you choose as a basis does not grant access to a workspace that users should not be able to access. In our example the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">demo-project-base</span> role does not grant any unnecessary workspace permissions. You can control workspace access with an ACL. Select the workspace from the <a href="http://documentation.magnolia-cms.com/administration/security/accesscontrollists.html#ACLstructure">controlled space dropdown</a>.</li>
<li><b>Trees</b> are customized views into specific data. Users can view trees with a direct URL if they know the name of the tree, for example <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://[host]/[instance]/.magnolia<span class="Apple-style-span" style="color: #3d85c6;">/trees/website</span></span>. Each module can register its own trees. Look in <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/modules/adminInterface/trees</span> to get an idea. As long as you restrict permissions to workspaces correctly, trees will honor the permissions. </li>
<li><b>Pages</b> provide specialized tools such as exporting, importing and querying. Users can access pages with a direct URL too: <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://[host]/[instance]/.magnolia<span class="Apple-style-span" style="color: #3d85c6;">/pages/jcrUtils</span></span>. Like in trees, content cannot be accessed through pages as long as the workspace is locked down.</li>
</ul></div>Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-62406050820205269322011-03-18T09:11:00.002+01:002011-03-31T10:41:40.358+02:00Category cloud with imagesThis post was inspired by <a href="http://old.nabble.com/Category-cloud-with-image-td31154527.html">Amit Patel's question</a> on how to add images in a Magnolia category cloud. Thanks Amit!<br />
<br />
<b><span class="Apple-style-span" style="font-size: large;">What is a tag cloud?</span></b><br />
Tags are words or short phrases that describe content such as articles or photos. A tag cloud is a weighted lists of those tags displayed as a group where popular tags are given more visual weight than less popular tags. The visual weight is accomplished by making popular tags larger or bolder.<br />
<br />
Here's a tag cloud from <a href="http://www.flickr.com/photos/tags/">Flickr</a> with tags that people use on their photos.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjY4JLXzpDq8glkkyHFnHUcjKXQXM8Xz6Xg9R51hLib7jzFGfZqCtxxyHzhoGfpPUn2txDTknWL3fvgVYEM0rpHtPi7fjYoFwsNP7CtM2sQgtEcK8VX9ug_sWfcLdZcEFI7lUYeeQ/s1600/flickr-1-1-2.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjY4JLXzpDq8glkkyHFnHUcjKXQXM8Xz6Xg9R51hLib7jzFGfZqCtxxyHzhoGfpPUn2txDTknWL3fvgVYEM0rpHtPi7fjYoFwsNP7CtM2sQgtEcK8VX9ug_sWfcLdZcEFI7lUYeeQ/s1600/flickr-1-1-2.png" /></a></div><div class="separator" style="clear: both; text-align: center;"></div><br />
Another cloud with trending Twitter topics.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjqUQuwNJmrsSlr20I6dY2CRJOZqgvQwRnRUuV72FEhvH_WMo0k3zDlwDumsdn1VJ8c8NnrxgovZ_mc8MzE1uktIZ4hui7wYzh0hGm-zkbkZOy3yuHqzLnxf6Sh7mlksui1WvJkjg/s1600/twitter+trend+cloud-1-1-1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjqUQuwNJmrsSlr20I6dY2CRJOZqgvQwRnRUuV72FEhvH_WMo0k3zDlwDumsdn1VJ8c8NnrxgovZ_mc8MzE1uktIZ4hui7wYzh0hGm-zkbkZOy3yuHqzLnxf6Sh7mlksui1WvJkjg/s1600/twitter+trend+cloud-1-1-1.png" /></a></div><div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"></div><br />
<b><span class="Apple-style-span" style="font-size: large;">Magnolia category cloud</span></b><br />
Magnolia's category cloud paragraph has the same principle. Articles on a website are tagged with categories to make it easier to find related content. Categories can be displayed in a cloud just like tags. The Magnolia category cloud is an editorial paragraph rather than compiled automatically from popularity statistics. This means that editors can set the weights to promote categories that are hot to give a boost to active campaigns or new content, for example.<br />
<br />
<div class="separator" style="clear: both; text-align: center;"></div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjE8arGahbXlUQOmVR1JNdkRKAIeHKXalwi3gEpiAsYXq-CdwsFXRqcb_c8Cq81L3lF02PUSZNA1sF_uMDE50bu-DqnhGvQGUYk6p7F2NNSeCQ5VNhqKW0459fQ1vscLX3H8gIAsw/s1600/mgnl+cloud-1-1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjE8arGahbXlUQOmVR1JNdkRKAIeHKXalwi3gEpiAsYXq-CdwsFXRqcb_c8Cq81L3lF02PUSZNA1sF_uMDE50bu-DqnhGvQGUYk6p7F2NNSeCQ5VNhqKW0459fQ1vscLX3H8gIAsw/s1600/mgnl+cloud-1-1.png" /></a></div><div class="separator" style="clear: both; text-align: center;"></div><br />
<b><span class="Apple-style-span" style="font-size: large;">Add an image control to Category dialog</span></b><br />
The quickest way to add images to each category is to copy the photo upload mechanism from the Contacts data type. Both Contacts and Categories are managed in the Data module so repurposing elements is a snap.<br />
<br />
Add an image control in Category dialog:<br />
<ol><li>Go to <b>Data > Config (Dialogs)</b>.</li>
<li>Copy <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/modules/data/dialogs/contact/personalTab/photo</span> to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/modules/data/dialogs/category/mainTab</span>.</li>
<li>Rename the copied node to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">icon</span>.</li>
<li>Change the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">label</span> to "Icon".</li>
</ol>Now you can add images. Get some nifty icons from the Web and add them to your categories.<br />
<div><br />
</div><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhmM1YHoDCdojeLrHLwtawXgtKWb-YEg_EJB3Dv7Zri6ZXBEfNpz6EK25J8csljs2r2d57cO6D-hXSZaL-_tboIKQkHeB-xioecbDbJ75kLphFLoIww-J-Zzonh6nIGQvlzDRfmqg/s1600/editing-finance.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="254" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhmM1YHoDCdojeLrHLwtawXgtKWb-YEg_EJB3Dv7Zri6ZXBEfNpz6EK25J8csljs2r2d57cO6D-hXSZaL-_tboIKQkHeB-xioecbDbJ75kLphFLoIww-J-Zzonh6nIGQvlzDRfmqg/s320/editing-finance.png" width="320" /></a></div><div><ol></ol><div><b><span class="Apple-style-span" style="font-size: large;">Render images next to category labels</span></b><br />
<div class="separator" style="clear: both; text-align: center;"></div><ol><li>Edit the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">categoryCloud.ftl</span> paragraph script. It's in the Categorization module JAR. You can also test this out by creating a script in <b>Templating Kit > Templates</b> and referencing it from the paragraph definition instead.</li>
<li>Assign images to categories.</li>
</ol><pre class="brush:xml;toolbar:false;first-line:12;highlight:19">[#-- Assigns: Macro for Item iteration --]
[#macro assignItemValues item]
[#-- Assigns: Get Content from List Item--]
[#assign itemName = item.@name]
[#assign itemDisplayName = item.displayName!itemName]
[#assign itemLevel = item.level]
[#assign itemLink = model.getCategoryLink(itemName)!]
[#assign itemIcon = item.icon!]
[/#macro]</pre><ol start="3"><li>Render the icons.</li>
</ol><pre class="brush:xml;toolbar:false;first-line:35;highlight:[36,37,38]"><li class="${itemLevel}">
[#if item.icon?exists]
<img src="${stk.createImageLink(itemIcon)}" />
[/#if]
<a href="${itemLink}" >${itemDisplayName}</a>
</li></pre><br />
To finish off, add a category cloud paragraph on the page and admire your handywork!<br />
<br />
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj3hkvuIciP7THLNXTPH9aceCOMb5dCHRQFNna5dKkRmP7XBTnmQhCmQT_dnC6w6y0utVLE6q-ecCw0pZTLGLiyDkjkksvUQbJRVeewBBaQu4vszSgBfzt7MaF4iuycr6zj01io3g/s1600/cloud+with+images.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj3hkvuIciP7THLNXTPH9aceCOMb5dCHRQFNna5dKkRmP7XBTnmQhCmQT_dnC6w6y0utVLE6q-ecCw0pZTLGLiyDkjkksvUQbJRVeewBBaQu4vszSgBfzt7MaF4iuycr6zj01io3g/s1600/cloud+with+images.png" /></a></div><br />
</div></div>Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-84876927153837799472011-02-02T12:18:00.000+01:002011-02-02T12:18:24.951+01:00Link popularityThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at increasing your site's link popularity.<br />
<br />
Search engines place strong emphasis on your site’s link popularity. Links from external sites, especially highly ranked ones, increase your site's rank. The more links targeting your site from external sources the better.<br />
<br />
There are countless ways to build links and a comprehensive discussion on this is beyond the scope of this paper. Some ways that Magnolia can help to build incoming links are:<br />
<ul><li>By developing a blog on an external domain to promote your main site. The Templating Kit allows you to <a href="http://www.magnolia-cms.com/magnolia-cms/magnolia-4-4/previous-versions/magnolia-4-3/enterprise-multi-site-cms.html">manage multiple sites in a single instance</a>.</li>
<li>A forthcoming <a href="http://wiki.magnolia-cms.com/display/WIKI/Magnolia+Twigs+Module">social media module</a> will facilitate effortless integration with social media networks that have become a must for success on the Web.</li>
<li>Social bookmarking provided in many Magnolia templates.</li>
<li><a href="http://finnotype.blogspot.com/2011/01/search-engine-friendly-urls.html">Friendly URLs</a> make creating external links intuitive and easy to create.</li>
</ul>Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-7647234424212703072011-02-01T10:40:00.000+01:002013-12-19T09:53:28.744+01:00Keywords in page titles and meta elementsThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at inserting keywords in page titles and meta elements.<br />
<br />
Page titles are an extremely important SEO factor. Search engines give titles considerable algorithmic weight and use them as headings on search results. Titles should include keywords and, where appropriate, your company name for branding purposes:<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><title>Magnolia - Finance, Insurance & Banking</title></span></blockquote>
Description meta elements on the other hand do not add much to page relevance, but should not be neglected:<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><meta name="description" content="Magnolia's largest group of Enterprise Edition customers is from the..."></span></blockquote>
Their content often appears below the title in search results:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiutsHZ7FO2LUTaeI1SM12lEu2gpn087S_bxlpfxdnzFHA8hA07r1AU6vO91mNRiag1oJkdoqPIAOIwhgbc5eF41gdLb8tax1QvqqKUollSv5v4XGK3hhfyTZ9Nhk5C-W_DSaDBsA/s1600/keywords-in-google-results-.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiutsHZ7FO2LUTaeI1SM12lEu2gpn087S_bxlpfxdnzFHA8hA07r1AU6vO91mNRiag1oJkdoqPIAOIwhgbc5eF41gdLb8tax1QvqqKUollSv5v4XGK3hhfyTZ9Nhk5C-W_DSaDBsA/s1600/keywords-in-google-results-.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
The relevance of keywords stipulated in the keyword tag once had great impact, but this is no longer true. Actual page content is now far more relevant. Still, a keyword tag should be included:<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><meta name="keywords" content="Finance, Insurance, Banking"></span></blockquote>
Magnolia produces the title element from the page title automatically, so this aspect is never overlooked. Inserting keywords and descriptions is done in the page info dialog:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgHOYYc3BT6ablSVdv4l01trxaSfaNEU5WagaQteMdhSHSgSoIrZmuND4fuv8TXDLk6scs4WV8iLLLEZ94Bn_bsHm0Q7TsqEQw_d80oQkUnOGvYELYvdPjLQTUmcmBhGDnVLX-LNA/s1600/meta-keywords.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgHOYYc3BT6ablSVdv4l01trxaSfaNEU5WagaQteMdhSHSgSoIrZmuND4fuv8TXDLk6scs4WV8iLLLEZ94Bn_bsHm0Q7TsqEQw_d80oQkUnOGvYELYvdPjLQTUmcmBhGDnVLX-LNA/s1600/meta-keywords.png" /></a></div>
<br />
These fields can be made mandatory with a simple configuration change in AdminCentral. If an editor fails to provide the description, page abstract is used automatically as a fallback. Authors don't need to fill the field to be SEO compliant.Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-31232678251489040202011-01-28T09:48:00.000+01:002013-12-19T09:55:45.362+01:00Optimizing imagesThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at optimizing images.<br />
<br />
Great images enhance your site visually and enhance SEO rankings, provided they are properly optimized. Google and other search engines offer image-specific searches. A high rank in these searches increases your visibility. Search engines cannot read the content of images, and therefore must rely on accompanying text and tags.<br />
<br />
Best practices include:<br />
<ul>
<li>Image <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">alt</span> attributes with a short description of the image, for example. </li>
<li>Keyword-rich image file names. <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">yellow-roses.jpg</span> is far more descriptive and relevant than <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">img003.jpg</span>.</li>
<li>Size and quality optimized for quick loading. Crisp, sharp images look better in thumbnails displayed in search results, and are more likely to be linked to by other webmasters.</li>
<li>Captions that aptly describe the image assist vision-impaired users.</li>
<li>Width and height specified in the element. Many browsers render a page before images are downloaded. When dimensions are provided, other page elements wrap around them correctly, improving the initial user experience.</li>
</ul>
Images can be stored in Magnolia's built-in document management system or uploaded at editing time. When the DMS is used, a two-phase failsafe mechanism ensures that alt tags, appropriate file names, and captions are included:<br />
<div class="separator" style="clear: both; text-align: center;">
<br /></div>
<ol>
<li>At upload time, details such as image source, copyright, subject line and size are captured. The fields provided for this purpose in the DMS are based on the <a href="http://dublincore.org/">Dublin Core Metadata Standard</a>. If the original file name contains spaces, Magnolia replaces them with hyphens. In the event that an editor fails to include the information requested in the dialog, the source and subject-line are used as fallback.<br /><br /><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgYP_kQ4pYTOy3Q1S82BcyzAnUQzVKtBFUK2eRE8vm9C8E8NvkaKxUn512NfvalTI2eVIqgfPqZwlHZmbpZK1VgqNPctkGoDKBAmhtDmJqLfsJ0oL_tfJC48WseWBZqtxXnf54WhQ/s1600/asset-properties.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em; text-align: center;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgYP_kQ4pYTOy3Q1S82BcyzAnUQzVKtBFUK2eRE8vm9C8E8NvkaKxUn512NfvalTI2eVIqgfPqZwlHZmbpZK1VgqNPctkGoDKBAmhtDmJqLfsJ0oL_tfJC48WseWBZqtxXnf54WhQ/s1600/asset-properties.png" /></a><br />
<br />
</li>
<li>When inserting an image to a page, the information read from the DMS can be changed once again. If the fields are configured as mandatory, an editor cannot insert an image without providing suitable alt attribute and caption. This enforces best practice compliance.</li>
</ol>
As a result, the page template renders crawler-accessible HTML code:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEibE5mE4OppUiucTRcSizYg-60n86OtjK04xn4vd8bY1QgfhIzEfVr2mkGPfQFVH6tT6Mi2cYCsU0M_u7v0pynSTlAV_1tYh5fT_nFE2JuVrh6yETNkhU7mPcmd6mi8kkdZKTgeEw/s1600/inspect-image.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEibE5mE4OppUiucTRcSizYg-60n86OtjK04xn4vd8bY1QgfhIzEfVr2mkGPfQFVH6tT6Mi2cYCsU0M_u7v0pynSTlAV_1tYh5fT_nFE2JuVrh6yETNkhU7mPcmd6mi8kkdZKTgeEw/s1600/inspect-image.png" /></a></div>
<br />
Magnolia Imaging module ensures that high-quality, web-optimized images are used uniformly throughout the site. The module generates multiple variants from a single source image, resulting in considerable time-savings for editors. Sizing and cropping happens automatically, based on CSS rules. Built-in filters that scale and crop images can also be used for effects such as text overlays, which allow crawlers to read image text. It is possible to configure a standard output format and resolution for all images, and control the behavior of images in each area of a template.Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-73934640553944313722011-01-26T09:17:00.002+01:002013-12-19T09:57:35.162+01:00Redirecting trafficThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at redirecting traffic.<br />
<br />
Redirecting is the practice of sending requests to alternative destinations. Typical reasons to redirect are:<br />
<ul>
<li>Pages have moved due to site re-organization but search engines and users still have the old URLs in their indexes and bookmarks. Without redirection traffic going to the moved pages is lost to 404 errors.</li>
<li>Identical URLs serving the same content lead to duplicate content issues as crawlers mistake each URL for a separate site. This is known as the "canonical URL issue" in SEO parlance. It is not uncommon to have <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">example.com</span>, <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">www.example.com</span>, and <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">example.com/index.html</span> deliver the same content. Sometimes there is a valid need to display the same content on multiple pages.</li>
</ul>
These factors adversely affect SEO but they can be corrected by redirecting the incoming request to an alternative URL. There are several ways to redirect, but the only search engine friendly way is a 301 permanent redirect, which ensures that your hard-earned page rank is transferred to the new location. Contrast this with a temporary 302 redirect which is disastrous for SEO as page rank is not applied towards the new location.<br />
<br />
Redirects are typically cumbersome to implement on a Web server. Responsibility over Web server configuration often falls to another team and is out of reach for authors and editors, even for technical CMS team members. Fortunately, Magnolia allows you to configure redirects directly in AdminCentral.<br />
<br />
A permanent 301 redirect is easy to do with virtual URI mapping. The request can be redirected to the same domain or another one. For example, when visitors request <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">winter2010.com</span>, you can redirect them to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">example.com/marketing/campaigns/winter2010</span>, the actual location of the content. Short addresses are easier to market and remember.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh4yfSDtRalBJEU0YU-NMWB9lBwAXFxynNM_HxBBtfaf40baMcccIGoxAW2PG140ZbgmIuKryLm0GIAh6foIsg9AGTVQDnmL0TPkClE490cYq1vbFXs05vxr47wPgu0OuTVVMWGKA/s1600/vum.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh4yfSDtRalBJEU0YU-NMWB9lBwAXFxynNM_HxBBtfaf40baMcccIGoxAW2PG140ZbgmIuKryLm0GIAh6foIsg9AGTVQDnmL0TPkClE490cYq1vbFXs05vxr47wPgu0OuTVVMWGKA/s1600/vum.png" /></a></div>
<br />
In addition, the Templating Kit includes a Redirect template that allows authors to set up a redirect page and define where the incoming request should go. Both internal and external pages can be identified as redirection targets:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiSPUBZb8yR8JHGaOJP23ZSwTHLulo5nMGXKK-3HiK1LLd4rMclbLhbFOeAORL3qV_3j1fO5jyeiYPJqv5yVJ3WSF29UGT3noaHBtLpAOQpP3qDbBB6G4Y2Okn3afYNZ-NVi7l3jQ/s1600/redirect-page.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiSPUBZb8yR8JHGaOJP23ZSwTHLulo5nMGXKK-3HiK1LLd4rMclbLhbFOeAORL3qV_3j1fO5jyeiYPJqv5yVJ3WSF29UGT3noaHBtLpAOQpP3qDbBB6G4Y2Okn3afYNZ-NVi7l3jQ/s1600/redirect-page.png" /></a></div>
<br />
If you read more about the <a href="http://www.seomoz.org/blog/canonical-url-tag-the-most-important-advancement-in-seo-practices-since-sitemaps">canonical URL issue</a> on SEO blogs you will come across the "canonical URL tag". It is a <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">link</span> element in the page HTML head that tells crawlers that the page is actually a copy of the page given in the <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">href</span> attribute, and that page rank should be attributed to that page instead.<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><link rel="canonical" href="http://www.example.com" /></span></blockquote>
The canonical URL is almost the same as 301 redirect in terms of SEO with the following exceptions:<br />
<ul>
<li>301 redirect redirects all traffic (crawlers and visitors). The canonical meta element is just for crawlers.</li>
<li>301 is a stronger signal that multiple pages have a single, canonical source.</li>
<li>301 can redirect traffic to another domain, while still counting existing page rank towards the new location.</li>
<li>Canonical URL is sometimes favored over 301 because you don't need to ask developers to implement it. But as seen above, this is not an issue in Magnolia since editors can do their own virtual URI mapping in AdminCentral.</li>
</ul>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-82199500300928952452011-01-24T09:40:00.000+01:002013-12-19T10:01:27.127+01:00Categorizing contentThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at categorizing content.<br />
<br />
Usability and SEO go hand-in-hand. Categorizing content allows visitors to find related and similar content with ease. Logical, keyword-rich categories provide intuitive navigation of a large collection of content. Categorization offers a range of opportunities to improve internal linking, visibility, and keyword density. Common uses of categories are tag clouds, and links to overview and landing pages.<br />
<br />
Although content tagging is an effective technique, tag clouds in particular have been abused. Bloggers saw them as a keyword-stuffing opportunity, and search engines have developed techniques to combat this trend.<br />
<br />
Magnolia allows you to create custom categorization taxonomies. You can tag articles with categories to support browsing of related content. This feature can be extended and adapted to suit your needs.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgxuQYos7XOKDV1K66syYoIKouEeR86BtiSswC2HeAhmtsnXPESxAqFB-heEynUdZYEngj_LlVKjHCr-pzTe68Ecya7OuJoekPF5rEYm1c2rGhSyCfBkGwX7AsxQ7MpJYk57lseNQ/s1600/categories-app.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgxuQYos7XOKDV1K66syYoIKouEeR86BtiSswC2HeAhmtsnXPESxAqFB-heEynUdZYEngj_LlVKjHCr-pzTe68Ecya7OuJoekPF5rEYm1c2rGhSyCfBkGwX7AsxQ7MpJYk57lseNQ/s1600/categories-app.png" /></a></div>
<br />
By default, you can categorize any page based on the Article template. Categories are displayed as related links in the article header:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgC5Fcfjp9Vdx2eULXr25489uJkoxTZYq8ptTi8_oKokM06jZgmXxISvjwrlloDBLcVX3WHVrsYl6boIyJtu7yciiFASt4OSacSe1SxKtOuI565XYBs4pVDNqqIt508txjcNTHQ1Q/s1600/related-links.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgC5Fcfjp9Vdx2eULXr25489uJkoxTZYq8ptTi8_oKokM06jZgmXxISvjwrlloDBLcVX3WHVrsYl6boIyJtu7yciiFASt4OSacSe1SxKtOuI565XYBs4pVDNqqIt508txjcNTHQ1Q/s1600/related-links.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
<br /></div>
<br />
Magnolia provides an editorial Category Cloud which allows editors to assign weights to categories. The more weight a category has, the bigger it shows in the cloud:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhXEOYa7Enqbx2xouP24xhs7DScR50VKDNp8oe1ZvuJHagjcNtGOitA1nCIRFTMbzwwF5W-1SW55lOpPaWjmuABNqCaqUNTcvVKMAAie5W7mqo9pXlwfXbLJDtBBJhPx9jLyO91pQ/s1600/category-cloud.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhXEOYa7Enqbx2xouP24xhs7DScR50VKDNp8oe1ZvuJHagjcNtGOitA1nCIRFTMbzwwF5W-1SW55lOpPaWjmuABNqCaqUNTcvVKMAAie5W7mqo9pXlwfXbLJDtBBJhPx9jLyO91pQ/s1600/category-cloud.png" /></a></div>
<br />
The Category Overview template lists all articles within a category and suggests related categories:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiMTfZ59TKN5i1MzWBAX9pqSzeA_prqbdzIKvrNhB0ISpCiou6yzhd7bQlXK2bByiEQeJQcLK_D_PLL-4OoTx4ryEEYSoaWxIR5F54I_VaZvq73y8cmksftne9W1djWdKXjw8z91Q/s1600/category-overview.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiMTfZ59TKN5i1MzWBAX9pqSzeA_prqbdzIKvrNhB0ISpCiou6yzhd7bQlXK2bByiEQeJQcLK_D_PLL-4OoTx4ryEEYSoaWxIR5F54I_VaZvq73y8cmksftne9W1djWdKXjw8z91Q/s1600/category-overview.png" /></a></div>
<br />
<div class="separator" style="clear: both; text-align: center;">
</div>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-3550964698805620402011-01-21T10:41:00.001+01:002013-12-19T10:27:19.410+01:00Preventing broken linksThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at preventing broken links.<br />
<br />
Broken links can lower your site's rankings. Google mentions this specifically in its <a href="http://www.google.com/support/webmasters/bin/answer.py?answer=35769">SEO guidelines</a>. Broken links are also a source of irritation for users.<br />
<br />
While you have little control over changes to external links, you can inadvertently break internal links in a variety of ways, such as when changing site structure or deleting content that has incoming links.<br />
<br />
A process should be in place to regularly validate all links on a site.<br />
<br />
Magnolia has safeguards to prevent broken links:<br />
<ul>
<li>A hierarchical content store ensures that there are no orphaned pages that have no incoming links. All pages belong to a hierarchy, and each page has at least one incoming link - from its parent.</li>
<li>Each page has a unique content ID for use as an internal link target. Dialogs provide a user-friendly browser for locating the target. Authors don't need to know the unique ID.<br />
</li>
</ul>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjIz-flppNWMEUC6cqtOtqoYSnmk9DGX2x3foWvftWXXE13s-ZniY6VzXS-QERtINHa7c6ouhVSfj4PlmJz0aEcRTX86TS3WsZJ-q7Hh3GdCSNLA28kBZhOi7RvkvmKWCfrB86NBw/s1600/pages-chooser.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjIz-flppNWMEUC6cqtOtqoYSnmk9DGX2x3foWvftWXXE13s-ZniY6VzXS-QERtINHa7c6ouhVSfj4PlmJz0aEcRTX86TS3WsZJ-q7Hh3GdCSNLA28kBZhOi7RvkvmKWCfrB86NBw/s1600/pages-chooser.png" /></a></div>
<br />
<ul>
<li>The unique ID stays the same even when the target page is moved or renamed. This allows for flexible site reorganization without breaking the links. The same mechanism is used when linking to documents in the document management system (DMS). Internal links to non-existing pages and documents will not be rendered, avoiding broken links.</li>
<li>A reference view lists any incoming and outgoing links. A message on shows dependent content on deletion and deactivation.<br />
</li>
</ul>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhSN0NLQ7lqjSCQuYSLP1tySnUqMYLgzvlxXPxHGF9hIULkWLzixWbQT45XEQX_8mwu1pbjFAVYFXDtWRjn_uY8jokwb3J03pH11Z6gTD8GSDIm18MojW3xpKgoswr2bLDhHPI73g/s1600/deletion-warning.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhSN0NLQ7lqjSCQuYSLP1tySnUqMYLgzvlxXPxHGF9hIULkWLzixWbQT45XEQX_8mwu1pbjFAVYFXDtWRjn_uY8jokwb3J03pH11Z6gTD8GSDIm18MojW3xpKgoswr2bLDhHPI73g/s1600/deletion-warning.png" /></a></div>
<br />
<ul>
<li>A custom 404 "not found" page can be displayed for broken incoming links. You can provide helpful alternatives such as sitemap tree or a search box to find the desired content:<br />
</li>
</ul>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEikUJ9n71E7NqxXBjM4SPmDln9UTGn6rJt9sJCEeVkWZqicrV9dhFh3Qa2RD3pAC4nTVW2tCmV26cjIySC1gpnbZ5iA9wJRffqnOsj6POktqVWCTLbT08lYGgBbNMxatKYOg4D8pQ/s1600/404.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEikUJ9n71E7NqxXBjM4SPmDln9UTGn6rJt9sJCEeVkWZqicrV9dhFh3Qa2RD3pAC4nTVW2tCmV26cjIySC1gpnbZ5iA9wJRffqnOsj6POktqVWCTLbT08lYGgBbNMxatKYOg4D8pQ/s1600/404.png" /></a></div>
<br />
Magnolia does not check for outgoing broken links but third party link checker tools for this purpose exist.Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-56676476087374755912011-01-19T16:42:00.001+01:002013-12-19T10:29:13.052+01:00HTML linksThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at inserting HTML links.<br />
<br />
Navigation links should be rendered as HTML to make them easy for crawlers to read. Search engines take the anchor text of a link into consideration when indexing it. Graphics and Flash objects, used by many designers to control look and feel, normally cannot be crawled. Alternative text descriptions should be provided. Use of uncrawlable elements also hinders users who do not have the required browser plug-ins.<br />
<br />
Since the navigation system is a site-wide collection of links to topics, links should be consistent throughout the site. Navigation is also a perfect opportunity to include descriptive keywords.<br />
<br />
The Magnolia Templating Kit offers four navigation structures out-of-the-box: horizontal, vertical, breadcrumbs, and meta-navigation. All of them render links as HTML. Consistent navigation is enforced throughout the site using the same template.<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiEPedoIAkkxsQtYvtGLr9TQBmc1GbORJ701aWb30nuZaIMRDmI6kex2wAmURN4wbfJyshBevq5HBwEp2tN0Acvg6setJqW_eojlmUApvnLtEUOKW8mAnMytG0qBHS_07aJZyY2xA/s1600/navigation.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="251" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiEPedoIAkkxsQtYvtGLr9TQBmc1GbORJ701aWb30nuZaIMRDmI6kex2wAmURN4wbfJyshBevq5HBwEp2tN0Acvg6setJqW_eojlmUApvnLtEUOKW8mAnMytG0qBHS_07aJZyY2xA/s400/navigation.png" width="400" /></a></div>
<br />
<div class="separator">
</div>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-12736598864562659532011-01-17T14:18:00.000+01:002013-12-19T10:30:27.641+01:00Shallow site architectureThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at providing a shallow site architecture.<br />
<br />
Site architecture is critical to SEO. Many sites grow organically and their architecture becomes a maze-like, illogical complex. A clear structure provides both the user and web crawler with a positive navigational experience.<br />
<br />
As a rule of thumb, the flatter the structure, the better. The higher a page appears in the site structure, the more likely it will be ranked high by a crawler. Crawlers seem to determine the depth of a page by the number of directories present in the URL, giving more relevance, for example, to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/books/art</span> than to <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/books/bestsellers/hardcover/art</span>. A one or two layer limit is recommended, but for larger sites this is not always feasible.<br />
<br />
It is also important to maintain consistency throughout your site. All pages should follow the same format, and once established, you should endeavor to stick to the URL guidelines. Where possible, avoid the use of sub-domains as crawlers may view them as separate from your main domain.<br />
<br />
Magnolia stores content in a hierarchical content repository. Editors see the hierarchy as a tree where each page belongs to a branch and has a parent node:<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi3NEAEtBFFaxNbxEml29jw489YfRaEdmfzhF3MKOl54C8ZE6aU0PQx-SLwTkGZtwCiVwgvEqSSrf4yq_3kaRqLM5MVIA_VP45GpVzTVeHndzJXNp5SnKbpL07RlAjAqyiMWCubUg/s1600/tree.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi3NEAEtBFFaxNbxEml29jw489YfRaEdmfzhF3MKOl54C8ZE6aU0PQx-SLwTkGZtwCiVwgvEqSSrf4yq_3kaRqLM5MVIA_VP45GpVzTVeHndzJXNp5SnKbpL07RlAjAqyiMWCubUg/s1600/tree.png" /></a></div>
<div class="separator">
</div>
<br />
Organizing a site as a hierarchy enforces consistent structure. Pages and branches can be rearranged via drag-and-drop.<br />
<br />
Magnolia allows you to manage an unlimited number of sites in AdminCentral. Each site has its own site tree, to keep the hierarchy shallow. You can map unique domain names to each site, creating microsites for campaigns, for example. To a crawler, these appear either as unique sites (<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">www.winter2010.com</span>) or as parts of your domain (<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">winter2010.example.com</span>).<br />
<br />
Sometimes it is difficult to avoid deeper structures. For example, you may want to create a campaign inside your main site at <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">/example/marketing/campaigns/winter2010</span>. Adhering to the shallow hierarchy principle is possible even in this case. Magnolia allows you to shorten the URL with URI mapping. Visitors and crawlers access the campaign site at <span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">www.example.com/winter2010</span> while the content is served from the true location deeper in the hierarchy.Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-22691603412649162362011-01-14T09:30:00.000+01:002013-12-19T10:33:23.412+01:00Search-engine friendly URLsThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at creating search-engine friendly URLs.<br />
<br />
URLs are an important SEO element for search engines as well as users. Search engines are more likely to index static, short, clean URLs. Users appreciate their readability too. While most crawlers can follow dynamically generated URLs, there is evidence that when dynamic parameters are appended to a URL, the crawler only follows them to sites considered to have high importance. Request parameters should be avoided in the URL, as the crawler may view several URLs pointing to the same content as duplicates, lowering page rank.<br />
<br />
Good<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.yoursite.com/books/hardcover</span></blockquote>
Bad<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.yoursite.com?p=72&s=0</span></blockquote>
<br />
Page URLs should:<br />
<ul>
<li>Include important keywords, as keywords are highlighted in search results. Most SEO experts agree that including them in a URL is important. Keywords also increase the likelihood of a visitor clicking through to your site.<br />
</li>
</ul>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjzYOsh5uY1GMeIJTivACF0qBjF-bms9ShtFDwsztIgm6XyFt5iCfOIRWpMj4LqP7-CXTkv-HzQjyfIpC8SJcBQZNHMpJC0hs97hmPwitGLTXU0Ffx6WsgVGhBcFK9FTAOrVeQY9Q/s1600/keywords-in-results.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjzYOsh5uY1GMeIJTivACF0qBjF-bms9ShtFDwsztIgm6XyFt5iCfOIRWpMj4LqP7-CXTkv-HzQjyfIpC8SJcBQZNHMpJC0hs97hmPwitGLTXU0Ffx6WsgVGhBcFK9FTAOrVeQY9Q/s1600/keywords-in-results.png" /></a></div>
<ul>
<li>Have short, case-insensitive words, separated with hyphens.</li>
<li>Be descriptive of page content. Both from the SEO and usability perspectives, an obvious URL is a good URL. URLs get pasted, shared and written down, so the more obvious the content, the better.</li>
<li>Avoid the use of meaningless numbers and extraneous information.</li>
</ul>
<br />
Magnolia produces clean, human-readable URLs by default. Dynamically generated URLs are converted to crawler-friendly static ones. Request parameters are not appended to URLs.<br />
<br />
<div class="separator">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiuXVIvnsPOkAokGejTP8XYI7mhROWl_eVRCjKFJe0igbsEedETHy2r_kbwenrYil4puQ_rfjy6Kzz-HHz5JOuITeOUw3FPgLcpiviaJjQNkSRjfxmMyxfMvawI8J1lDy1Wk690oQ/s1600/friendly-url.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiuXVIvnsPOkAokGejTP8XYI7mhROWl_eVRCjKFJe0igbsEedETHy2r_kbwenrYil4puQ_rfjy6Kzz-HHz5JOuITeOUw3FPgLcpiviaJjQNkSRjfxmMyxfMvawI8J1lDy1Wk690oQ/s1600/friendly-url.png" /></a></div>
<br />
Some systems append session IDs to a URL. A session is typically needed when a user logs in. A user's shopping cart is an example of content that would be stored in a session. Appending session IDs to URLs is a security issue. A URL that contains an ID cannot be copied without the risk of inadvertently handing the session to another user.<br />
<br />
Good<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.yoursite.com/cart</span></blockquote>
Bad<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.yoursite.com/cart?jsessionid=undn2i50l4</span></blockquote>
Magnolia is session-less until the user logs in. At that point, a session ID is stored in a cookie instead of appending it to the URL. This avoids the duplicate content issue and makes URLs safe to copy and share.<br />
<br />
When creating internal links, Magnolia uses the title of the target page as anchor text by default. The title typically includes the most relevant keywords about the target page.<br />
<br />
Minimizing length and trailing slashes will make URLs easier to copy and paste, and fully visible in search results. A Magnolia URL is equally valid, regardless of whether you include an .html suffix or slash:<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.magnolia-cms.com/clients/references</span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.magnolia-cms.com/clients/references.html</span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">http://www.magnolia-cms.com/clients/references/</span></blockquote>
<div>
<br /></div>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.comtag:blogger.com,1999:blog-11804845.post-91464420474569330022011-01-12T10:38:00.000+01:002013-12-19T09:50:51.678+01:00Restricting crawler accessThis post belongs to a series about <a href="http://finnotype.blogspot.com/2011/01/search-engine-optimization.html">search engine optimization</a> (SEO) with Magnolia CMS. Today we look at restricting crawler access.<br />
<br />
<div style="margin-bottom: 0px; margin-left: 0px; margin-right: 0px; margin-top: 0px;">
While SEO is mostly about about enticing that crawlers to your content, there are some pages you may not want them to access. These include administrative, password protected, and paid access pages.</div>
<br />
A robots.txt file restricts crawler access on a site-wide basis. The file is typically placed in the root directory of your site. All legitimate crawlers it check fro the presence of a robots.txt file, and respect the directives it contains. Even if you do not want to restrict access, it is advisable to include a robots.txt file because the absence of one has been known to produce a 404 error, resulting in none of your pages being crawled. This can also be the case if the file is not constructed correctly. Specific crawlers can also be denied access by entering their names or IP addresses in the file.<br />
<br />
The following example instructs all crawlers to keep out of the private and temp directories and denies access to a specified crawler.<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">User-agent: BadBot # replace 'BadBot' with the actual user-agent of the bot</span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">Disallow: /private/</span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;">Disallow: /temp/</span></blockquote>
It is also possible to exclude individual pages with a robots meta element in the page HTML header.<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><html></span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><head></span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><title>...</title></span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW"></span><br />
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"></head></span></blockquote>
Relevant values for the robots meta element are:<br />
<ul>
<li>NOINDEX prevents the page from being included in the index.</li>
<li>NOFOLLOW prevents the crawler from following any links on the page. Note that this is different from the link-level rel attribute which prevents the crawler from following an individual link. For anti-spam reasons, it is generally better to use the rel attribute with value NOFOLLOW for individual links.</li>
<li>NOARCHIVE instructs the crawler not to keep the page in the engine's public index. With Google, this prevents a cached copy of the page from being available in search results.</li>
</ul>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhNm7YILOSpLoon2TSmNL_ucg8hE6W9c4mzcT4I-qC-azIdI2lZeRf3s8jChZOiSMQGgTuNiencyq33dzyO1hSiQUraCqUFsJmoRV_iJReoATzXCsoCB2k3dyVKvLXHV3oynVpA6w/s1600/google-search-example.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhNm7YILOSpLoon2TSmNL_ucg8hE6W9c4mzcT4I-qC-azIdI2lZeRf3s8jChZOiSMQGgTuNiencyq33dzyO1hSiQUraCqUFsJmoRV_iJReoATzXCsoCB2k3dyVKvLXHV3oynVpA6w/s1600/google-search-example.png" /></a></div>
<br />
Preventing crawlers from following undesirable links can help combat automated spam. This method is endorsed by all major engines. Adding a rel="nofollow" attribute to a link allows control on an individual link basis. It can be used to reference external content while not endorsing it, and overcomes the necessity to exclude the crawler from all links on a page.<br />
<blockquote style="background-color: #f0f8fd; border: 1px dashed #c1d8df; margin-left: 10px; padding: 3px;">
<span class="Apple-style-span" style="font-family: 'Courier New', Courier, monospace;"><a href="http://www.badsite.com" rel="nofollow"></span></blockquote>
<br />
You can use all the above access restriction methods in Magnolia:<br />
<ul>
<li>Editing a robots.txt file is vastly simplified in that Magnolia produces clean, human-readable URLs such as http://www.magnolia-cms.com/support-and-services.</li>
<li>At a single-page level, templates set the robots meta element in the HTML header to "all" by default, allowing full crawler access. Options to change this behavior can be offered to editors with minimal configuration directly in AdminCentral. Customization would involve adding a field in the Page Info dialog definition and a minor tweak to the paragraph template.</li>
</ul>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiYfcPkHesBV84WEdfa_kxc_bUZ027j7EeyAjMNHOMm4ueQWhszpMWILeDDPaiTP0fBe-McVNQUML2DXtjKxepXKA4__Zb0PiCj1lmzUHdkOjzrZDDU-IlyqRhg07FRLcIPeR0pmw/s1600/robots-access.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em; text-align: center;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiYfcPkHesBV84WEdfa_kxc_bUZ027j7EeyAjMNHOMm4ueQWhszpMWILeDDPaiTP0fBe-McVNQUML2DXtjKxepXKA4__Zb0PiCj1lmzUHdkOjzrZDDU-IlyqRhg07FRLcIPeR0pmw/s1600/robots-access.png" /></a></div>
Antti Hietalahttp://www.blogger.com/profile/11746937085383393559noreply@blogger.com