Troubleshooting Common Issues with Virto SharePoint Custom Mask Field Web PartThe Virto SharePoint Custom Mask Field Web Part is a handy tool for applying input masks to SharePoint fields and improving data consistency. However, like any extension, it can run into issues that disrupt forms, validation, or rendering. This article walks through common problems, diagnostic steps, and practical fixes so you can resolve issues quickly and reliably.
Quick checklist before troubleshooting
- Confirm product version compatibility: ensure the Virto Web Part version supports your SharePoint version (Online, 2019, 2016, 2013).
- Clear browser cache and test in an incognito/private window or a different browser to rule out client-side caching.
- Check user permissions: the user must have appropriate permissions to edit the list/form where the mask is applied.
- Verify installation: make sure the solution was deployed successfully and the Web Part appears in the Web Part gallery or app catalog.
- Inspect console and network: open browser developer tools (Console & Network tabs) for script errors or blocked resources.
Issue 1 — Mask not applying on the form
Symptoms: Field displays as a regular text box; typing does not follow the mask; no placeholder or formatting appears.
Possible causes and fixes:
- Missing or mismatched field mapping: confirm that the Web Part is configured to target the correct field internal name (not the display name). Use list settings to confirm the internal name.
- Script load failure: open browser console for errors referencing Virto scripts or jQuery. If scripts fail to load, ensure web part files are deployed to the correct library and paths match configuration.
- Conflicting JavaScript/CSS: other custom scripts or third-party add-ins can override behaviors. Temporarily disable other customizations (or test on a clean page) to isolate conflicts.
- Modern vs classic pages mismatch: some Virto components are built for classic pages. Verify the Web Part supports the page experience you’re using (SharePoint Online modern pages require SPFx-compatible components).
- Field type unsupported: confirm the target field type is supported by the mask (single line of text, not multi-line or certain managed metadata fields).
Issue 2 — Mask applied but validation not enforced
Symptoms: Mask displays and formats input, but form allows submission with invalid or incomplete values.
Possible causes and fixes:
- Client-side vs server-side validation: Virto masking often provides client-side enforcement. Ensure any required server-side validation or SharePoint column validation is configured if you need stronger enforcement.
- Required field vs mask settings: check whether the mask settings include “required” or “allow incomplete” options. Toggle the relevant settings to force completion.
- Save via custom script or API: if records are saved programmatically (REST/CSOM), client-side mask validation might be bypassed. Add server-side checks or validate before submit in custom scripts.
- Event receiver or flow interference: automations that process submissions might alter or accept incomplete values. Review Power Automate flows, workflows, or event receivers that run on item creation/update.
Issue 3 — Placeholder or format looks wrong (locale/formatting issues)
Symptoms: Mask placeholder characters, date or number formats, or decimal separators differ from expected locale.
Possible causes and fixes:
- Browser or user regional settings: ensure user profile or browser locale matches the intended mask format. Date and decimal separators are often locale-dependent.
- Web Part configuration: some masks allow defining the placeholder and characters explicitly—adjust these to match local conventions (e.g., using comma vs dot for decimals).
- SharePoint regional settings: site collection regional settings can affect date/time rendering—verify site settings under Site Settings → Regional Settings.
- Script library version mismatch: older masking libraries may not support certain internationalization features. Update to a version that supports your locale.
Issue 4 — Performance issues or slow page load
Symptoms: Form page loads slowly, or the web part causes a delay when many masked fields exist.
Possible causes and fixes:
- Large number of scripted web parts: each mask instance may load scripts and initialize. Reduce the number of heavy client-side components or consolidate where possible.
- Unminified scripts or synchronous loading: ensure Virto scripts are minified and loaded asynchronously where possible. Use bundling or CDN-hosted versions if supported.
- Network latency for external resources: if scripts are loaded from remote CDNs and your environment restricts or slows those requests, host scripts locally in the SharePoint library.
- Browser memory/CPU constraints: test in different browsers and systems; older machines or browsers can struggle with many JS-driven components.
Issue 5 — Styling/CSS conflicts (mask misaligned or invisible)
Symptoms: Input mask overlay misaligned with input text, or mask characters are hidden due to CSS.
Possible causes and fixes:
- CSS specificity conflicts: custom themes or CSS may override Virto styles. Inspect the element with dev tools to find which rules override the web part. Add or adjust CSS specificity, or load Virto styles after custom styles.
- SharePoint modern theming: modern site themes may change form markup. Verify compatibility of the version of the web part with the modern theme framework, or add CSS adjustments scoped to that environment.
- Responsive layout issues: if the page layout or web part zone changes width, ensure the mask container uses flexible sizing (percentage widths) or adapt styles to prevent clipping.
Issue 6 — Accessibility or screen reader problems
Symptoms: Screen readers don’t announce the mask or input guidance; keyboard navigation is impaired.
Possible causes and fixes:
- Missing ARIA attributes: ensure the web part outputs appropriate aria-label, aria-describedby, and role attributes for assistive technologies.
- Focus management: confirm the input receives focus naturally and that mask auto-formatting doesn’t break typing or cursor placement. If it does, check for options to disable aggressive formatting on keypress and instead format on blur.
- Provide alternative hints: add visible helper text or use native SharePoint field descriptions which are typically announced by screen readers.
Issue 7 — Errors after SharePoint or browser updates
Symptoms: Previously working masks break after updating SharePoint, installing a cumulative update, or after browser updates.
Possible causes and fixes:
- API or DOM changes: SharePoint updates can alter form markup or client APIs. Check Virto release notes for supported versions and update the Web Part to a compatible build.
- Deprecated dependencies: third-party libraries (like older jQuery versions) may be incompatible with updated browsers. Upgrade libraries bundled with the web part.
- Re-deploy or re-register web part: sometimes the solution’s references require re-deployment to the app catalog or reconfiguration after major platform changes.
Diagnostic steps and tools
- Browser developer tools: Console for JS errors, Network for blocked or 404 resources, Elements to inspect DOM and CSS rules.
- Fiddler or browser network capture: to detect blocked endpoints, slow resources, or incorrect paths.
- ULS logs and SharePoint logs: for server-side errors when deployment or rendering fails on the server.
- Test site/page: reproduce the issue on a clean site collection or a development tenant to isolate environmental factors.
- Error reproduction matrix: document browser, OS, user permission, page type (classic/modern), Virto version, target field type—this helps support and vendor troubleshooting.
When to involve Virto support
- Install/deployment failures where the solution package returns errors during deployment.
- Licensing or activation issues that prevent full functionality.
- Bugs that persist after updating to the latest supported Virto version and after eliminating environmental conflicts.
Provide Virto support with: SharePoint version, Virto Web Part version, exact steps to reproduce, browser console logs, screenshots, and a minimal reproduction page if possible.
Preventative best practices
- Keep Virto Web Parts and dependencies patched and aligned with your SharePoint version.
- Standardize on supported browsers and document regional/locale expectations.
- Limit custom front-end scripts on forms or namespace them to avoid collisions.
- Use feature flags or staged rollouts when updating web parts to catch issues early.
- Add server-side validation or list-level column validation to prevent data integrity issues if client-side masks are bypassed.
If you want, I can:
- Create a short troubleshooting checklist you can paste into a runbook.
- Analyze a specific console error or log snippet if you paste it here.
Leave a Reply