Crear y utilizar controladores personalizados

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

Explicar qué es un controlador personalizado y describir sus atributos clave.
Crear una clase de controlador personalizado.
Utilizar un controlador personalizado en una página de Visualforce.

Nota

El reto práctico para esta insignia está localizado al japonés, español (LATAM) y portugués (Brasil). Para cambiar el idioma de su Trailhead Playground, siga estas instrucciones. Puede que la localización esté desactualizada. Si no aprueba el reto con las instrucciones localizadas, cambie el idioma a inglés y la configuración local a Estados Unidos, y vuelva a intentarlo.

Consulte la insignia Trailhead en su idioma para aprender a aprovechar la experiencia traducida de Trailhead.

Introducción a controladores personalizados

Los controladores personalizados contienen lógica personalizada y manipulación de datos que puede utilizar una página de Visualforce. Por ejemplo, un controlador personalizado puede recuperar una lista de elementos para mostrar, realizar una llamada a un servicio Web externo, validar e insertar datos y mucho más; y todas estas operaciones estarán disponibles en la página de Visualforce para utilizarlas como un controlador.

En otra ubicación se describe cómo admite Visualforce el patrón de diseño Modelo–Vista–Controlador (MVC) para la creación de aplicaciones Web. Los controladores recuperan habitualmente los datos para mostrar en una página de Visualforce y contienen códigos que se ejecutan en respuesta a acciones de página, como un botón en el que se hace clic. Cuando utiliza el controlador estándar, se le proporciona una funcionalidad considerable o estándar mediante la plataforma.

Pero un tamaño no es válido para todos y no todas las aplicaciones Web son estándar. Cuando desea sustituir una función existente, personalice la navegación a través de una aplicación, utilice llamadas o servicios Web o si desea un mayor control de cómo se accede a la información para su página, Visualforce le permite tomar las riendas. Puede escribir un controlador personalizado utilizando Apex y controlar la lógica de su aplicación de comienzo a fin.

Crear una página de Visualforce que utiliza un controlador personalizado

Agregue un controlador personalizado a una página de Visualforce haciendo referencia al nombre de la clase del controlador en el atributo <apex:page> controller.

Cuando su página utiliza un controlador personalizado, no puede utilizar un controlador estándar. Las páginas utilizan un atributo diferente para establecer el controlador personalizado.

Abra Developer Console y haga clic en File (Archivo) | New (Nuevo) | Visualforce Page (Página de Visualforce) para crear una nueva página de Visualforce. Ingrese ContactsListWithController para el nombre de página.

En el editor, sustituya cualquier marca con lo siguiente.

<apex:page controller="ContactsListWithController">
    <apex:form>
        <apex:pageBlock title="Contacts List" id="contacts_list">
            <!-- Contacts List goes here -->
        </apex:pageBlock>
    </apex:form>
</apex:page>

Cuando intente guardar esta página, obtendrá un error, porque ContactsListWithController ya no existe. No se preocupe, solucionaremos esto después.

Crear una clase de Apex de controlador personalizado

Un controlador personalizado es simplemente una clase de Apex, que redacta por sí mismo con Develover Console.

Existen muchas clases de utilidad y sistema para ayudarle a redactar lógicas de controlador personalizado, pero el único requisito para que se utilice una clase como un controlador personalizado es que exista.

Abra Developer Console y haga clic en File (Archivo) | New (Nuevo) | Apex Class (Clase de Apex) para crear una nueva clase de Apex. Ingrese ContactsListWithController para el nombre de la clase.

En el editor, sustituya cualquier código con lo siguiente.

public class ContactsListWithController {
// Controller code goes here
}

Al igual que con páginas de Visualforce, debe guardar sus cambios en Apex cuando lo cambie. No es mucho y no hace nada aún, pero hace que desaparezca el error de la página de Visualforce. Entonces...

Vuelva a cambiar a la página de Visualforce y guárdela de nuevo. El mensaje de error debe desaparecer y la página se guarda correctamente.
Haga clic en Preview (Vista previa) para abrir una vista previa de su página que podrá ver mientras realiza los cambios. Una nueva ventana se debe abrir, mostrando los elementos de barra lateral y encabezado de la página estándar de Salesforce, pero aún no el contenido.

A primera vista, estos dos nuevos elementos que creó no parecen muy interesantes. Aunque sean en un 90% código de marcadores, los dos elementos, página de Visualforce y controlador de Apex, están vinculados entre sí. En cuanto agrega algunos códigos más al controlador, su página podrá utilizarlo.

Más allá de los fundamentos

Es posible que haya observado que esta clase de controlador personalizado no se hereda de otra clase ni implementa una interfaz que promete ajustarse a los requisitos de un controlador de Visualforce. Ni los controladores complejos hacen esas cosas, porque no hay ninguna clase de la cual heredar o interfaz que implementar. Esto le deja la libertad de crear sus propias clases e interfaces cuando aumente su experiencia con Apex.

Agregar un método para recuperar registros

Cree un método de obtención que ejecuta una consulta SOQL que devuelve registros que desea mostrar en su página.

El objetivo principal de la mayoría de los controladores es recuperar datos para mostrar o gestionar actualizaciones en datos. En este controlador sencillo, todo lo que necesita hacer es ejecutar una consulta SOQL básica que busca registros de contacto y luego convierte en disponibles esos registros en la página de Visualforce.

En la clase ContactsListWithController, sustituya la línea de comentario // Controller code goes here por el siguiente código.
```
private String sortOrder = 'LastName';
public List<Contact> getContacts() {
    List<Contact> results = Database.query(
        'SELECT Id, FirstName, LastName, Title, Email ' +
        'FROM Contact ' +
        'ORDER BY ' + sortOrder + ' ASC ' +
        'LIMIT 10'
    );
    return results;
}
```
Este código agrega una variable de miembro privada, una cadena denominada sortOrder y un método público, getContacts(). sortOrder es mucho más fácil de comprender, ya que es el nombre del campo por el que se ordenan los contactos. getContacts() también es bastante sencillo, pero si no conoce Apex, puede ser difícil de analizar a primera vista. El efecto del método es realizar una consulta SOQL para obtener una lista de registros de contacto y luego devolver esa lista de contactos al método emisor. ¿Quién será el emisor? La página de Visualforce, claro.

En la página ContactsListWithController, sustituya la línea de comentarios  por la siguiente marca.

<!-- Contacts List -->
<apex:pageBlockTable value="{! contacts }" var="ct">
    <apex:column value="{! ct.FirstName }"/>
    <apex:column value="{! ct.LastName }"/>
    <apex:column value="{! ct.Title }"/>
    <apex:column value="{! ct.Email }"/>
</apex:pageBlockTable>

Cuando guarda esta página, debe ver una ficha de información de contacto que le resulta familiar. Una lista de contactos respaldada por un controlador personalizado

Una lista de contactos respaldada por un controlador personalizado

La marca para la página ContactsListWithController debe resultar familiar. Excepto para el atributo controller de la etiqueta <apex:page>, es casi el mismo código que debe utilizar para crear la página con el controlador estándar.

La diferencia es lo que sucede cuando se evalúa la expresión {!contacts }. En esta página, Visualforce traduce esa expresión en una llamada al método getContacts() de su controlador. Ese método devuelve una lista de registros de contacto, que es exactamente lo que espera <apex:pageBlockTable>.

El método getContacts() se denomina un método de obtención y es un patrón general, donde {!someExpression } en su marcado de Visualforce se conecta automáticamente con un método denominado getSomeExpression() en su controlador. Esta es la forma más sencilla para que su página obtenga el acceso a datos que necesita mostrar.

Agregar un nuevo método de acción

Cree métodos de acción en su controlador personalizado para responder a entradas de usuario en la página

Mostrar datos está bien, pero responder a acciones de usuarios es esencial en cualquier aplicación Web. Con un controlador personalizado, puede crear tantas acciones personalizadas como desee admitir en una página, redactando métodos de acción para responder a la actividad de usuarios.

En la clase ContactsListWithController, debajo del método getContacts(), agregue los dos métodos siguientes.
```
public void sortByLastName() {
    this.sortOrder = 'LastName';
}
public void sortByFirstName() {
    this.sortOrder = 'FirstName';
}
```
Estos dos métodos cambian el valor de la variable privada sortOrder. sortOrder se utiliza en la consulta SOQL que recupera los contactos, y el cambio sortOrder cambiará el orden de los resultados.

En la página ContactsListWithController, sustituya las dos etiquetas <apex:column> para ct.FirstName y ct.LastName con la siguiente marca.

<apex:column value="{! ct.FirstName }">
    <apex:facet name="header">
        <apex:commandLink action="{! sortByFirstName }"
            reRender="contacts_list">First Name
        </apex:commandLink>
    </apex:facet>
</apex:column>
<apex:column value="{! ct.LastName }">
    <apex:facet name="header">
        <apex:commandLink action="{! sortByLastName }"
            reRender="contacts_list">Last Name
        </apex:commandLink>
    </apex:facet>
</apex:column>

Aunque el aspecto visual permanece igual, si hace clic en los encabezados de columna Nombre y Apellidos ahora, cambiará el orden de clasificación de la lista de contactos. ¡Excelente!

El nuevo marcado agrega dos componentes anidados a cada uno de los componentes <apex:column>. <apex:column> siempre tiene un encabezado de texto sin formato, pero deseamos convertir el encabezado en activable. <apex:facet> nos permite establecer los contenidos del encabezado de columna como queramos. Y lo que queremos es un vínculo que llama el método de acción correcto. El vínculo se crea utilizando el componente <apex:commandLink>, con el atributo action establecido como una expresión que hace referencia al método de acción en nuestro controlador. (Recuerde que los métodos de acción, a diferencia de los métodos de obtención, se denominan del mismo modo que la expresión que hace referencia a ellos.)

Cuando se hace clic en el vínculo, activa el método de acción en el controlador. El método de acción cambia el orden de clasificación de la variable privada y luego se vuelve a representar la tabla. Cuando se vuelve a representar la tabla, se vuelve a evaluar {!contacts }, que a su vez vuelve a ejecutar la consulta con el orden de clasificación que se acaba de establecer. El resultado final es que se vuelve a ordenar la tabla en el orden solicitado por el clic del usuario.

Más allá de los fundamentos

El texto del encabezado para las columnas nombre y apellido está codificado en esta marca. ¿Qué sucede si no todos sus usuarios utilizan el inglés? La interfaz de usuario estándar de Salesforce tiene versiones traducidas de los nombres de campo para todos los objetos estándar y puede proporcionar sus propias traducciones para objetos personalizados. ¿Cómo accederá a esto? En lugar del texto sin formato, pruebe esta marca: <apex:outputText value="{!$ObjectType.Contact.Fields.FirstName.Label }"/>. Es la forma correcta de hacer referencia a la etiqueta de un campo, incluso si su organización utiliza el mismo idioma, porque se actualizará automáticamente si se cambia el nombre del campo alguna vez.

Más información...

Los controladores personalizados y el lenguaje de Apex le permiten muchas más cosas de las que piensa en sus páginas de Visualforce.

Los métodos de obtención extraen datos de su controlador en la página. Existen métodos más apropiados que le permiten enviar valores desde la copia de seguridad de la página a su controlador. Al igual que los métodos de obtención, el prefijo de los reguladores es “set”, y aparte de eso, son solo métodos que toman un argumento.

Una alternativa a los métodos de obtención y reguladores es utilizar propiedades de Apex. Las propiedades son como una combinación de una variable con métodos de obtención y reguladores con una sintaxis que los agrupa juntos de forma más clara. Una propiedad sencilla que hace referencia a un objeto personalizada se podría declarar así.

public MyObject__c myVariable { get; set; }

Las propiedades pueden ser públicas o privadas y pueden ser de solo lectura o incluso de solo escritura, omitiendo get o set. Puede crear implementaciones para los métodos de obtención o regulación cuando desea realizar lógicas adicionales aparte de simplemente guardar o recuperar un valor.

Las propiedades son una función general de Apex, no especifica de Visualforce. Apex es un lenguaje de programación completo y además de ser el socio natural para la creación de páginas complejas de Visualforce, se utiliza en muchos más contextos de desarrollo de la Plataforma Lightning. Consulte los temas de Apex en otra parte aquí y los recursos al final de esta página para ver más formas de aprender a utilizar Apex de forma exhaustiva.

El ciclo de vida de una respuesta y solicitud de Visualforce puede parece complejo inicialmente. En concreto, es importante comprender que no hay un orden especifico en el que se llaman los métodos de obtención y reguladores (o propiedades, si los utiliza), de modo que no debe introducir dependencias de orden de ejecución entre ellos. Encontrará muchos más detalles disponibles en las secciones relevantes de la Guía del desarrollador de Visualforce, en concreto el capítulo Controladores personalizados y extensiones de controlador.

Recursos