Smart Loader Lite - Forge Documentation
1. Short Summary
Smart Loader Lite is a reusable OutSystems Reactive Web component that displays loading indicators while an operation is running. It supports FullScreen, Card, and Inline loading modes with a CSS-based spinner, custom messages, Light/Dark/Blue themes, optional full-screen blur, and an optional cancel link.
2. Component Details
Component Name: Smart Loader Lite
Module Name: SmartLoaderLite
Public Block: SmartLoader
Recommended Demo Screen: SmartLoaderDemo
Database Required: No
Target App Type: Reactive Web App
Primary Users: Developers, QA teams, support teams, release teams, and SRE teams
3. Key Features
- Full-screen loading overlay
- Card loading mode
- Inline loading mode
- CSS-based animated spinner
- Custom loader message
- Optional sub-message
- Light, Dark, and Blue themes
- Optional background blur in FullScreen mode
- Optional cancel link
- Lightweight implementation
- No database or server action required
- Easy integration into forms, buttons, API calls, and long-running UI actions
4. Supported Display Modes
FullScreen:
Covers the full page with a centered loader card. Best for form submissions, page-level processing, report generation, API calls, and actions where user interaction should be blocked.
Card:
Shows a centered loader card in the screen or section where the block is placed. Best for section-level loading or modal/card processing.
Inline:
Shows a compact spinner with text inline. Best for small loading states such as table refresh, search loading, or small async actions.
5. Block Inputs
IsLoading: Boolean
Controls whether the loader is visible.
Example: True or False
LoaderMessage: Text
Main message displayed in the loader.
Example: Loading..., Saving changes..., Generating report...
LoaderSubMessage: Text
Optional supporting message below the main text.
Example: Please wait while we process your request.
DisplayMode: Text
Supported values: FullScreen, Card, Inline
Theme: Text
Supported values: Light, Dark, Blue
ShowSpinner: Boolean
Controls whether the spinner is visible.
BlurBackground: Boolean
Applies blur only in FullScreen mode in Version 1.
AllowCancel: Boolean
Shows or hides the cancel link.
6. Recommended Defaults
IsLoading = False
LoaderMessage = "Loading..."
LoaderSubMessage = "Please wait."
DisplayMode = "FullScreen"
Theme = "Blue"
ShowSpinner = True
BlurBackground = True
AllowCancel = False
7. Final Block Structure
Use this structure inside the SmartLoader block:
SmartLoaderContainer
LoaderCard
Spinner
LoaderMessageText
LoaderSubMessageText
CancelLink
8. CSS Class Mapping
SmartLoaderContainer: dynamic smart-loader classes
LoaderCard: smart-loader-card
Spinner: smart-loader-spinner
LoaderMessageText: smart-loader-title
LoaderSubMessageText: smart-loader-subtitle
CancelLink: smart-loader-cancel
9. SmartLoaderContainer Style Classes Expression
Use this expression in the SmartLoaderContainer Style Classes property:
"smart-loader "
+
If(
ToUpper(Trim(DisplayMode)) = "INLINE",
"smart-loader-inline ",
ToUpper(Trim(DisplayMode)) = "CARD",
"smart-loader-card-mode ",
"smart-loader-fullscreen "
)
ToUpper(Trim(Theme)) = "DARK",
"smart-loader-dark ",
ToUpper(Trim(Theme)) = "BLUE",
"smart-loader-blue ",
"smart-loader-light "
If(BlurBackground, "smart-loader-blur", "")
10. How to Integrate into Any App
Step 1: Add Dependency
Open the consumer application in Service Studio, go to Manage Dependencies, select SmartLoaderLite, and add the SmartLoader block.
Step 2: Add Local Variable
On the screen where the loader is required, create a Boolean local variable.
Example:
IsSaving: Boolean
Default: False
Step 3: Place the SmartLoader Block
Place the SmartLoader block on the screen or layout.
Step 4: Configure Inputs
Example configuration for a save operation:
IsLoading = IsSaving
LoaderMessage = "Saving changes..."
LoaderSubMessage = "Please wait while your data is being saved."
Step 5: Control Loader in Client Action
In the save button client action:
1. Assign IsSaving = True
2. Call the save/server action
3. Assign IsSaving = False
4. Show success or error message
Important: In exception handling, always set IsSaving = False so the loader does not remain visible after an error.
11. Example Configurations
FullScreen Loader:
IsLoading = IsProcessing
LoaderMessage = "Processing request..."
LoaderSubMessage = "Please wait while we complete your action."
Card Loader:
IsLoading = IsRefreshing
LoaderMessage = "Refreshing data..."
LoaderSubMessage = "Fetching latest information."
DisplayMode = "Card"
Theme = "Light"
BlurBackground = False
Inline Loader:
IsLoading = IsSearching
LoaderMessage = "Searching..."
LoaderSubMessage = ""
DisplayMode = "Inline"
Dark FullScreen Loader:
IsLoading = IsLoadingData
LoaderMessage = "Loading dashboard..."
Theme = "Dark"
12. Demo Screen Recommendation
Create a screen named SmartLoaderDemo with these local variables:
- IsLoading
- LoaderMessage
- LoaderSubMessage
- DisplayMode
- Theme
- ShowSpinner
- BlurBackground
- AllowCancel
Suggested default values:
LoaderSubMessage = "Please wait while data is being loaded."
Add demo buttons:
- Show Loader
- Hide Loader
- Set FullScreen Mode
- Set Card Mode
- Set Inline Mode
- Set Light Theme
- Set Dark Theme
- Set Blue Theme
13. Testing Checklist
- FullScreen loader appears when IsLoading = True
- Card loader appears when DisplayMode = Card
- Inline loader appears when DisplayMode = Inline
- Spinner appears when ShowSpinner = True
- Spinner hides when ShowSpinner = False
- LoaderMessage displays correctly
- LoaderSubMessage displays correctly
- LoaderSubMessage hides when blank
- Light theme works
- Dark theme works
- Blue theme works
- Blur works in FullScreen mode
- Loader hides when IsLoading = False
- Cancel link appears when AllowCancel = True
- Cancel link hides when AllowCancel = False
- Mobile layout looks acceptable
14. Troubleshooting
Loader does not appear:
Check IsLoading value, SmartLoaderContainer visibility, and Style Classes expression.
Spinner does not appear:
Check ShowSpinner = True, Spinner.Visible = ShowSpinner, and Spinner Style Classes = smart-loader-spinner. If the spinner container is empty, add a small blank expression inside it to force rendering.
Spinner does not rotate:
Check that @keyframes smartLoaderSpin exists in the CSS and there is no reduced-motion CSS disabling animation.
Blur does not work in Card or Inline mode:
This is expected in Version 1. BlurBackground applies only to FullScreen mode.
Loader does not hide after error:
Ensure exception handling sets the loading variable back to False.
15. Version 1 Behavior Note
In Version 1, BlurBackground is applied only in FullScreen mode. Card and Inline modes do not blur the page or parent container. Blur support for Card and Inline modes is planned for a future version.
16. Best Practices
- Use FullScreen mode when user interaction should be blocked.
- Use Card mode for section-level or modal-level processing.
- Use Inline mode for small loading indicators.
- Always reset IsLoading to False in success and error paths.
- Keep LoaderMessage short and action-specific.
- Use LoaderSubMessage for helpful guidance such as Please do not refresh the page.
- Use Blue theme for modern enterprise apps.
- Use Dark theme when the app has a darker UI or when stronger focus is needed
19. Version Notes
Version 1.0.0
- Initial release
- Added SmartLoader block
- Added FullScreen, Card, and Inline display modes
- Added CSS-based spinner animation
- Added custom message and sub-message
- Added Light, Dark, and Blue themes
- Added FullScreen blur support
- Added optional cancel link
- Added demo screen support
20. Future Enhancements
- Blur support for Card mode
- Glass effect for Inline mode
- Configurable blur intensity
- Progress bar support
- Percentage progress support
- OnCancel event
- Preset loader templates
- Skeleton loader mode
- Dots loader mode
- Page-level global loader service