Summary of the Smartsite Coding and Architecture Guidelines - ΩJr. Coding Guidelines

Get certified

Seneca regularly schedules trainings. Manuals are available online.

Get the correct version of the documentation

Every version has its own. 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.

Change the default credentials

Change them after installation, including 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. 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.

Those custom error pages should retrieve their sources from the file system, and not from Smartsite. 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 an compression

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.

See this reference: IIS7 HTTP Compression.

Avoid iXperion’s Javascript and CSS Combinator

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.

Keep the Javascript and CSS files in their own folders:

/<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. You need to combine and minify their script and CSS files.

If you need to create dynamic CSS and Javascript contents using vipers or macros, add it using the Smartsite Placeholder vipers. See the Javascript and CSS section at the bottom of this article.

Use channels for multi-language

Exploit the built-in functionality.

Accept the visitor’s language prefs

There’s a 20-year old HTTP preference that tells you what languages the visitor accepts. Use it. 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.

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.

Identify pages and templates

Provide this information as HtmlMetaElements, applying a vendor prefix befitting your company.

Provide pagination both above and below lists

Advise your customer to apply this.

Prefix custom database objects

Tables, views, procedures, functions, triggers, etc: add a prefix. 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.

Identify items by code…

rather than number. This mainly concerns records from the contents table.

Always filter user input

Only allow that which you require.

Always filter database output

Only display what you expect.

Use HTML forms

Our customers can use the wizard forms. 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.

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.

Provide references

When building and maintaining objects, provide references to functional and technical designs in the object’s Notes field, and issue tracking numbers in the object’s business logic field. Also provide a brief functional description if the item has a description field.

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. If your company includes SEO specialists, acquire their advice.

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.

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. Hiding errors is bad practice. Output an error message to the web page, either visibly or in source, with some identification of the offending macro.

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.

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.

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.

Inside translations: check for field and item existence

Check whether the callee supports the properties the translation was intended to manipulate.

Inside formatting macros: check for field existence

We'd like to see our sites a bit robust.

Use Regions to capture errors

Not all procedures allow for error capturing. Those, you contain in regions.

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 cannot compare to or work with null values. Use regions.

Avoid direct database queries

Smartsite iXperion lets you retrieve, sort, filter, and format articles without needing to write any database query. This adds a data protection layer and an abstraction level.

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.

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>