Pré-requisitos

• SACI 4.2 (ou superior) instalado e funcionando corretamente. Ao longo do tutorial será assumida a URL de exemplo http://saci.instituicao.br
• Um produto jornalístico com base em um dos gabaritos: Joomla, Drupal ou Plone

Identificando um produto no SACI

Todo conteúdo publicável a partir do SACI é chamado de “matéria”. Semelhante a matérias de jornal ou revista, toda matéria no SACI está relacionada a um produto jornalístico, como por exemplo um boletim de e-mail, um site ou uma rede social.

É necessário descobrir qual a identificação do produto com o qual queremos integrar nosso site de exemplo. Para isso:

1. Acesse a área interna do SACI (forneça seu e-mail e sua senha);
2. Na lateral esquerda, acesse o menu “Unidades”;
3. Selecione a unidade em que seu produto está cadastrado
4. Na parte superior direita da página, clique na opção “Produtos”
5. Selecione o produto que você deseja integrar ao site de exemplo
6. Observe a barra de endereço (URL) do seu navegador. Ela deverá ter um conteúdo parecido com http://saci.instituicao.br/produto?id=P . Neste caso, o “P” é o número do produto que queremos testar.

Obtendo as matérias prontas para publicação

O primeiro serviço disponível na API de publicação do SACI é o de listagem das matérias prontas para publicação. Para testar esse serviço vamos criar uma página HTML simples (index.html) e adicionar o código Javascript necessário. Para fins de clareza adotaremos a biblioteca jQuery, porém qualquer biblioteca que permita o uso de chamadas AJAX usando JSON pode ser usada.

O exemplo abaixo recupera a lista de matérias do produto P que estão prontas para publicação e exibe o resultado no console do navegador:

    $.ajax({
        url:"http://saci.instituicao.br/listar_materias",
        type:'GET',
        async: true,                    
        dataType:'jsonp',   
        jsonpCallback: "callback", 
        contentType: "application/json",
        data:{produto: P}, 
        success: function(response) { 
            $.each(response, function(key, value) { 
                materia=value.id; 
                console.log(“id:” + value.id
                    +"\ntítulo:"+value.titulo
                    +"\ndestaque:"+value.destaque 
                    +"\ndestaqueImagem: "+value.destaqueImagem
                    +"\ndata_inicio: "+value.inicio+"\ndata_fim: "+value.fim 
                    +"\ntexto: "+value.texto);
                $.each(value.classificacoes, function(key,value){ 
                    console.log("-"+value.id);            
                    $.each(value.subclassificacoes, function(key,value){ 
                        console.log("--"+value.descricao);              
                    }); 
                });                            
            }); 
        }, 
        error: function(xHr,textStatus,error) { 
            console.log(textStatus); 
            console.log(error); 
        } 
    });

Em termos mais técnicos, a lista é retornada no formato JSONP, com cada item da lista representando uma matéria completa. Cada matéria possui o formato (em pseudo-código):

    Integer id //identificador
    String titulo //título
    String texto //texto completo
    String destaqueImagem //URL completa da imagem de destaque (pode ser nula)
    DestaqueCoordenadas destaque_coordenadas //coordenadas de corte da imagem de destaque
    List<Anexo> anexos //lista dos anexos
    Date inicio //data de início da publicação (pode ser nula)
    Date fim //data de vencimento da publicação (pode ser nula)
    List<Classificacao> classificacoes //lista das classificações da matéria
    Boolean destaque //se a matéria deve ter destaque na página inicial do site

A estrutura “coordenadas de destaque” possui o formato:

    Integer x1 //coordenada X do ponto superior-esquerdo (pixels)
    Integer y1 //coordenada Y do ponto superior-esquerdo (pixels)
    Integer x2 //coordenada X do ponto inferior-direito (pixels)
    Integer y2 //coordenada Y do ponto inferior-direito (pixels)

A estrutura “anexo” possui o formato:

    String arquivo //URL completa do anexo
    String legenda //legenda descrevendo o anexo (pode ser vazio) 

A estrutura “classificação” possui o formato:

    Integer id //identificador
    String descricao //descrição (seu nome)
    List<Subclassificacao> subclassificacoes //lista de subclassificações  

Finalmente, o formato de uma subclassificação é:

    Integer id; //identificador
    String descricao; //dscrição (seu nome)  

Vale notar que aquelas matérias que ainda não foram redigidas, editadas ou revisadas, ou ainda aquelas que já foram publicadas, não serão incluídas nesta lista.

Marcando uma matéria como publicada

Uma vez obtida a lista de matérias prontas para publicação, nossa aplicação de teste simplesmente imprimiu o conteúdo das matérias no console do navegador. Porém, uma aplicação real faria algo muito mais significativo. Um CMS, por exemplo, poderia converter cada matéria em um “post” em um site institucional. Já um aplicativo móvel poderia gerar um efeito sonoro alertando o usuário de que uma nova notícia está pronta.

Uma vez que uma ação tenha sido tomada, é necessário acessar o segundo serviço disponível na API de publicação do SACI, que é o de publicação de matéria. Apenas uma matéria por vez pode ser marcada como “publicada”, dificultando assim a ocorrência de acidentes.

O exemplo abaixo marca a matéria de identificador M como publicada:

    $.ajax({ 
        url:"http://localhost:8080/saci/publicar_materias", 
        type:'POST', 
        async: true,                    
        dataType:'jsonp', 
        jsonpCallback: "callback", 
        contentType: "application/json", 
        data:{materia: M}, 
        success: function() { 
      console.log("materia "+M+" publicada com sucesso"); 
        }, 
        error: function(xHr,textStatus,error) { 
      console.log(textStatus); 
      console.log(error); 
        } 
    });

Diferente do primeiro serviço (de listagem), este método não retorna informações significativas. Porém, é imprescindível que ele seja invocado, uma vez para cada matéria publicada, do contrário essas mesmas matérias continuarão a constar na lista de matérias disponíveis.

Casos especiais

Em geral o serviço para listagem de matérias lista apenas aquelas prontas para publicação, porém atenção especial deve ser dada a um caso particular: matérias que já foram publicadas mas que sofreram atualizações, voltando assim a constar como prontas para publicação. Esse comportamento é comum em casos de errata, complementação de texto etc, e cabe ao consumidor do serviço decidir como proceder.

Em casos onde o sistema consumidor seja um CMS (por exemplo, Drupal), é aconselhável:

• Selecionar o identificador da matéria sendo listada
• Procurar o post que foi gerado a partir dessa matéria (isso implifica que os posts precisem de um novo atributo para que se possa recuperar a matéria de origem)
• Atualizar o post com o novo texto
• Adicionar ao post uma nota de rodapé ou informar a data de atualização
• Marcar a matéria como publicada

  Porém, cada caso deve ser tratado a parte, já que estão envolvidas variáveis como o modelo de negócio do consumidor do serviço, o tipo do seu sistema (ex: CMS, aplicativo) etc.