Page Blocks

Hosting sponsored by:

Point In Space

Code Style Standards

| View List | Style Guide | Secure Code Standards |

Names

File Names

File names are governed by the structural requirements of the page assembly engine and the use of custom file extensions. Refer to the docs (link to be added) for details of the page assembly engine and how that dictates file naming rules.

File Extensions

The pageblocks framework uses custom file extensions to aid in identifying file purpose. The following are the standards:

  • .ctag = custom tag source code files
  • .ctyp = custom type source code files
  • .lgc = page block logic code
  • .dsp = page block display code
  • .cnfg = configuration file
  • .lasso = browser loadable stub/process file

Variable Names

At the top level there are two distinctions in variable names: those belonging to the pageblocks framework, and those belonging to the application. All framework variables begin with fw_ whether they are global or page. Local scoped variables in custom tags used to also have fw_ prefxies, but as of version 5.2, I've begun a transition away from that, and dropping the prefixes (there's no scope conflict with app vars, and there's no need to identify private status like there is with ctype instance vars). Application variables should have either no prefix or an app specific prefix. However, one method or the other should be picked and enforced consistently throughout the application.

Variables are prefixed as follows to denote some meaning as to their role or usage.

  • fw_ = prefix to all framework vars (lack of g means it is a page scoped var)
  • fw_g = global : a framework var in the Lasso global namespace
  • m_ = model object data member : the var is a part of the data structure of the model
  • c_ = controller object data member : the var is a functional attribute of the controller code
  • v_ = view object data member : the var is functional attribute of the view code
  • i_ = form input : the var is created from a form input which is not a attribute of an m_, v_, or c_ object
  • x = temporary : meaning used as temporary scratchpad/register to hold a value needed primarily within the scope of a short code segment. I didn't use the letter t just in case it may be more useful for something else, and x has a certain "temporary" quality to it
  • pv_ = application specific custom type private instance variable

Variable names are written in camel case where words are adjoining with no underscores, and each word begins with an uppercase letter such as $xThisLineItem, $fw_gErrorAlertEmail, $fw_pageModes->'useAutoErrorDisplay'. As for vars where acronyms get embedded such as $fw_SMTPServer, the uppercase letters are fine. Some standards prefer the camel case be preserved, but some find it easier to recognize the acronym when it remains in all caps (I fell into the latter camp). Abbreviations are camel case as in $m_userPswd or $m_rcrdSelected.

There is no attempt or need to include variable data types in the name. That's what var declarations are for. With Lasso being a loosely typed language, some vars will change from one data type to another anyway. There's no rule against including the data type in the name as there may be cases where something like $m_configDataString is converted to $m_configDataArray and both need to be preserved, however, there's also no rule that such naming is required, and it is not desired except where there's a clear need. In fact, I'd be inclined to rename the previous example vars as $m_configDataRaw and $m_configData under the right circumstances.

Examples:

  • $fw_gQueryUser, where $fw_g = a framework level variable in the global namespace. All global vars are expected to remain unchanged by the application.
  • $xPriorSessionTimeout = an application variable with a temporary purpose which in this case appears to be holding what that prior SessionTimeout value was before we temporarily set it to a new value
  • $m_articleTitle, $m_articleAuthor = vars for data values from an article data structure (model)
  • $c_btnClicked = var from a controller that stores what button was clicked

As for full words versus shortend words, most words should be spelled out, but a few exceptions are worth saving the space and typing such as these which are commonly used in pageblocks framework code:

  • btn = button
  • pswd = password
  • err = error
  • rcrd = record
  • pg = page
  • app = application

CTag and CType Names

Pageblock framework tags are prefixed with fwpNnnn_ where the Nnnn is a name of a collection of related tags and types. The rest of type name is camel case starting with lowercase. Pageblock framework custom types are named with an fwp_ prefix and the rest of the name camel case starting with lowercase. With Lasso 8 deciding to use the underscore as a namespace separator, this does mean that fraemwork tags end up consuming multiple name spaces rather than a single one. Not much we can do about that one except to start over, and that's not happening any time soon. By the way, the fwp acronym is a legacy leftover from when the framework was called FWPro which distinguished the Lasso 5/MySQL version from my original FrameWork which was Lasso 3 and FileMaker Pro 5 oriented.

Application-specific tags and types should adopt a prefix either unique to the company or the application as it seems appropriate. Prefixes of tag_ and typ_ are useful for generic app-specific naming where company or product identiity is not important. The most important thing is to pick some patterns and stick to them.

Some pageblocks framework tag and type name examples:

  • fwpActn_updatePrep (tag)
  • fwpGUI_stylize (tag)
  • fwp_collection (type)
  • fwp_authenticatedUser (type)

Possible application-specific examples:

  • tag_emailToAuthor
  • typ_newsArticle
  • acmeUnits_lbsToKg
  • acmeUnits_feetToMeters

CType Instance Variable Names

Prior to 8.5, Lasso did not allow for private variables, but we still needed to communicate which vars should not be considered part of the custom type's attributes. So, to communicate this, instance variable names have a few different rules. Pageblocks framework custom types will use fw_ prefixes for all variables which the programmer should not be accessing directly. Application specific instance vars which are to be considered private should begin with pv_.

Instance vars for both framework and application-specific custom types which are to be public attributes do not have to use any prefix according to the above rules. Instead those vars should read naturally in the object->noun relationship such as $myArticle->'title' and $myPO->'shipDate'. While we're here, you'll notice the use of the quotes. Lasso allows these to be optional, the pageblocks framework style is to always include them for all instance vars regardless of there being an identically named member tag or not. The reason is simple: it's signficantly faster if quotes are used.

CType Member Tag Names

Prior to 8.5, Lasso did not allow for private member tags, but we still need to communicate which tags should not be called directly by the programmer. So, to communicate this, private member tag names in custom types of the framework will begin with fw_, and those in application-specific custom types should begin with pv_. These would only be called with self-> tags in the ctype code like (self->pv_sortItems) and (self->fw_sortItems). This practice started after most of the framework code was already written, so it's not 100% reliable yet that a tag without an fw_ prefix should be considered public.

Public member tags should read naturally in the object->verb relationship such as $myArticle->update and $myPO->getInventoryStatus.

Indenting, Spacing, and Statement Punctuation

Code is indented using tabs equivalent to 4 spaces per tab. I understand the advantage of spaces remaining consistent in various mediums, but tabs enable faster keyboarding through the whitespace, and that's what I've adopted. You're more than welcome to adopt your own preference, but this is how the master files will be saved, and all contributed code will need to be in this format.

Var Declarations

Variable declarations should have the assignment aligned and indented like this:

    var:
        'color'        = string,
        'shape'        = string,
        'borderColor'  = string;

Note there is no () around the assignment data types. I used to do that, but have switched to no (), so it's probable you'll see both in source files until this update is also made. No parens is preferred. Data types or initial values in declarations are fine, but it is preferred to be clear about the initial value data type. Do not use quotes for numeric values, and cast dates as date data types, etc.

Avoid embedded assignments in var declarations where possible. It's easier to undertstand and maintain a separate sequence of steps than lengthy nested assignments, and the time difference isn't measurable. If some hairy nested assignment is necessary, then it should be accompanied by explicit comments even if it appears obvious at the time the code is written.

Tag Paramaters

Tags with one or two parameters can optionally be coded on one line, but for the most part tags with two or more parameters should have each parameter on a separate line with the parameters aligned like this:

    fwpGUI_popup:
        -name    = 'mCities',
        -blank   = false,
        -dflt    = var:'mCities',
        -list    = var:'vCitiesList';

Where tags are nested and the nested tag also has parameters, indenting should be done like this:

    fwpGUI_popup:
        -name    = 'mCities',
        -blank   = false,
        -dflt    = var:'mCities',
        -list    = (string_replace:
                       var:'vCitiesList',
                       -find     = '\r',
                       -replace  = '```');

Statement Punctuation

Pageblocks framework code does not use C-style use of (). Closing ) and ; and ); are put at the end of the code, not on separate lines. If I had to pick a style to emulate it would be more like Python than C.

Speaking of () sets. As we know, Lasso 7 changed the rules and got a lot more picky about places where () are required. Therefore, as a rule, my pendulum has swung and more () are better than fewer () just in case we go through another round of increased sensitivity. I've also done some testing that showed LP6 was faster with fewer (), but LP7 (and presumably 8) are actually faster with more (). So more it is.

Also, Lasso 8 introduced yet more syntax styles with the paren syntax. All pageblocks framework code follow the original LassoScript style with colons following tag names.

Here's some examples of how I use () and spaces in various statements:

  • if: ((var:'x') == true) || ((var:'y') == true);
  • $myObject->(method: -param1='abc', -param2='xyz');
  • #someVar + (self->'iVar') + 'literal stuff';

There should always be spaces around operators like + - *, etc. There should always be spaces around = in assignments (although you will find some old code in PB that doesn't do that, this will eventually be changed as code is updated). In tags where params are on a single line, I tend not to use spaces around the =, but with or without spaces is OK.

For the most part, conditional statements and container tags should have blank lines before and after the IF, ELSE, SELECT, and CASE lines. Likewise, a blank line after container tags with params like INLINE, LOOP, etc. Closing tags do not need empty lines. In cases, where there's just a single line, and the code is simple, then leaving out the blank lines so the whole block can be easily read as one chunk is OK. As the nested elements get to several lines, then the blank lines should be included. Code should be thought of as paragraphs. Each new "thought" begins a new paragraph which in the source code means blank lines. Likewise, tags with multiple parameters should often be separated with blank lines too.

inline:
    -username = $fw_gUserName,
    -password = $fw_gUserPswd;

    if: ((var:'x') == true) || ((var:'y') == true);

        ..... many lines of stuff here .....

    else: (var:'z') == true;

        loop: 10;
            loop_count; ' - '; $varX; '<br />\r';
        /loop;
    /if;
/inline;

Commenting

Most of the framework code was originally written before Lasso supported block style comments. Block style comments are now used in the headers of each file, but inline commenting of the code is done with single line comments. This helps them stand out more when syntax coloring is not available.

Comments are not added after lines of code like this:

var:'xyz' = string;   // this commenting is not used

All comments are to be on their own lines above the block being discussed, and for the most part they should all be fully left justified regardless of the indenting of the code at that point. The idea is tha it should be easy to scan for comments along the left margin. Having said that, given the age of some source files, you will find a mixture of commenting styles. Those spelled out here are preferred, and gradually the source files will be updated to conform to them.

// comments are on their own lines
// and should always be full left justified

    var:'xyz' = string;
    $xyz += 1;

Major section breaks (those between different functional steps, or breaks between lengthy if or case statements) should include horizontal lines of hyphens to the 80th character position. If subsections need to be divided to aid clarity in section breaks, use shorter breaks to the 60th character position, and start the break from the code's indent position. The purpose of the horizontal splits is to provide some visual cues as to the arbitrary code sections while scrolling. There's no set rules as to when exactly to use them, but I think you can get a feel for the usage by viewing source files. For member tag sections within custom types, a different style of commenting mini-headers for each tag is used. You can view some source code files for examples.

//----------------------------------------------------
// section label
//
// section comments if needed are after an empty
// line so the label stand out clearly, and
// end with an empty line as well
//

select: $someVar;

    case: 'choiceA';
        var:'xyz' = string;
        $xyz += 1;

//----------------------------------------------------
    case: 'choiceB';
        var:'xyz' = string;
        $xyz += 1;

//----------------------------------------------------
    case: 'choiceC';
        var:'xyz' = string;
        $xyz += 1;

        //--------------------------------
        $xyz->split:', ';

Gotcha Commenting

Comments are to help code maintainers know what code chunks are doing, but even more importantly sometimes it is also to explain why things work the way they do. So, don't be shy and tell it like it is. If code is a kludge or there's some tricky dependencies that will be difficult to trace, or there's a bug that just can't be located, then plainly comment the code to that effect. I've adopted these notations:

  • TODO = means there's more work to do here to finish or improve the intended functionality
  • BUG = known bug whether or not the cause is known
  • KLUDGE = explain something was hacked for expediency
  • WARNING = something about this is not obvious when you read it, difficult dependency or other such thing, or the code is very complex, changing anything could cascade trouble, think before you type

History:

  • updated Jul 21, 2007 (Greg Willits)
    • fixed some linguistics, minor updates re: Lasso 8.5
  • updated Jan 02, 2006 (Greg Willits)
    • updated docs to reflect conventions for version 5 and the name change to pageblocks
    • changed discussion relative to global vars which are now used (previous versions did not use Lasso global vars)
  • updated Aug 19, 2005 (Greg Willits)
    • updated docs to reflect var name conventions for FWPro4
    • changed m,v,c to m_, v_, c_ and added form input f_
  • first release Apr 8, 2005 (Greg Willits)

The inspiration for this format, and some ideas for content came from here.


© 2002-2013, pageblocks.org