Visualforce Fundamentals

Visualforce Fundamentals

This skill activates when designing, building, or debugging Visualforce pages and their Apex controllers on the Salesforce platform. It covers controller architecture, view state optimization, security hardening (CSRF, SOQL injection, FLS/CRUD), PDF rendering, and Lightning Experience compatibility.

Before Starting

Gather this context before working on anything in this domain:

• Page purpose: Is this a data-entry form, a read-only display, a PDF output, or an email template preview?
• Controller type needed: Does the page operate on a single record (standard or custom controller), a list (standard list controller), or custom business logic (custom controller or extension)?
• Lightning Experience context: Will this page appear in LEX as a tab, record action, or override? If yes, it will run inside an iframe — classic JavaScript DOM assumptions break.
• Security context: Is this accessible to unauthenticated users, Experience Cloud guests, or internal employees? Guest users get no implicit record access.
• View state budget: Complex pages easily exceed the 170 KB limit. Identify large collections, binary fields, or render-dependent state early.

Core Concepts

Concept 1: Controller Types

Visualforce offers three controller patterns. Choosing the wrong one forces workarounds later.

Extensions complement a standard controller and inherit its record context automatically. A full custom controller owns all data access and must replicate standard-controller FLS enforcement explicitly.

Concept 2: View State

Every Visualforce page that uses <apex:form> carries a hidden __VIEWSTATE field on every postback. This field is encrypted and contains the serialized state of all non-transient, non-static instance variables in the controller and its extensions.

Key limits (from Salesforce Limits Quick Reference):

• Maximum view state size: 170 KB per page request. Exceeding this throws a ViewStateException and the page stops working.
• View state is round-tripped on every postback, adding latency proportional to payload size.

To control view state:

• Mark display-only collections (List<Account>, List<SelectOption>) as transient — they are rebuilt on the next request anyway.
• Restrict SOQL field lists to only fields the page actually renders.
• Use <apex:actionRegion> to limit which components participate in a postback.
• Consider <apex:remoteAction> or JavaScript remoting to avoid view state entirely for read-heavy operations.

Concept 3: Expression Language and Component Model

Visualforce uses {! } expression language to bind controller data to page markup. The approximately 150 built-in apex:* components (input, output, form, datatable, pageBlock, etc.) handle HTML rendering, state management, and action dispatch.

Important behaviors:

• {!fieldName} on an <apex:inputField> bound to the standard controller automatically respects the field's FLS for the running user.
• Custom controller properties accessed via {!myProperty} bypass FLS — the controller author is responsible for enforcement.
• The rendered attribute is evaluated server-side at render time; a component with rendered="false" is not sent to the browser at all.
• action attributes on <apex:commandButton> and <apex:commandLink> must return null or a PageReference — void methods cause a page reload to the current URL.

Concept 4: Lightning Experience Compatibility

Visualforce pages in Lightning Experience load inside an iframe with a separate domain. This means:

• window.parent access is blocked by the browser's same-origin policy.
• Classic JavaScript that modifies window.location or parent.document does not work.
• Salesforce provides sforce.one.* JavaScript APIs for LEX navigation from within VF iframes.
• CSS and SLDS styling must be added explicitly — Classic styles do not apply inside the VF iframe.

Common Patterns

Pattern 1: Custom Controller with FLS Enforcement

When to use: You need custom business logic and SOQL beyond what the standard controller provides.

How it works: Use WITH USER_MODE on SOQL queries (available Summer '23+) to enforce FLS and CRUD at the database level automatically. For DML, use Database.insert(records, AccessLevel.USER_MODE).

Why not the alternative: Omitting FLS enforcement in a custom controller is a security-review failure and exposes data to users who should not see it. The standard controller enforces FLS on bound fields automatically — custom controllers do not inherit this.

Pattern 2: Transient Variables for Large Collections

When to use: Any controller property that is a list used only for display (not submitted back to the server).

How it works: Declare the variable transient in Apex. The value is recomputed each time the page loads or re-renders via a getter method, and is never serialized into view state.

Why not the alternative: A non-transient List<SObject> with 200 records can easily consume 50–80 KB of view state alone. On complex pages with multiple lists this rapidly exceeds the 170 KB limit and produces ViewStateException errors in production.

Pattern 3: PDF Rendering

When to use: You need to produce a formatted PDF document (invoices, contracts, reports) from Salesforce data.

How it works: Add renderAs="pdf" to the <apex:page> tag. Salesforce uses the Flying Saucer library to convert the HTML output to PDF. Use inline CSS for layout — external stylesheets must be hosted at a public URL and are often unreliable. Use <apex:stylesheet> only for static resources.

Why not the alternative: Trying to use JavaScript PDF libraries in a VF page does not work because JS runs after the server renders the page — renderAs="pdf" bypasses JavaScript entirely.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Identify the controller type — Confirm whether the page is single-record (standard controller), list-based (standard list controller), or custom logic (custom controller or extension). Choose the simplest option that meets the requirements.
2. Audit SOQL in the controller — Every query must use bind variables (not string concatenation). For custom controllers, add WITH USER_MODE to enforce FLS automatically, or call Schema.sObjectType.Account.fields.Name.isAccessible() for field-by-field checks.
3. Audit view state — Identify every non-transient collection or object property in the controller. Mark display-only properties transient. Limit SOQL field lists to only what the page renders.
4. Harden against CSRF — State-changing actions (DML, delete) must be triggered via POST (use <apex:commandButton> inside <apex:form>). Never invoke DML from a GET-accessible method or URL parameter action.
5. Test in Lightning Experience — Load the page inside LEX and verify navigation, CSS rendering, and any JavaScript calls. Replace window.parent DOM access with sforce.one.* API calls.
6. Validate with a low-privilege user — Run the page as a user without admin privileges. Confirm that hidden fields are not exposed via the controller and that SOQL results respect the user's record access.
7. Run the checker script — Execute python3 scripts/check_visualforce.py --manifest-dir <metadata-path> to catch common issues automatically before deployment.

Review Checklist

Run through these before marking work in this area complete:

• Controller SOQL uses bind variables — no string concatenation of user-controlled values
• Custom controller enforces FLS/CRUD via WITH USER_MODE or explicit Schema checks
• Display-only collections and properties are marked transient in Apex
• State-changing actions are POST-only (inside <apex:form> with <apex:commandButton>)
• Page tested in Lightning Experience iframe — no broken JS, navigation uses sforce.one.*
• Tested with a low-privilege user to confirm data is not over-exposed
• View state size verified under 170 KB (check View State Inspector in Developer Console)

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. View state persists across partial postbacks — <apex:actionRegion> limits which components are re-rendered, but the entire controller state is still serialized. A large non-transient property in a component outside the region still consumes view state.
2. Standard controller FLS applies only to bound fields — Fields accessed via {!account.Name} on a standard controller enforce FLS. Fields read via a custom getter that queries Account.Name directly do NOT automatically enforce FLS — the Apex author must check.
3. renderAs="pdf" ignores JavaScript entirely — The PDF rendering engine (Flying Saucer) does not execute JS. Pages relying on JS for layout or data loading produce blank or broken PDFs.
4. VF iframes in LEX have a different origin — Salesforce serves VF pages from a visualforce.com subdomain, separate from the main salesforce.com Lightning host. Cross-origin restrictions apply; window.parent.location access will throw a security error.
5. <apex:inputField> on a formula field causes a runtime error — Formula fields are read-only at the database level. Binding them to <apex:inputField> produces a DML exception on save, not a compile-time error.
6. Transient variables are null on initial page load — The first render always reconstructs transient values via their getter. If the getter relies on view-state variables not yet populated (e.g., a record ID passed via URL), initialize defensively with null checks.
7. Page actions on GET are CSRF-vulnerable — If a page's action attribute on <apex:page> triggers DML (e.g., action="{!doSomething}"), a crafted URL can trigger that DML without a form submission. Reserve DML for form-submitted actions only.

Output Artifacts

Related Skills

• apex/soql-security — SOQL injection and FLS/CRUD enforcement patterns that apply directly to Visualforce custom controllers
• apex/governor-limits — Bulkification and query limits for controller queries that execute on page load or postback
• apex/continuation-callouts — Long-running HTTP callouts from Visualforce action methods using the Continuation pattern