As SAC developers, we primarily focus on end-user requirements and experience, while also considering the broader impact of the content we build (network and source system performance).
But how often have you revisited an SAC story to enhance it, or inherited one created by someone else only to be confronted with a myriad of widgets using default names, no logical grouping, and layouts that require painful dragging and dropping to adjust?
In this blog, we’ll look at best practices based on experience that will make your life, and the lives of your fellow SAC developers far easier.
Naming Conventions
If you’ve read this far and get no further, the biggest single thing you can do to make developing SAC content easier is to use naming conventions.
- Create a set of standard naming conventions for widgets
- Give widgets meaningful names
- Don’t get lazy and stop doing it
Below is an example of the prefixes I use, the main point being use something that works for you and your colleagues.
* Ensure it’s included in your organisation’s design guidelines
| Widget Type | Standard Pre-Fix | Example |
| Bar Chart | chartB_ | chartB_revenue_by_state |
| Line Chart | chartL_ | chartL_margin_by_product |
| Numeric Point Chart | kpi_ | kpi_actuals_vs_budget |
| Waterfall Chart | chartWF_ | chartWF_spend |
| Table | tbl_ | tbl_invoices_by_month |
| Panel | pnl_ | pnl_title |
| Text Box | txt_ | txt_title |
| Image | img_ | img_logo |
| Shape | shape_ | shape_header_divider |
| Button | btn_ | btn_page2 |
| Dropdown List | ddl_ | ddl_product |
| List Box | lb_ | lb_store |
| Radio Button Group | rbg_ | rbg_managers |
No one wants to see this in the outline view when editing a story!
When writing script it’s really not helpful hitting CTRL space and getting a meaningless list of charts……err which one was it again??
Far nicer to be presented with this.
Layouts
When building a story, I use panels wherever possible to group content.
Based on 100’s of story builds over the years I’ve yet to see a significant performance impact of using many panels within a SAC story.
Grouping content allows you to quickly navigate to it in design mode, makes it super easy to move blocks of content around if the layout needs changing.
It also makes scripting far simpler when you need to show/hide content (just hide the panel, not all the widgets it contains individually)
Example
This is typically how I structure a story layout, each distinct block of content is contained within a panel, you can also see in the outline view that the content is logically ordered top to bottom and left to right.
The same logical order (and naming convention) is carried on within each panel
At a glance you should be able to understand what is what and where it is, without even seeing the widgets in the main story window.
Script structure and annotation
This topic has been written about, probably shortly after the first ever line of code or script was created
Yet it’s incredibly rare I open a SAC Story created by someone else and find fully documented script.
Even rarer is to find script that is not only annotated at a line level but also contains a summary level comment.
Summary level annotation provides great insight into the logic, how the block of code fits into the overall design & interaction with other code blocks.
As a quick example, here’s part of the code I wrote for a noughts and crosses game in SAC
Here’s part of the same script with annotation and a summary.
Someone else picking up work on this story would quickly be able to understand the logic and how the code interacts with other script in the story.
In this example I simply pasted the code into Chat GPT and asked it to annotate and summarise the script.
It did a fairly decent job, but you should always sanity check the output.
Other Thoughts
Panel Auto Scroll
I always turn this off, no one needs yet more scroll bars!
plus it makes it harder to arrange content within panels if there’s no hard stop on the widget layout position.
Flow Panels
Awful things they make setting up layouts really painful and shouldn’t be needed if you’re clear about what you’re building.
Dynamic Layout / Sizing
It’s always a challenge to build a story that looks good on varying screen sizes.
I typically build the story using auto widget widths and fixed px left and right values, once I’m happy with the overall layout I change the Left/Right px unit to %
This allows widgets to auto size better when screen sizes vary.
You can go a step further and setup a number of CSS styles to change font sizes etc when the widget size changes.
Summary
Taking the time to apply consistent naming conventions, logical layouts, and well-structured, annotated scripting is about building SAC stories that are scalable, maintainable, and developer friendly.
Whether you’re handing a project over to a colleague or revisiting it six months later, these habits dramatically reduce friction and improve development efficiency.
Good design isn’t just for end users, it starts with the developer.