NotasTecnicas/zonas

Hay 3 aspectos que integran las zonas.

  • El primero es la zona misma, que implica la selección de una 'entidad' (comisión, mesa) con la cual operar. Al seleccionar cualquier operación de la zona, aplicará sobre la selección actual. Por otro lado, al seleccionar otra 'entidad' se editará en la operación actual.
  • El segundo es la protección de parámetros. En g3w se protegen especialmente los parámetros que representen comisiones y mesas, por lo que toda operación perteneciente a la zona deberá poder decodificar este formato. Para un background más teórico del manejo de parámetros referirse a  Seguridad de Parámetros - Chulupí
  • Finalmente, en virtud del esquema mencionado en el punto anterior, es muy simple inspeccionar y procesar los parámetros de forma automatizada. Las zonas tienen incorporado un procesador de derechos que evalúa para cada 'entidad', si el docente actual tiene el derecho que exige la operación.

Zonas

Definicion

Las zonas se encuentran definidas en /operaciones/_comun/zonas/zona_[comision|examen].php (personalizables). Allí se define todo lo que en pantalla aparece debajo del menú y por encima del contenido propio de cada operación:

  • combo de selección de entidades: Cada entrada posee un link a la operación actual con ella como parámetro (en formato seguro). Si no tiene derechos es un link vacío. Para modificar las entidades que se muestran ver principalmente
    get_datos_navegacion() y get_descripcion_fila($fila) para la parte visual.
    
  • Tabs para las operaciones de la zona: Cada una tiene un link a las otras operaciones de la zona con la entidad actual como parámetro, con el mismas consideraciones anteriores. Para modificar las operaciones que se muestran ver principalmente
     get_operaciones_zona()
    
  • Descripción de la entidad: Un cuadro contraible con datos de la entidad seleccionada. Ver
    get_datos_detalle($transaccion, $seleccion), get_template().
    

La zona obtiene los datos de una única clase php, denominada transacción (centraliza el acceso a la bd). /modelo/transaccion/zona_[comision|examen]. Esta provee los datos del combo y la descripción de la entidad actual. El listado de entidades (el que consume get_datos_navegacion()) debe recibir una instancia de rs_consulta, necesario para codifcar los parámetros en la zona. (OBs, no puede ser un rs_arreglo ya que no está diseñado para funcionar entre operaciones).

Operaciones

Las operaciones de la zona deben agregarse a la zona (get_operaciones_zona()) y además, el controlador de la misma debe extender get_info_zona(). La misma retorna un arreglo con 2 campos 'zona' => 'comision|examen', y 'seleccion' => [arreglo-seleccion (Proximo parrafo)].

	function get_info_zona()
	{
		if (isset($this->params_comision['comision'])) { //si no esta seleccionado nada, no activo la zona
			return array('zona' => 'comision', 'seleccion' => $this->params_comision);
		}
	}

El arreglo-seleccion es un arreglo por la forma en que funciona el manejo de parámetros. El parámetro codificado se procesa, se corre la consulta que supuestamente lo generó y se busca una fila con el mismo hash (ver doc chulupi para ampliación). Los parámetros se toman de esa fila, ya que lo que se envía al usuario es solamente un hash (Coloquialmente: hago una consulta, la hasheo y se la envio al usuario, el usuario me devuelve el hash de lo que selecciona, regenero la consulta y puedo ver los parámetros que eligió -> en definitiva me paso los parámetros a través de las consultas para que no las pueda tocar el usuario).

El arreglo-selección se entregará a las operaciones de la zona get_id_fila($seleccion) para que determine que columna/s son los id de la fila (la identifican unívocamente), y get_datos_detalle($seleccion), que se la pasará a la transacción para recuperar datos de la entidad seleccionada.

Actualmente la zona_comision utiliza una columna 'id' que se define como sigue:

  id = [comision] id de comision si la comision no tiene subcomisiones
  id = [comision]_[subcomision] si tiene subcomisiones.

Es decir, todos los links a operaciones de la zona_comision deberán provenir de una rs_consulta(..) cuya consulta al catálogo incluya la columna id. De esta forma cada operación puede saber como decofificar el link. Y todas las otras operaciones sabrán como hacer un link a la nueva operación (le enviarán el parámetro id).

Para el caso de examenes se requiere solamente la columna 'llamado_mesa', tal cual se encuentra en la base de datos (sga_docentes_mesa_llamado.llamado_mesa, vw_mesas_examen.llamado_mesa).

La forma de decodificar un parámetro es mediante el helper de los controladores:

		$this->hash_comision = $this->validate_param(0, 'get', validador::TIPO_TEXTO);
		$this->params_comision = $this->decodificar_hash($this->hash_comision, 'edicion');

En el ejemplo 'edicion' es la acción para la que supuestamente se generó el link (para evitar reutilización de parámetros). Su valor por defecto es la opearción actual, pero puede especificarse otra operación ya que es común 'agarrar el parámetro de otra operación' para hacer links. Por ejemplo, en primera instancia se hace un link para la operación 'edicion'. La operación lo recibe y lo decodifica, y obtiene un $hash por un lado, y su decodificación. Con ese $hash puede hacer un link a 'guardar'

		kernel::vinculador()->crear('controlador', 'guardar', array($hash));

Para lo cual, la acción 'guardar' tendría que validar que el hash recibido fue creado para la acción editar, no para la actual. Asimismo hay casos más complejos donde puede haber varios destinos posibles (muchos accesos a una operación) para lo que se puede poner un arreglo de operaciones (array('edicion', 'guardar')) o '*' para aceptar cualquier acción (es un poco mas manipulable para un atacante).

IMPORTANTE: todos los links que se generen en la zona hacia otras acciones de la misma operación deben adaptarse a este formato codificado (para que la zona pueda en cada acción recuperar la entidad seleccionada y hacer los links). Salvo que sea un link a otra operación se utiliza la clase rs_arreglo para generarlos (en vez de rs_consulta como en la zona) ya que es un poco más eficiente.

Derechos

Dado que la zona fuerza a utilizar el esquema de parámetros codificado, es trivial aplicarle derechos. Al momento de recuperar una entidad de una fila se checkea si el docente actual tiene derechos para la operación actual. Si no las tiene, genera una excepción. Por otro lado, el vinculador al momento de generar un link se fija si el docente tiene derechos para la acción destino y si no la tiene generar un link vacío permitiendo mostrar el link/botón deshabilitado.

La definición de derechos se realiza en el ACC_docente.xml.

		<operacion id="evaluaciones" url="evaluaciones" activa="1">
			<accion id="listar_notas">
				<derecho id='evaluacion_consultar' sobre='comision'/>
			</accion> ...

Obs: es importante considerar todas las acciones de cada operación, no solo las visuales. Un ejemplo típico es editar/guardar. La acción editar permite editar, y luego se hace un post a 'guardar'. Hay que poner derechos en ambas operaciones para evitar un acceso directo a guardar.

En primer lugar debe retornarse de la transacción de la operación los datos wrappeados con alguna de las clases rs_consulta o rs_arreglo. Se debe indicar una columna que defina univocamente a la consulta, y en caso de utilizar derechos, cual es la entidad sobre la cual se aplican.

	$rs = new rs_consulta('carga_notas_cursada_comision', 'lista_comisiones_docente', $parametros);
	$rs->set_columna_id('comision');
	$rs->agregar_entidad('comision');

Desde el controlador se debe acceder de la misma manera que cualquier transacción, solo que a través de el método codificador_modelo() que realiza las configuraciones necesarias. Notar que el codificador_modelo() wrappea los resultados en un kernel\util\modelo\procesador_vista que gestiona de forma eficiente la generación de links y testeo de derechos entre otras. También implementa  ArrayAccess e Iterator por lo que puede iterar o acceder como cualquier arreglo (salvo pocas excepciones)

$comisiones = $this->codificador_modelo()->info__comisiones_docente($anio_academico, $periodo_lectivo, $actividad);
/** @var $comisiones modelo\procesador_vista */
$comisiones->link('LINK', 'notas_cursada_comision', 'edicion');
foreach ($comisiones as $fila) {
	$actividad = $fila['actividad'];
	$href= $fila['LINK']; //o '-.-' si no tiene derechos