Smartsite Coding and Architecture Guidelines, annotated version - ΩJr. Coding Guidelines

Get certified

Seneca regularly schedules trainings. Editors, Editorial Managers, as well as Engineers, should take Editor and Site Management training. Manuals are available online.

Engineers should take the Site Building, Installation, Outscaling, and Workflow training, plus added courses for specialisations. Technical documentation is available to registered engineers.

Get the correct version of the documentation

Every version of Smartsite iXperion is equipped with its own technical reference documentation. You can find it in the “bin” folder, named “smartsite.chm”. It should work on MS Windows, if they have hh.exe installed (which is standard).

The “bin” folder is not exposed to the web. Copy the file, add the correct version number, and place it in a readily available location.

Use the company’s iXperion Website Template

If you don’t have one, build it, and put someone in charge of maintaining it. This prevents you from having to reapply time-proven settings and building time-proven structures, with every new website.

Change the default credentials

The default credentials are documented well in installation docs and manuals. Your competitors will know them, and so will disgruntled ex-coworkers. Change the after installation, even when you use the company template, and make them unique per site.

After deployment, disable auxiliary accounts

Avoid letting your coworkers and customers reuse passwords from one site to the next, or from test sites to live sites. Disable their accounts, and contact them to have them reset their passwords during a real-time conversation. Test users should remain deactivated unless testing requires their reactivation.

Apply custom error pages

Out of the box, Smartsite iXperion’s EmptySix website includes one generic error page, and is set to guide all errors to that page. This error page discloses too much information and uses a visual layout that almost never meets the customer’s needs. Make it unavailable.

Instruct Smartsite not to handle its own errors. Instead, instruct both the web server and its technological framework to capture and deal with errors. Build 2 error pages (outside of the CMS): one for http-500 errors, and one http-404 page for all other errors. This prevents people from trying various error strategies to hack a site, and provides detailed error information to an engineer with access to the web server.

Those custom error pages should retrieve their sources from the file system, and not from Smartsite. This prevents a cascade of http-500 and -404 errors, which will crash the web server. The error pages should be simple, straightforward, yet let the visitor recognise the site and branding. See the Google 404 page for example.

For image and other binaries folders, instruct the web server to return error images rather than web pages.

Augment the web server cache and compression

By default, the MS IIS web servers cache too little. Add mime types to IIS7’s httpCompression. Cache almost anything that goes to visitors, except for web pages. Do compress web pages. Do not cache .dws, .xml, .net and other real-time application files, but do compress them.

On IIS 7, the caching (a.k.a. static compression) may break due to a failure of the IIS to validate the cache file directory. We have yet to find a solution.

In IIS 6, mime types were added in the metabase.xml, as file extensions. In IIS 7, mime types are added as mime types, in a dedicated configuration file. See this reference: IIS7 HTTP Compression.

Avoid iXperion’s Javascript and CSS Combinator

Smartsite iXperion has its own combinator for Javascript and CSS files, using its SCF (Smartsite Client Framework). It combines and minifies files from the “scf” folder as well as Smartsite items that contain Javascript and CSS, if so indicated.

This works when your database contains a single web site with a single visual layout and javascript needs. In all other cases, it fails to provide necessary flexibility.

You should keep it active and continue to use its default files, as Smartsite needs them for its default Smartlets. However, your site- and layout-specific files should be added to your rendertemplates using an overrulable translation. Do not let the combinator add your files for you.

The easiest way to do this, is by keeping the Javascript and CSS files in their own folders, which is almost the way the Front-End Developers are supposed to deliver them:

/<site name>

  /Assets

    /c (for CSS files)

    /i (for images that aid the lay-out)

    /j (for Javascript files)

    /m (for multimedia files)

The Front-End Developers will not include an “Assets” folder: this is a Smartsite-specific folder that allows us to exclude access by regular editors. They are instructed to combine and minify script and CSS files.

You can still add page-specific CSS and Javascript to specific web pages, for instance if you need to create dynamic CSS and Javascript contents using vipers or macros. In that case, add it using the Smartsite Placeholder vipers. Also see the Javascript and CSS section at the bottom of this article.

Use channels for multi-language

This way you can get the most out of built-in functionality like sub-site management, string localisations, automated separation of search results, and automated repositories. You can bind domain names and date display to languages, easily determine which editor gets to author which language, and enable the editorial management to choose whether or not to publish an article in a certain language and locale.

Accept the visitor’s language prefs

There’s a 20-year old HTTP preference that tells you what languages the visitor accepts. Use it. Don’t try and outwit that mechanism. Chances are, the visitor either didn’t set it and you should accept their setting, or they did set it and you should accept their setting. As a bonus, provide a secondary language switch, and have that switch take priority.
Reference: A.E.Veltstra (2009): “Detecting the user’s preferred language”.

Turn channel properties bulk-updatable

If your website uses more than, say, 3 channels, turn their contenttype properties bulk-updatable. It will prove a time saver.

Never grant your customer the administrator role…

unless they are certified Site Builders and you contractually agree to have warranty voided. Instead, create less able roles that follow the customer’s business structure.

Remember Data Mgmt

Appoint a customer employee as responsible for the site’s data management. Cleaning up old articles and removing finished tasks speeds up the site.

Use the “ELBA” coding architecture

Available from Smartsite iXperion’s “EmptySix” website database, ELBA allows for modularisation, reuse, inheritance, and overrules, of translations, a.k.a. the Smartsite code building blocks. It keeps rendertemplates clean, and offers an easy way to determine which building block is used by which template.

Identify pages and templates

Make it easy for the maintenance personnel to figure out what page they’re looking at, and which rendering it uses. Provide this information as HtmlMetaElements, applying a vendor prefix befitting your company.

Provide pagination both above and below lists

This is a usability standard. It makes moving through long listsit easier for visitors. (Visitors tend to forget the “top”/“home” button on their keyboard, and some devices don’t even provide one.) If it is omitted from the Functional or Interaction Design, inform all parties.

This rule is added because adding pagination in Smartsite can prove tricky and time-consuming.

Prefix custom database objects

Tables, views, procedures, functions, triggers, etc: add a prefix to show that they aren’t default Smartsite objects. Use a site prefix if the object is not used for other customers, otherwise use your company’s vendor prefix.

Prefix client-specific site objects

String localisation names, custom Smartlets, item relations, thesauri, manager actions, rendertemplates, translations, channels, and contenttypes: add a site prefix to identify in which site they should be used.

Identify items by code…

rather than number. This mainly concerns records from the contents table. When transporting material from the development environment to the testing, acceptance, and later the live environments, the item’s sequence number is likely to change. Its code property however holds a GUID (Globally Unique Identifier), which you can consider a constant.

Always filter user input

Whether your client has asked for form validation or not, you need to protect the site’s database. Smartsite and the technology framework do provide a bit of protection, but since they cannot predict the client’s needs, additional filtering is your responsibility. Filter the input and only allow that which you require.

Always filter database output

You might have assumed that no editor would ever enter HTML in a Title or Description field. You might have assumed the contents of those fields would never hurt your HTML output. You assumed wrong. Filter it and only display what you expect.

Use HTML forms

Smartsite includes a form wizard for editors. It includes all form controls and input validation. It will suffice for quite the variety of forms and needs.

Our customers can use the wizard forms. Seneca provides form building trainings. Know that it requires a user and password, which is set in configuration, and should be updated when the equivalent Smartsite user credentials are updated.

Our Front-End Developers however will build forms in HTML, adding client-side scripting for validation. We add the server-side form handler with checks and validations, ignoring the form wizard.

Provide semantic meaning

Name object and memory buffers after why they are used, instead of what they are or what they do. The name should provide meaningful, beneficial information, that can’t be acquired easily from the CMS. This keeps the need for additional descriptions and in-code comments to a minimum.

Provide references

When building and maintaining objects, provide references to functional and technical designs, and issue tracking numbers, in the object’s Notes field. This will aid your coworkers when they need to adjust or research uour work.

Also provide a brief functional description if the item has a description field. This will aid the understanding of why something exists in cases where a functional design turns absent.

Always provide reasonable friendly names

Your company’s iXperion website template should provide these for initial site hierarchies. For customer-specific article hierarchies, you yourself will need to think up friendly article names. Expect that your client’s editors have no expertise in this field. If your company includes SEO specialists, acquire their advice.

Some hints:

• Empty friendly names for folders to remove their presence from a descendant’s friendly name. Consider config and supportive content folders, or sub site container folders.
  
• Friendly names of channels will be shown as soon as the visitor visits a page outside of the default channel. For multi-language channeling, name the channel’s friendly name after its language code.
  
• Pages in multi-site databases still require unique friendly names. (Much unlike file-based web sites, that can use the same name for pages in each different folder.)
  
• Friendly names must never equal names of folders in the file system.
  

Let article collections stay in context

For sites that use taxonomy and meta information to list articles in overviews, you may have considered collecting those articles in collection folders, like a site-wide news archive. If so, let that archive remain part of the normal site hierarchy. Do not move it out of context.

The hierarchical context is required if you care to provide a meaningful navigational environment to the site visitors. It dictates the contents of menus, breadcrumbs, and maybe even the colour of the page or the site logo. Moving the article collection out of that context means you have to reintroduce one, artificially. That will fail at the most inopportune of moments.

Without further adjustment, storing an article in one place and showing a hyperlink to it in another place, will transport the visitor, changing contexts. If the customer seeks to keep the visitor in the same context, have their editors create article stubs. A stub displays content from a different article. Smartsite’s proprietary Repository system is based on article stubs, adding editor workflow automation.

Capture errors in macro execution

All Smartsite macros sport an error property. Use it. Leaving it empty will completely hide the error unless you add some checks. We do not advise hiding errors: it leads to longer problem solving time, and thus angry customers. Instead, output an error message to the web page, either visibly or in source, with some identification of the offending macro.

Hint: once a macro falls into error mode, it suppresses all other formatting you have requested. Your error message will be “naked”, i.e. void of any formatting.

Block indentation and whitespace

Macro blocks are XML based. Start child blocks on a new line. Indent child blocks with 1 tab. The current SXML Editor does this automatically when you ask it to format your code.

Unfortunately, those new lines inside a macro also make it into the output: whitespace is significant. That results in an output that proves a difficult read, if not an annoying read due to the amount of scrolling through pointless whitespace.

Thus, tell your macros to trim their whitespace. Beware of greedy removal: it will lead to smushedtogethertexts. Balance is key.

Macro properties and attributes

Put each property and attribute on its own line, indented with 1 tab, except for parameter collection members, where having the attribute on the same line may benefit comparison from one member to the next.

Attributes are written in lower case, no matter what the documentation suggests. Otherwise your macros will fail.

Write vipers and translations in lower case

The documentation will show vipers with one or more upper case letters. Translations can be stored with one or more capitals. Nonetheless, when programming, you need to write them all in lowercase, lest they will fail to execute.

Inside translations: check for field and item existence

Since translations cannot dictate who calls them, they need to check whether the callee supports the properties the translation was intended to manipulate. Here are some hints:

• Do not assume that the provided translation parameter actually refers to an active item that lives in the active channel: check it first.
  
• Do not assume that a field exists in the current item: the translation may have been misplaced, and the item contenttype may have been altered. Check it first.
  
• Do not assume that the callee did indeed set that memory buffer you are about to use. Always check it. Possibly even set it, yourself.

OK. Sometimes you cannot check things. If it fails, it fails good. Then let it fail. Capture the error and store it in a log somewhere. Inform someone. Inform the visitor, but omit the tech details.

And sometimes checking doesn’t seem worth the time and effort… until you run into a website where simple editorial changes will break execution.

Inside formatting macros: check for field existence

Inside a sitemap macro, we like to retrieve values from fields we expect. But what happens if an editor throws in an unexpected contenttype? We don’t want that to cause the whole site to crash: we'd like to see our sites a bit more robust.

Use Regions to capture errors

If parts of your coding fails, the whole page will fail, unless you capture the errors. Not all procedures allow for error capturing. Those, you contain in regions, which in turn do allow error capturing, That way, only part of the page will fail, but the rest of it will still work.

Prominent places where regions come to the resque:

• Invalid URL locators and inactive embeds
  
• Null-values from databases inside formatting procedures
  
• Sessions in preview mode
  
• Accepting form and query input
  

Do not compare string contents…

unless you are comparing hard-coded literals provided there and then. Do not compare memory buffer contents, item field contents, user input, or database contents, without precaution. If you need to check whether the contents are empty, equate its length property to 0 (zero). If you absolutely must compare unfiltered contents, then at least hash or encode it, removing any possible harm.

Hint: Smartsite iXperion does not allow comparing to or dealing with Database Null values. Capture them in Regions.

Avoid direct database queries

Smartsite iXperion lets you retrieve, sort, filter, and format articles without needing to write any database query. This may seem useful only in environments that are likely to switch databases. More importantly: it adds a data protection layer. Secondly, it adds an abstraction level that reduces the amount of required SQL knowledge amongst CMS implementation engineers.

In cases where using self-written queries provide significantly faster execution, remove them from Smartsite’s parser altogether and have them executed in a compiled middleware component, like a Page Component or a custom Viper. Add a data protection layer inside the component. You can also store a query as a view or a stored procedure in the database, depending on your needs. A query in a stored procedure in MS SQL Server usually performs faster than the same query in any component or macro. Moving the queries into compiled middleware or the DBMS however, also reduces the ease of access.

Javascript and CSS

By default, you add Javascript and CSS using the placeholders. You should never have to add it to a web page immediately. As always, there will be exceptions. In such cases, we can add either to our web page like this:
<script type="text/javascript">/* {html.cdata(" */
//Your Javascript code here
/* ")} */</script>
<style type="text/css">/* {html.cdata(" */
/* Your CSS code here */
/* ")} */</style>

Why a CDATA section?
It tells the Smartsite SXML parser to generate a CDATA block, which tells the HTML parser in the browser to skip parsing its contents.

Why the multiline instead of single-line comments?
Because these work in both Javascript and CSS, meaning you have to remember fewer guidelines.