If you’re just joining us, welcome to the third and final installment of our series on good Argos DataBlock design. Our first two chapters covered Planning Your Ideal DataBlock and Getting The Look Just Right. Now, we’ll examine an often-overlooked but equally important aspect of good DataBlock design—documentation.

When you’re designing DataBlocks, it’s important to keep in mind that you’re probably not the only user who will be interacting with them. Even if you are, it is likely that, in six months, you won’t remember what every piece of your design does, or why you designed it that way. Good naming conventions and clear descriptions can save other designers (or even just your future self) from confusion down the road.

Naming Scheme

As we’ve strongly recommended in a previous blog post, adopting a naming scheme can go a long way to make your DataBlock more understandable, both to other designers and to yourself as you continue to develop. You can save yourself and others plenty of time if you follow some simple rules for naming your objects. Since your SQL queries may reference these objects as variables, it is a good practice to name them as you are creating them. Every object you place on a dashboard has a property called “Variable Name.” We recommend updating this property before doing anything else. Don’t wait until after you have written all your SQL! Argos will not auto-update the variable references in your queries, and you may run into situations where your DataBlock will require quite a bit of editing to weed out every reference to a variable you may rename after the fact.

Rule of Three

As a general guideline, an object/variable name should tell you three things.

• First, it should tell you where on the DataBlock the object is located. This is especially important on dashboards made up of multiple forms.
• Next, the name should indicate what type of object it refers to. This will quickly tell you what sorts of (and how many) values it might return. A list-box variable might return multiple values of varying lengths, while a checkbox variable will only be a binary.
• Lastly, a variable name should describe the contents of the object. (i.e., What is the object actually showing? Term Codes? Accounts? Student Fields of Study?)

We put these three pieces together to create our recommended object naming convention.

<FormName>_<ObjectType>_<ObjectDescription>

Example: Term Code

Let’s take this term selection DropDown:

Location: “Main” form
Object Type: DropDown
Object Description: Term Code Selection
So we would name the object: “Main_DD_Term”

Note that Argos does not allow spaces in variable names, so we instead use an underscore to separate words. Also note that, for the sake of being concise, we use a two-character abbreviation (“DD”) to denote the object type.

For reference…

Evisions uses the following abbreviations:

• BT (Button)
• CB (Check Box)
• CH (Chart)
• DT (Date Entry)
• DD (Drop Down List Box)
• EB (Edit Box)
• LB (List Box)
• MB (Memo Box)
• MC (Multi-Column List Box)
• RB (Radio Button)

SQL Variables

We name SQL variables slightly differently. We start with a ‘sql_’ designation. Then, if the variable is used on one particular form, we’ll give the form’s name. Lastly, we’ll once again end with a short descriptor of what the variable does. This will make the variable easier to find when we want to reference it later.

sql_<Form Name>_<Variable Description>

For example, if we’re using a SQL variable to place a student ID on the “main” form, we’d name the SQL variable “sql_Main_GetStudentID.”

Keep in mind that other non-variable objects – such as labels, OLAP cubes, panels, scroll boxes and shapes – can be named in a similar fashion, and you may indeed find it useful to do so, but naming is less necessary with these than with objects that can be used as parameters.

DataBlock Description

The last point we’d like to leave with you is to always clearly describe your DataBlocks and the objects contained therein. So far, we’ve been discussing object and variable names, which will only be visible to DataBlock designers. However, as designers, it is perhaps even more important that the DataBlocks we create are understandable to our report viewers, and that starts with giving each DataBlock a good name and description. Argos also allows you to put notes into each DataBlock, which can be used to provide even more information.

Be clear and descriptive

On your DataBlock’s forms, you can use SQL and add labels to describe what an object does. Be as descriptive as necessary so that your end users don’t have to guess at what that object is doing.

As an example, let’s say you make a listbox to allow users to make a selection for organizations. If the listbox contains only org codes and nothing else, it may not be immediately obvious what exactly the object is doing. In the listbox’s SQL, you might concatenate the org descriptions in with the codes to give the display more context for the user. You can also add a label above the listbox that says “Organization.” If the listbox is configured to allow multi-select, you could make the label say “Select Organization(s),” to hint at the fact that they can select more than one org without writing explicit instructions.

If your users do need steps or instructions, consider adding an extra form they can reach where they can find that information. Your end-user feedback will help you determine the right amount of guidance to include or exclude from your forms. You need to strike a balance between being sufficiently informative and creating a simple and clean interface without the clutter of unnecessary or redundant information.

Remember: You are the Designer

While we can make suggestions and provide these tips, nothing in design is a hard, fast rule. Each institution we work with has had different ideas, needs and rules. Meeting the needs of your end users is always key here. Communicate with your end users to get a feel for what they need. Be open to feedback, and always be willing to try something new to take your DataBlock design to the next level.