Adding Fields to the Person Form - ES

Este tutorial aplica para la versión 4.0 de iHRIS Manage. Para ver el tutorial de versiones diferentes del software vea lo siguiente:

For other versions, see Adding Fields to the Person Form (versions) .

En este tutorial, veremos cómo agregar campos nuevos al formulario person a iHRIS Manage. Agregaremos dos campos, uno llamado "Favorite Color" que será una lista desplegable, y uno será "Favorite Animal" que será un campo para texto. Hay muchas formas de pelar a mi animal favorito, un gato. Igualmente, hay muchas formas de agregar un campo a un formulario. Para mantener de mejor manera el código y las personalizaciones que estamos haciendo, lo haremos al crear un sub-módulo Demo_ManagePerson del sitio-módulo Demo que contiene todos los cuatro cambios. Para ver una personalización similar, vaya a personalizaciones [CSSC] y en especial bajo modules/Person.

Advertencia: En este tutorial modificaremos el sitio Demo de ihris-manage directamente. Este no es el método recomendado para hacer este en un ambiente productivo. Por favor lea Creating a Site para detales sobre cómo crear un sitio.

Pre-Requisitos

Es recomendado leer los siguientes artículos y referirse a ellos conforme va leyendo este tutorial:

• Module Structure
• Configuration (Magic) Data
• Forms and Fields

Directorios

Puede que desee ver Customizing iHRIS Manage para generalidades de algunos de los directorios relevantes par alas personalizaciones. Nosotros haremos nuestras personalizaciones al sito Demo de iHRIS Manage. En unix puede que trabaje bajo:

<Base Dir>

/var/lib/iHRIS

<Site Dir>

/var/lib/iHRIS/4.0/ihris-manages/sites/Demo

Si tiene instalado Windows iHRIS Manage trabajará bajo los directorios:

<Base Dir>

C:\Program Files\ihris-suite

<Site Dir>

C:\Program Files\ihris-suite\sites\ihris-manage

Crear un Módulo Nuevo

Observando:

• <SITE DIR>/iHRIS-Manage-Demo.xml for Linux
• <SITE DIR>/iHRIS-Manage-Demo.xml for Windows

Vemos que podemos poner sub-módulos en los módulos del subdirectorio del directorio el sitio, que ya existe. Así que (en unix):

mkdir <SITE DIR>/modules/DemoPerson

que contiene nuestro sub-modulo DemoPerson. Luego guarde al archivo:

<SITE DIR>/modules/DemoPerson/DemoPerson.xml

Los siguientes contenidos:

<?xml version="1.0"?>       
<!DOCTYPE I2CEConfiguration SYSTEM "I2CE_Configuration.dtd">
<I2CEConfiguration name='DemoPerson'>      
 <metadata>
   <displayName>Demo Person</displayName>   
   <category>Form</category>
   <description>Sets up the Demo Person form with extra fields for favorite animals and favorite color</description>
   <version>4.0.0</version> 
   <requirement name='Person'>
     <atLeast version='4.0'/>
     <lessThan version='4.1'/>
   </requirement>
   <path name='templates'>
      <value>./templates</value>
   </path>
   <priority>300</priority>  
 </metadata>
</I2CEConfiguration>

Esto es (casi) la mínima cantidad de cosas que necesitamos hacer para crear un módulo nuevo. En este momento, no hay funcionalidad, pero ya dijimos que el módulo DemoPerson requiere el módulo Person, que incidentalmente es un sub-module de ihris-common. También fijamos la prioridad del módulo, para saber que los archivos plantilla que crearemos tomarán precedencia sobre cualquier cosa en los módulos ihris-manage o ihris-common.

Formularios y Clases de Formularios y Herencia

En realidad hay dos partes para definir un "form", un formulario y una clase del formulario. A los formularios se les refiere por sur shortname, por ejemplo person. Al segundo se le refiere por el nombre de una clase de PHP, por ejemplo, iHRIS_Person.

Todos los datos magic para formularios están bajo /modules/forms. Los datos magic definen los formularios bajo /modules/forms/forms y para las clases de formularios bajo /modules/forms/formClasses. Por ejemplo, el archivo de configuración <BASE DIR>/ihris-common/modules/Person/Person.xml define el módulo Person. Aquí verá dos nodos:

<configrationGroup name='person'>
</configurationGroup>

y

<configrationGroup name='iHRIS_Person'>
</configurationGroup>

El segundo define algunos de los campos asociados con la clase iHRIS_Person, y el primero nos dice la clase que el formulario person utiliza es iHRIS_Person.

Ahora si observamos el archivo de configuración <BASE DIR>/ihris-manage/iHRIS-Manage-Configuration.xml veremos dos cosas: que ihris-manage requiere el módulo Person, y también veremos un nodo <configurationGroup name='person'> similar. Esta vez el formulario person utiliza la clase iHRIS_ManagePerson. Ya que ihris-manage requiere Person, la clase asociada al formulario person se carga desde iHRIS-Manage-Configuration.xml y no desde Person.xml

Si observamos más allá en este archivo, veremos el nodo <configurationGroup name='iHRIS_ManagePerson'> que define la clase iHRIS_ManagePerson. Aquí verá dos cosas:

• iHRIS_ManagePerson extiende iHRIS_Person, así que tiene los mismos campos que iHRIS_Person
• iHRIS_ManagePerson agrega el campo llamado password con tipo 'STRING_PASS' pero que este campo no se guarda a la base de datos

Agregar los Campos a Datos Magic

Agregaremos los dos campos fav_color y fav_animal a la clase DemoPerson. Ya que queremos que fav_color sea una lista desplegable, también tendremos que crear un formulario llamado fav_color que contendrá los colores que queremos. Para construir estos formularios y campos, tendremos que agregar datos (magic) de configuración. Agregar a:

<SITE DIR>/modules/DemoPerson/DemoPerson.xml

Lo que sigue luego de la etiqueta </metadata> :

<configurationGroup name='DemoPerson' path='/'>
  <status>overwrite:true</status>
  <configurationGroup name='forms' path='/modules/forms/forms'>
    <configurationGroup name='fav_color'>
       <!-- define the 'fav_color' form -->
       <configuration name='class' values='single'>  
         <value>I2CE_SimpleList</value>
         <!-- fav_color uses the 'I2CE_SimpleList' form defined in i2ce/modules/Forms/modules/Lists-->
       </configuration>
       <configuration name='display' values='single'>         
         <value>Favorite Color</value>  
         <!-- the name of this form that is displayed to a user is 'Favorite Color'-->
       </configuration>
    </configurationGroup>
    <configurationGroup name='person'>
      <!-- the form 'person' is defined in ihris-common/modules/Person/Person.xml. -->
      <configuration name='class'> 
         <value>DemoPerson</value>
         <!-- Here we are changing the form class it uses to be 'DemoPerson' which is defined below -->
      </configuration>
    </configurationGroup>
  </configurationGroup>
  <configurationGroup name='formClasses' path='/modules/forms/formClasses'>
    <configurationGroup name='DemoPerson'>
       <!-- We are defining the DemoPerson class -->
       <configuration name='extends'>
          <value>iHRIS_ManagePerson</value>
           <!-- The DemoPerson class extends the 'iHRIS_ManagePerson' class defined in <BASE DIR>/iHRIS-Manage-Configuration.xml -->
       </configuration>
       <configurationGroup name='fields'>
          < !-- Under here we add in the new fields that DemoPerson has -->
          <configurationGroup name='fav_animal'>
             <!-- The data definining the 'fav_animal' field of DemoPerson -->
            <configuration name='formfield'>
              <value>STRING_LINE</value>
              <!-- Set the field to have type 'STRING_LINE' which is a single line of text e.g. an <input type='text'> in a form-->
            <configuration>
            <configuration name='headers' type='delimited' values='many'> 
              <value>default:Favorite Animal</value> 
              <!-- Set the default header for this field to be 'Favorite Animal'-->
            </configuration>
          </configurationGroup>
          <configurationGroup name='fav_color'>
            <!-- The data definining the 'fav_color' field of DemoPerson -->
            <configuration name='formfield'>
              <value>MAP</value>
              <!-- Set the field to have type MAP. By default, this field will be one of the ids of the form fav_color-->
            <configuration>
            <configuration name='headers' type='delimited' values='many'> 
              <value>default:Favorite Color</value> 
              <!-- Set the default header for this field to be 'Favorite Color'-->
            </configuration>       
         </configurationGroup>
       </configurationGroup>
    </configurationGroup>
  </configurationGroup>
</configurationGroup>

El texto color tomate son comentarios que puede omitir si desea.

El texto color verde olivo puede quitarse antes de la liberación, pero es útil para propósitos de desarrollo. Se asegura que cualquier cambio que haga al archivo de configuración sea actualizado.

Personalizar los Archivos Plantilla

En el paso anterior, habilitamos que dos campos se guardaran en la base de datos. Ahora tenemos que editar el ínter faz del usuario para que muestre los campos donde sea apropiado. Hay tres áreas que necesitamos para agregar estos campos:

• Mostrar el expediente de una persona muestra su animal y color favorito
• Editar el expediente de una persona permite actualizar el animal y color favorito
• Agregar un lugar en la página Administer Database para agregar los colores permitidos

Mostrar los Favoritos

La página titulada View Person y mencionada en el URL como view se brinda primero en el sub-módulo Person de ihris-common. Aquí, observando <BASE DIR>/ihris-common/modules/Person/Person.xml vemos que la página view carga por defecto el archivo view.html que podemos encontrar en <BASE DIR>/ihris-common/modules/Person/templates/view.html.

El módulo ihris-manage anula view.html al proveerle en <BASE DIR>/templates/view.html

Ya que el archivo view.html no es especifico al módulo DemoPerson, no es apropiado poner nuestra versión modificada en el sub-módulo DemoPerson. En lugar de eso podremos el directorio de plantillas del módulo del sitio Demo. Aquí está en comando (unix):

cp <BASE DIR>/ihris-manage/templates/view.html <SITE DIR>/templates/view.html

Para mostrar el animal y color favorito de una persona después de su nacionalidad, abra el recién creado <SITE DIR>/templates/view.html. Busque la línea:

<span type="form" name="person:nationality" showhead="default" class="even"></span>

y agregue lo siguiente unas líneas después:

<span type="form" name="person:fav_color" showhead="default" ></span>
<span type="form" name="person:fav_animal" showhead="default" class="even"></span>

Editar los Favoritos

En View Person, el primer link Update This Information nos deja cambiar la información básica de la persona como el nombre y la nacionalidad. Agregaremos los campos para cambiar su color y animal favorito en esta página. Haciendo click en el link y observando el URL, vemos que esta página se llama person.

Iniciamos observando el sub-módulo Person de ihris-common para encontrar el archivo plantilla correcto a editar. Observando <BASE DIR>/ihris-common/modules/Person/Person.xml, vemos que la página person carga el archivo plantilla html por defecto form_person.html. Este archivo se encuentra en <BASE DIR>/ihris-common/modules/Person/templates/form_person.html. No es anulado por ihris-manage.

Debido a que este archivo plantilla es especifico a una persona y no involucra ningún otro formulario, lo pondremos en nuestro modulo DemoPerson. Crearemos un sub-directorio de plantillas y copiaremos ente archivo a ese directorio. Aquí están los comandos (unix):

 mkdir <SITE DIR>/modules/DemoPerson/templates
 cp <BASE DIR>/ihris-common/modules/Person/tempaltes/form_person.html <SITE DIR>/modules/DemoPerson/templates/form_person.html

Ahora abrimos el recién creado <SITE DIR>/modules/DemoPerson/templates/form_person.html y buscamos la línea siguiente:

<span type="form" name="othername" showhead="default"></span>

y agregamos:

<span type="form" name="fav_color" showhead="default"></span>
<span type="form" name="fav_animal" showhead="default"></span>

Justo después de ella.

Agregar a las Listas de la Base de Datos

Las listas guardadas en la base de datos se controlan a través de la página llamada Administer Database y se les refiere como lists. Necesitamos agregar un link para administrar la lista de Color Favorito.

La función básica de la página list es provista por I2CE por el sub-módulo Lists del sub-módulo Forms. Aquí la página lists se maneja por la clase en <BASE DIR>/I2CE/modules/Forms/modules/Lists/lib/I2CE_PageFormLists, y vemos que se carga un archivo plantilla lists.html. El lists.html es un archivo plantilla que contiene todas las listas de la base de datos que queremos administrar. (Técnicamente, deberíamos tener un archivo <BASE DIR>/I2CE/modules/Forms/modules/Lists/templates/lists.html pero olvidamos agregarlo.)

Las páginas lists se extienden en ihris-common a través de la clase en <BASE DIR>/ihris-common/lib/iHRIS_PageFormLists. También notamos que aquí hay un archivo plantilla <BASE DIR>/ihris-common/templates/lists.html que tiene todas las listas brindadas por ihris-common.

El módulo ihris-manage anula el lists.html brindado por ihris-common al brindarle el suyo propio en <BASE DIR>/ihris-manage/tempalte/lists.html. Verá que tiene todas las listas provistas por ihris-common así como las listas nuevas provistas por ihris-manage. Este es el archive plantilla que modificaremos para nuestro sitio para agregarle la lista Color Favorito .

Ya que el archivo lists.html no es especifico al módulo DemoPerson, no es apropiado poner nuestra versión modificada en el sub-modulo DemoPerson. En lugar de eso pondremos el directorio de plantillas del módulo de sito Demo. Aquí está el comando (unix):

cp <BASE DIR>/ihris-manage/templates/lists.html <SITE DIR>/templates/lists.html

Ahora abra el archivo <SITE DIR>/templates/lists.html y agregue la línea siguiente:

<li task='can_edit_database_list_fav_color' ><a  href="lists?type=fav_color">Favorite Color</a></li>

en el bloque<ul> bajo Employee Lists.

Notará, que tenemos un atributo task en la etiqueta <li>. Un usuario con el rol Gerente de RH o Administrator puede editar cualquier lista de la base de datos. Sin embargo, para el fin de este ejemplo, agregaremos esta tarea la cual podemos asignar a un usuario con el rol Gerente de Capacitación. Hacemos esto en la siguiente sección

Crear la Plantilla Editar Color Favorito

Tenemos que crear un plantilla llamada 'view_list_fav_color.html' en nuestro directorio de plantillas que contendrá: <source lang='xml'>

Edit This Information

• Update this Information
• <a href="lists?type=emp_status">Select another Favorite Color</a>

Favorite Color

</source>

Fijando la Tarea Editar Lista de Base de Datos Color Favorito (Opcional)

En la sección anterior, utilizamos una tarea can_edit_database_list. En esta sección realizamos la tarea opcional de agregar esto a los datos de configuración.

Inserte el código siguiente en <SITE DIR>/modules/DemoPerson/DemoPerson.xml justo después de la etiqueta <status>overwrite:true</status> :

<configurationGroup name='tasks' path='/I2CE/tasks/task_description'>
   <!-- This node has all of the tasks available to the system and a description of what they are -->
   <configuration name='can_edit_database_list_fav_color'>
      <!-- This is the task that we added to edit the database list associated with the form fav_color
           The class I2CE_PageFormList checks for the existence of "can_edit_database_list_$formname" for editing the list in the action() method-->
      <value>Edit the Favorite Color list</value>
      <!-- The description of the task.  It is displayed in the task/role management page -->
   </configuration>
   <configuration name='can_view_database_list_fav_color'>
      <!-- This is the task that we added to view an existing entry in the database list associated with the form fav_color
           The class I2CE_PageViewList checks for the existence of "can_view_database_list_$formname" for editing the list in the action() method-->
      <value>View the training course status list</value>
      <!-- The description of the task.  It is displayed in the task/role management page -->
   </configuration>
</configurationGroup>
<configurationGroup name='tasks_trickle_down' path='/I2CE/tasks/task_trickle_down/' >
  <!-- This node is used to describes all the sub-tasks that are a specific task has-->
  <configuration name='can_view_database_list_fav_color' values='many'> 
    <!--If we can view the database list for 'fav_color' we want to make sure we have permission to view 
         database lists in general. 
         The 'many' attribute says to treat this like an array of values -->
    <value>can_view_database_lists</value>
  </configuration>
  <configuration name='can_edit_database_list_fav_color' values='many'> 
    <!-- If we can edit the database list 'fav_color' we need to make sure we can view it as well as edit 
         database lists in general.
         The 'many' attribute says to treat this like an array of values -->
    <value>can_view_database_list_fav_color</value>
    <value>can_edit_database_lists</value>
  </configuration>
</configurationGroup>
<configurationGroup name='role_trickle_down' path='/I2CE/tasks/role_trickle_down'>
  <!-- This node is used to describes all the tasks that are assigned to various role -->
  <configuration name='training_manager' values='many'>
    <!-- This node defines the tasks that are assigned to the 'training_manager' role.  
         The 'many' attribute says to treat this like an array of values -->  
    <status>uniquemerge:true</status>
    <!-- We want to merge the existing tasks for the training_manager role to the ones we define below.
         The existing values for 'training_manager' are defined in <BASE DIR>/ihris-common/modules/TrainingCourse/TrainingCourse.xml -->
    <value>can_edit_database_list_fav_color</value>
    <!-- Here we assign the 'can_edit_database_list_fav_color' to the 'training_manager' role -->
  </configuration>
</configurationGroup>

Habilitar el Módulo

Ahora que tenemos todo listo, solo necesitamos habilitar el módulo 'DemoPerson' en el sitio. Abra el archivo

<SITE DIR>/iHRIS-Manage-Demo.xml

y agregue lo siguiente:

<requirement name='DemoPerson'> 
 <atLeast version='4.0'>
 <lessThan version='4.1'>
</requirement>

en la <metadata> sección después del requerimiento de ihris-manage. También, asegúrese de tener: <source lang='xml'>

  <path name='modules'>
     <value>./modules</value>
  </path>

</source>

Cambiar el Encabezado de Animal Favorito

Supongamos que quiere cambiar el encabezado del campo fav_animal de " Favorite Animal " a "Favorite Mammal" Para hacer esto, necesitamos actualizar la versión del módulo así como agregar una etiqueta de <versión> en donde hemos cambiado el encabezado. Los cambios se resaltan. En la sección <metadata> tenemos:

 <metadata> 
 <displayName>Demo Person</displayName> 
 <category>Form</category> 
 <description>Sets up the Demo Person form with extra fields for favorite animals and favorite color</description>    
  <version>4.0.1</version>  
 <requirement name='Person'> 
    <atLeast version='4.0'/> 
   <lessThan version='4.1'/> 
 </requirement> 
 <path name='templates'> 
   <value>./templates</value> 
 </path> 
 <priority>300</priority> 
</metadata>

y en la definición del campo 'fav_animal' tenemos:

     <configuration name='headers' type='delimited' values='many'> 
        <version>4.0.1</version>
        <value>default:Favorite Mammal</value>              
     </configuration>

Happy Debbuging