= Caixa de Seleção Múltipla - !OptGroup =

== Plugin: wf_select_option_multiple_init ==

'''Descrição:''' Insere código que referencia arquivos de javascript responsáveis pela funcionalidade.

'''Parâmetros:''' <nenhum>

'''Exemplo:'''

{{{
{wf_select_option_multiple_init}
}}}

Observação: antes de utilizar "wf_select_option_multiple" (seja uma ou mais vezes), deve-se fazer uma '''única''' chamada ao plugin "wf_select_option_multiple_init". 

----

== Plugin: wf_select_option_multiple ==

'''Descrição:''' Este plugin insere uma ''combo box'' e um ''select box'' múltiplo que permite ao usuário cadastrar vários ítens de uma lista. A ''combo'' é utilizada para mostrar todos os ítens "cadastráveis", que podem estar em formato de lista normal, ou uma lista dividida em grupos (utilizando '''optGroup'''). Ao selecionar um item, deve-se clicar no botão "Adicionar" para que a seleção seja copiada para o ''select box'', onde se encontram os itens a serem cadastrados. Ao adicionar um elemento, ele será desabilitado na ''combo'' para que não possa ser selecionado novamente.

Para remover um ou mais itens do ''select'', basta selecioná-los e clicar no botão "Remover". Isso vai reabilitá-los na ''combo''.

'''Parâmetros:'''

  nameTop: o nome e id que a ''combo'' irá receber.

  nameBottom: o nome e id que o ''select'' irá receber.

  arrayTop: lista dos ítens a serem carregados na ''combo''.

  arrayBottom: lista dos ítens a serem carregados no ''select''.

  onChangeTop: chamada da função a ser executada no onChange da ''combo''.

  onChangeBottom: chamada da função a ser executada no onChange do ''select''.

  size: tamanho do ''select box''.

  sortEnableBottom: valor (''true'' ou ''false'') indicando se deve-se executar a ordenação do ''select box''.

  diffEnable: valor (''true'' ou ''false'') indicando se deve-se executar o diff entre a ''combo'' e o ''select box''.

  style: para definir os estilos do ''select box''.

'''Parâmetros obrigatórios:'''

  nameTop

  nameBottom

'''Valor padrão:'''

  size: 8

  style: "width:400px"

  sortEnableBottom: true

  diffEnable: true

A seguir, é apresentada a combo com uma lista dividida em grupos. Para isso, o array deve possuir o seguinte formato:

{{{
array(
    "Curitiba" => array(
                    123 => "Araucária",
                    134 => "Colombo",
                     .
                     .
                    ),

    "Londrina" => array(
                    234 => "Cambé",
                    245 => "Ibiporã",
                     .
                     .
                    )
)
}}}

[[Image(select_option_multiple_combo.png)]]

Alguns elementos estão desabilitados pois já foram adicionados ao ''select''.

Uma visão mais geral do componente é apresentada a seguir:

[[Image(select_option_multiple.png)]]

Ao remover um elemento do ''select'', ele volta a ser habilitado na ''combo'' para que possa ser selecionado novamente, se necessário.

'''Exemplo de utilização:'''

{{{
{wf_select_option_multiple nameTop="disponiveis" nameBottom="cadastrados" arrayTop=$lista diffEnable=false}
}}}

O exemplo acima cria o componente com o array $lista carregado na ''combo''. Se esse array tiver um formato semelhante ao exemplo da imagem acima, será utilizado o optGroup, mas se for um array normal, será criada uma ''combo'' com ''options'' normais. O parâmetro "diffEnable=false" indica que não será realizado o diff entre a ''combo'' e o ''select'', que nesse caso realmente não é necessário, pois o ''select'' está vazio.

{{{
{wf_select_option_multiple nameTop="disponiveis" nameBottom="cadastrados" arrayTop=$listaCombo 
      arrayBottom=$listaSelect sortEnableBottom=false}
}}}

O exemplo acima cria o componente com a ''combo'' e o ''select'' carregados automaticamente com os arrays $listaCombo e $listaSelect, respectivamente. Quando não é especificado o '''diffEnable''', ou é definido "diffEnable=true", é efetuado o diff entre a ''combo'' e o ''select'', que desabilita os elementos da ''combo'' que forem encontrados no ''select''. Com "sortEnableBottom=false", os elementos do ''select'' não serão ordenados. Caso esse parâmetro não seja especificado, seu valor padrão é '''true'''.

'''ATENÇÃO:''' Antes do formulário ser submetido, você deve chamar a função javascript do componente "selectAllOptions". Essa função recebe como parâmetro o nome do ''select'' a ter as ''options'' selecionadas. No PHP serão recuperados os ''values'' dos elementos selecionados.