Managing Static Assets
Static Assets provide centralized storage and management for JavaScript files, CSS stylesheets, and image resources used throughout portal customization implementations. The Static Assets section in the Integrated Development Environment enables developers to organize, upload, reference, and maintain web resources through hierarchical folder structures while supporting automatic code insertion into Active Pages and Templates for efficient development workflows.
Understanding static asset management capabilities, folder organization strategies, upload processes, and code insertion features enables developers to maintain well-organized resource libraries that support consistent styling, reusable scripts, and optimized media delivery across portal implementations.
Understanding Static Assets
Purpose and Functionality
Static Assets serve as the centralized repository for all client-side resources required by Active Pages, Templates, and Content Pages including JavaScript libraries and custom scripts for interactive behaviors, CSS stylesheets for visual styling and layout, images for logos, icons, backgrounds, and content illustrations, and other web resources like fonts or downloadable documents.
Centralized Management: The Static Assets section provides a single location for all web resources, eliminating scattered files across multiple locations and enabling efficient resource discovery, reuse, and maintenance across all portal customizations.
Performance Optimization: Static assets are served efficiently by the Magentrix platform with appropriate caching headers and content delivery optimization. Properly organized and optimized assets improve page load times and overall portal performance.
Supported File Types
The Static Assets section supports all common web resource file types without restrictions on format or file type selection.
JavaScript Files:.js files containing JavaScript code for interactive behaviors, form validation, dynamic content manipulation, AJAX operations, and integration with external JavaScript libraries and frameworks.
CSS Stylesheets:.css files containing styling rules for visual appearance, layout definitions, responsive design specifications, animation definitions, and theme implementations.
Image Formats: All standard web image formats including .jpg/.jpeg for photographs and complex images, .png for images requiring transparency or lossless compression, .gif for simple graphics and animations, .svg for scalable vector graphics, and .ico for favicons.
Other Resources: Additional file types such as font files (.woff, .woff2, .ttf, .eot), downloadable documents (.pdf, .docx), or other resources that pages may reference can be uploaded as static assets.
No File Size Restrictions
The Static Assets section does not impose file size limits on uploaded resources, providing flexibility for comprehensive resource libraries including large JavaScript frameworks, high-resolution images, and extensive CSS libraries.
Optimization Responsibility: While no size restrictions exist, developers remain responsible for optimizing assets appropriately for web delivery. Large unoptimized files impact page load times and user experience regardless of upload capability.
Performance Considerations: Balance resource completeness against performance requirements by minifying JavaScript and CSS files, compressing images appropriately, using responsive image techniques for different device sizes, and implementing lazy loading for non-critical resources.
Creating Folder Structures
Accessing Folder Creation
Navigate to the Static Assets section in the sidebar navigation tree. Expand the section if necessary to display the Root folder and any existing folder hierarchy.
Right-click on the Root folder or any existing folder to display the context menu. Select New Folder from the context menu options to open the folder creation dialog.
Folder Naming
Enter a descriptive folder name that clearly indicates the contents or purpose of the folder. Folder names should support logical organization and enable efficient location of specific resources during development.
Descriptive Names: Use folder names that communicate content type or functional area such as "JavaScript," "CSS," "Images," "Logos," "Icons," "Libraries," or "Themes." Clear names enable quick navigation to desired resources.
Project Organization: Consider creating project-specific or feature-specific folders such as "Dashboard," "Registration," "Partner-Portal," or "Mobile" to group related resources supporting specific portal areas or functionality.
Consistent Conventions: Establish and follow consistent folder naming conventions across all static assets. Consistency improves maintainability and enables developers to predict folder locations without searching.
Folder Creation Completion
Click Create to generate the new folder. The IDE creates the folder within the parent folder where creation was initiated, updates the sidebar navigation tree to display the new folder, and makes the folder available for file uploads or additional nested folder creation.
Nested Folder Structures
The Static Assets section supports unlimited folder nesting depth, enabling hierarchical organization that reflects logical resource groupings and relationships.
Hierarchical Organization: Create nested structures such as /Images/Logos/Partner-Logos/ or /JavaScript/Libraries/External/ to establish clear organizational hierarchies that group related resources at appropriate levels.
Balance Depth and Simplicity: While unlimited nesting is supported, balance organizational detail against navigational complexity. Excessively deep hierarchies may hinder resource discovery and complicate path references.
Folder Purpose: Use nested folders to separate resources by type (JavaScript vs. CSS), purpose (libraries vs. custom code), project (different portal sections), or any organizational scheme that supports efficient resource management for the development team.
Uploading Static Assets
Accessing Upload Functionality
Navigate to the desired destination folder within the Static Assets section of the sidebar navigation tree. Resources will be uploaded into the selected folder, so choose the appropriate organizational location before initiating upload.
Right-click on the destination folder to display the context menu. Select Upload Asset(s) from the context menu options to open the file selection dialog.
File Selection and Upload
A file browser dialog appears enabling selection of files from the local file system. Navigate to the location containing files to be uploaded.
Single File Upload: Select a single file and click the upload or open button to upload that file to the selected destination folder.
Multiple File Upload: Select multiple files simultaneously using standard multi-select techniques (Ctrl+Click or Shift+Click on Windows/Linux, Command+Click on macOS) to upload multiple files in a single operation. Multiple file upload improves efficiency when adding numerous resources.
File Transfer: Confirm the file selection to initiate upload. The IDE transfers selected files to the Magentrix platform and adds them to the destination folder. Upload progress indicators may appear for large files or multiple file operations.
Upload Completion
After upload completes, uploaded files appear in the sidebar navigation tree under the destination folder. Files are immediately available for reference in Active Pages, Templates, and Content Pages.
Immediate Availability: Uploaded assets become accessible immediately without requiring additional activation or deployment steps. Pages can reference newly uploaded assets as soon as upload completes.
Name Verification: Review uploaded file names in the sidebar to verify correct uploads and appropriate naming. Rename files if necessary to follow established naming conventions or correct upload errors.
Renaming Static Assets
Rename Process
Right-click on the asset file or folder name in the Static Assets tree to display the context menu. Select Rename from the context menu options to open the rename dialog.
Enter the new name for the asset or folder in the provided input field. Maintain file extensions when renaming files to preserve proper file type identification (e.g., keep .js for JavaScript files, .css for stylesheets).
Click the confirmation button to apply the rename. The IDE updates the asset or folder name in the sidebar navigation tree and internal references immediately.
Reference Update Requirement
Manual Code Updates: Renaming assets does not automatically update references to those assets in Active Pages, Templates, or other code files. All code referencing the renamed asset must be manually updated to use the new name.
Reference Search: Before renaming frequently used assets, use the IDE's global search functionality to locate all references to the asset. Search results identify all files requiring updates after the rename operation.
Testing After Rename: After renaming assets and updating code references, test affected pages thoroughly to verify that all references were updated correctly and resources load properly. Missed references cause broken links and loading errors.
Renaming Best Practices
Initial Naming: Plan asset names carefully during initial upload to minimize the need for subsequent renaming. Well-chosen initial names reduce maintenance effort and prevent reference update requirements.
Coordination: Coordinate asset renames with team members working on related code to ensure all developers are aware of name changes and update references appropriately in their work.
Version Indicators: Consider including version indicators in asset names when maintaining multiple versions (e.g., library-v1.2.js, library-v2.0.js) rather than renaming existing files. Version-specific names enable controlled migration to new versions.
Deleting Static Assets
Deletion Process
Right-click on the asset file or folder in the Static Assets tree to display the context menu. Select Delete from the context menu options to initiate the deletion process.
A confirmation dialog appears requesting verification of the deletion operation. The confirmation message may indicate the number of files affected when deleting folders containing multiple assets.
Confirm the deletion to permanently remove the asset or folder from the Static Assets section.
Permanent Deletion
No Recycle Bin Recovery: Static Asset deletions are permanent and cannot be recovered from the Recycle Bin. Unlike Active Pages, Controllers, Classes, and Triggers which can be restored from the Recycle Bin, deleted Static Assets are immediately and permanently removed from the system.
Backup Requirement: Maintain external backups or version control for critical static assets to enable recovery if assets are accidentally deleted. External backups provide the only recovery mechanism for deleted Static Assets.
Careful Confirmation: Exercise particular care when confirming Static Asset deletions. Verify that assets are truly no longer needed and that backups exist if any possibility of future need remains.
Deletion Impact Assessment
Reference Identification: Before deleting assets, identify all Active Pages, Templates, and Content Pages that reference the asset. Use the IDE's global search functionality to search for the asset filename across all code files.
Broken References: Deleting assets that are referenced in active pages creates broken references that prevent proper resource loading. Pages referencing deleted assets may display incorrectly, lose functionality, or generate error messages.
Testing Requirements: If assets must be deleted despite active references, update all referencing code to remove or replace asset references before deletion. Test affected pages after deletion to verify that functionality remains intact without the deleted assets.
Folder Deletion: Deleting folders removes all contained assets and nested folders recursively. Verify the complete contents of folders before deletion to avoid accidentally removing needed resources nested within folder hierarchies.
Adding Assets to Pages
Automatic Code Insertion
The Static Assets section provides automatic code insertion functionality that generates properly formatted HTML code referencing selected assets and inserts it into open Active Pages or Templates at the cursor position.
Efficiency Benefit: Automatic code insertion eliminates manual typing of asset paths, reduces path errors, ensures correct reference syntax, and accelerates development workflow by handling repetitive code generation automatically.
Supported Page Types: Automatic code insertion works with Active Pages and Templates. Content Pages using WYSIWYG editing may require manual HTML source editing to insert asset references.
Adding Assets to Pages
Open an Active Page or Template in the editor to display the page content and editing interface. Position the text cursor at the location where the asset reference code should be inserted.
Navigate to the Static Assets section in the sidebar and locate the asset to be added. The asset can be in any folder within the Static Assets hierarchy.
Right-click on the asset file to display the context menu. Select Add to Page from the context menu options to trigger automatic code insertion.
The IDE automatically generates appropriate HTML code based on the asset type and inserts it at the current cursor position in the open page or template.
Generated Code Formats
JavaScript File Insertion: When adding JavaScript files, the IDE generates HTML <script> tags with correct src attributes referencing the asset path:
<script src="/staticassets/path/to/file.js"></script>
CSS File Insertion: When adding CSS files, the IDE generates HTML <link> tags with correct rel and href attributes referencing the asset path:
<link rel="stylesheet" href="/staticassets/path/to/file.css">
Image File Insertion: When adding image files, the IDE generates HTML <img> tags with correct src attributes referencing the asset path:
<img src="/staticassets/path/to/image.png" alt="">
Path Accuracy: Generated code includes correct relative paths from the page to the asset based on the asset's location in the folder hierarchy. Automatic path generation eliminates path calculation errors and ensures proper resource loading.
Code Insertion Requirements
Open Page Requirement: Automatic code insertion requires that an Active Page or Template be open in the editor at the time of insertion. If no appropriate page is open, the Add to Page option may be disabled or produce no effect.
Cursor Position: Code is inserted at the current cursor position within the open page. Ensure the cursor is positioned at the appropriate location in the page markup before initiating code insertion to avoid placing generated code in incorrect locations.
Manual Adjustment: After automatic code insertion, review and adjust generated code as necessary including adding alt text for images, modifying script tag attributes, adjusting link tag media queries, or reorganizing inserted code for optimal page structure.
Organizing Assets with Best Practices
Folder Structure Strategies
Type-Based Organization: Create top-level folders for each asset type (JavaScript, CSS, Images) with nested subfolders for more specific categorizations. Type-based organization enables quick navigation to resources of specific types.
/Root
/JavaScript
/Libraries
/Custom
/Validation
/CSS
/Themes
/Components
/Responsive
/Images
/Logos
/Icons
/Backgrounds
Project-Based Organization: Create top-level folders for different projects, portal areas, or functional components with nested subfolders for asset types within each project. Project-based organization keeps related resources together regardless of type.
/Root
/Partner-Portal
/JavaScript
/CSS
/Images
/Customer-Portal
/JavaScript
/CSS
/Images
/Admin-Dashboard
/JavaScript
/CSS
/Images
Hybrid Organization: Combine type-based and project-based approaches by creating top-level folders for asset types with nested subfolders for projects or features within each type. Hybrid approaches balance type-based navigation with project-based grouping.
/Root
/JavaScript
/Partner-Portal
/Customer-Portal
/Shared
/CSS
/Partner-Portal
/Customer-Portal
/Shared
/Images
/Partner-Portal
/Customer-Portal
/Shared
Naming Conventions
Descriptive Names: Use clear, descriptive names that indicate asset purpose, functionality, or content. Avoid generic names like "script1.js" or "style.css" in favor of specific names like "form-validation.js" or "partner-dashboard.css."
Consistent Patterns: Establish naming patterns and apply them consistently across all assets. Consistency enables predictable resource location and reduces time spent searching for specific files.
Version Indicators: When maintaining multiple versions of assets, include version numbers in filenames (e.g., jquery-3.6.0.min.js, bootstrap-5.1.3.min.css) to clearly identify which version is in use and support controlled version upgrades.
Minification Indicators: Use standard conventions to indicate minified files by including .min before the file extension (e.g., custom-scripts.min.js, styles.min.css). Clear minification indication helps distinguish between development and production versions.
Environment Indicators: For assets that differ between environments, include environment indicators in names (e.g., config-dev.js, config-prod.js) to prevent accidentally using incorrect versions in specific environments.
Documentation and Comments
README Files: Consider uploading README or documentation files within folders explaining folder contents, organization principles, asset purposes, or usage instructions. Documentation reduces confusion and onboarding time for new developers.
Asset Purpose Documentation: Maintain external documentation describing the purpose and usage of major assets particularly complex JavaScript libraries, specialized CSS frameworks, or critical image resources that may not be self-documenting.
Dependency Documentation: Document dependencies between assets such as CSS files requiring specific JavaScript libraries or scripts depending on particular stylesheets. Dependency documentation prevents incomplete asset references and missing functionality.
Asset Optimization
JavaScript Optimization
Minification: Minify JavaScript files to reduce file size by removing whitespace, comments, and unnecessary characters while preserving functionality. Minified files load faster and consume less bandwidth.
Concatenation: Combine multiple related JavaScript files into single files to reduce the number of HTTP requests required to load resources. Fewer requests improve page load performance particularly on high-latency connections.
Library Selection: Choose JavaScript libraries carefully balancing functionality against file size. Use lightweight alternatives when possible and avoid including entire libraries when only specific features are needed.
Code Splitting: For large applications, implement code splitting to load only necessary JavaScript for initial page rendering while deferring additional functionality loading until needed.
CSS Optimization
Minification: Minify CSS files to reduce file size by removing whitespace, comments, and unnecessary declarations. Minified stylesheets load faster and reduce bandwidth consumption.
Consolidation: Combine related CSS files into single stylesheets to reduce HTTP requests. Consolidated stylesheets improve initial page rendering times compared to loading multiple separate files.
Unused Rule Removal: Review CSS files periodically to identify and remove unused rules that no longer apply to active pages. Removing unused rules reduces file size and improves stylesheet maintainability.
Responsive Optimization: Use media queries appropriately to load device-specific styles without applying unnecessary rules on all devices. Responsive optimization ensures efficient styling across device types.
Image Optimization
Format Selection: Choose appropriate image formats based on content characteristics using JPEG for photographs and complex images, PNG for images requiring transparency or simple graphics with few colors, SVG for icons and simple graphics that scale, and WebP for modern browsers supporting advanced compression.
Compression: Compress images appropriately balancing visual quality against file size. Use lossy compression for photographs where minor quality reduction is acceptable and lossless compression for graphics where exact reproduction is required.
Dimension Optimization: Resize images to appropriate dimensions for their display context. Avoid uploading large images that will be displayed at small sizes, as browsers still download full images regardless of display dimensions.
Responsive Images: Implement responsive image techniques providing different image sizes for different device types and screen resolutions. Responsive images ensure optimal quality and performance across device capabilities.
Lazy Loading: Implement lazy loading for images not immediately visible on page load. Lazy loading defers image downloads until users scroll to image locations, improving initial page load times.
Reference Management
Consistent Path Usage
When referencing static assets in code, use consistent path formats across all Active Pages and Templates to enable predictable reference patterns and simplify maintenance.
Absolute Paths: Static asset references typically use absolute paths from the portal root (e.g., /staticassets/folder/file.js) ensuring correct resolution regardless of the requesting page's location in the URL structure.
Path Verification: Verify asset paths in browser developer tools if resources fail to load. Check for path typos, incorrect folder references, or case-sensitivity issues that prevent successful resource loading.
Central Asset References
Consider creating centralized reference pages or templates that include common static assets used across multiple pages. Other pages can then reference the centralized template ensuring consistent asset loading and enabling central management of common resources.
Master Template Pattern: Create master templates that include common JavaScript libraries, base stylesheets, and standard images. Individual pages reference the master template inheriting all standard asset references automatically.
Maintenance Benefits: Centralized references enable updating asset versions, adding new standard assets, or modifying loading patterns in a single location with changes automatically affecting all pages using the centralized reference.
Asset Version Management
Controlled Updates: When updating static assets with new versions, consider the impact on all pages using those assets. Test thoroughly before replacing production assets to ensure compatibility and expected functionality.
Version Coexistence: During transition periods, maintain multiple versions with distinct names (e.g., library-v1.js, library-v2.js) enabling gradual migration of pages to new versions without disrupting pages not yet updated.
Cache Management: Be aware of browser caching behavior when updating static assets. Browsers may cache old versions requiring cache clearing or cache-busting techniques to ensure new versions are loaded.
Troubleshooting and Common Issues
Resource Loading Failures
Path Verification: When assets fail to load, verify that references use correct paths including proper folder hierarchy, correct filename including extension, appropriate case-sensitivity, and valid path format.
File Existence: Confirm that referenced assets actually exist in the Static Assets section at the specified location. Deleted, renamed, or moved assets cause loading failures for pages still referencing old locations.
Browser Developer Tools: Use browser developer tools' Network tab to identify failed resource requests. Network errors indicate specific files failing to load and provide information about request URLs, response codes, and error messages.
Performance Issues
Large File Sizes: Identify excessively large static assets causing slow page loads. Review file sizes in the Static Assets section and optimize large files through compression, minification, or dimension reduction.
Excessive Requests: Count the number of separate static asset requests required to render pages. High request counts impact performance particularly on high-latency connections. Consolidate resources when possible to reduce request quantity.
Loading Priorities: Consider loading priorities for assets using async and defer attributes for JavaScript, preload hints for critical resources, and deferred loading for non-critical assets. Optimized loading priorities improve perceived performance.
Organization Challenges
Lost Resources: If assets are difficult to locate within disorganized folder structures, implement organizational improvements including logical folder hierarchies, consistent naming conventions, and documentation of organization principles.
Duplicate Assets: Identify and eliminate duplicate copies of assets stored in multiple locations. Duplicates waste storage space, complicate version management, and increase confusion about which version should be used.
Unused Assets: Periodically review Static Assets to identify resources no longer referenced by any active pages. Remove unused assets to reduce clutter and simplify resource management.
Jump to IDE Checklist
<< Working with Triggers | Using the Entity Browser >>