Microdados
From Joomla! Documentation
This article or section is incomplete, which means it may be lacking information. You are welcome to assist in its completion by editing it as well. If this article or section has not been edited in several days, please consider helping complete the content.
This article was last edited by Gkiyoshinishimoto (talk| contribs) 3 years ago. (Purge)
O que são microdados
Os microdados são uma forma de adicionar informações contextuais ao seu site e ao seu conteúdo, permitindo que os mecanismos de buscas compreendam melhor as informações que você fornece.
As informações contextuais permitem que os mecanismos de pesquisas entendam o significado das informações apresentadas em seu site, o que permite responder melhor a consultas de "linguagem natural" mais detalhadas, onde a compreensão do significado ajuda a interpretar o conteúdo mais relevante a ser exibido.
Os microdados podem ser usados para explicar praticamente qualquer coisa que você queira explicar, e há mais "esquemas" sendo adicionados regularmente. Existem vários vocabulários, mas atualmente o sistema preferido pelos mecanismos de buscas é o de schema.org.
Para entender como os mecanismos de pesquisas usam as informações dos microdados, veja este pequeno vídeo.
Roteiro do Joomla! 3.x para os microdados
A versão 3.2 introduziu a biblioteca JMicrodata, parte de um dos muitos projetos bem-sucedidos enviados durante o GSoC 2013 e a versão 3.3 introduziu elementos de microdados em dois dos esquemas do componente principal. Para a versão 3.4, pretendemos continuar refinando a biblioteca JMicrodata para garantir que seja flexível e fácil de usar para usuários de todos os níveis de habilidade e continuar implementando elementos de microdados em esquemas principais.
Como utilizo os microdados?
Os microdados podem ser adicionados ao Joomla! usando sobreposições de modelos ou com o uso de plugins que permitem inserir microdados em recursos específicos.
A partir do Joomla! 
existe uma biblioteca dentro do Joomla! que permite que os desenvolvedores extraiam microdados sem precisar formatá-los corretamente.
JMicrodata
A JMicrodata é uma biblioteca para implementar e produzir a semântica de microdados de http://schema.org.
A biblioteca foi projetada com esses objetivos em mente:
- Ter a possibilidade de alternar os tipos de microdados dinamicamente, basta alterar os tipos (há 558 tipos diferentes disponíveis);
- exibir semântica validada, a biblioteca cuida para exibir os dados corretamente;
- habilitar/desabilitar a semântica dos microdados;
- reservas, você nunca deve perder qualquer semântica significativa;
A classe JMicrodata usa o arquivo types.json que contém todos os tipos e propriedades de http://schema.org disponíveis, esse arquivo foi criado automaticamente com o rastreador web de https://github.com/PAlexcom/Spider4Schema.
Como uso a biblioteca JMicrodata?
Antes de tudo, você precisa criar uma instância da biblioteca em suas extensões:
<?php
$microdata = new JMicrodata('Article');
?>
Então, vamos supor que você tenha a seguinte string que faz parte do seu artigo:
<div>
<!-- Author of the content -->
<span>
Written by Alexandru Pruteanu
</span>
<!-- The content -->
Here is the article text...
<div>
E você deseja adicionar semântica de microdados e configurar o tipo de escopo atual como Article:
<?php
$microdata = new JMicrodata('Article');
?>
<div <?php echo $microdata->displayScope();?>>
<!-- Author of the content -->
<span>
Written by <?php echo $microdata->content('Alexandru Pruteanu')->property('author')->fallback('Person', 'name')->display();?>
</span>
<!-- The content -->
<?php echo $microdata->content('Here is the article text...')->property('articleBody')->display();?>
<div>
A biblioteca exibirá:
<div itemscope itemtype='https://schema.org/Article'>
<!-- Author of the content -->
<span>
Written by
<span itemprop='author' itemscope itemtype='https://schema.org/Person'>
<span itemprop='name'>Alexandru Pruteanu</span>
</span>
</span>
<!-- The content -->
<span itemprop='articleBody'>Here is the article text...</span>
<div>
O que acontece se o escopo atual for diferente de Article, por exemplo, um escopo Product, e o escopo atual não tiver uma propriedade Author e articleBody?
<?php
$microdata = new JMicrodata('Product');
?>
<div <?php echo $microdata->displayScope();?>>
<!-- Author of the content -->
<span>
Written by <?php echo $microdata->content('Alexandru Pruteanu')->property('author')->fallback('Person', 'name')->display();?>
</span>
<!-- The content -->
<?php echo $microdata->content('Here is the article text...')->property('articleBody')->display();?>
<div>
Como você adicionou um substituto ->fallback('Person', 'name'), ele retornará ao tipo Person e você não perderá nenhuma semântica significativa .
<div itemscope itemtype='https://schema.org/Product'>
<!-- Author of the content -->
<span>
Written by
<span itemscope itemtype='https://schema.org/Person'>
<span itemprop='name'>Alexandru Pruteanu</span>
</span>
</span>
<!-- The content -->
Here is the article text...
<div>
Se você não precisar de todas essas informações dos microdados, basta desativar esse recurso chamando: $microdata->enable(false);
<?php
$microdata = new JMicrodata('Product');
$microdata->enable(false);
?>
<div <?php echo $microdata->displayScope();?>>
<!-- Author of the content -->
<span>
Written by <?php echo $microdata->content('Alexandru Pruteanu')->property('author')->fallback('Person', 'name')->display();?>
</span>
<!-- The content -->
<?php echo $microdata->content('Here is the article text...')->property('articleBody')->display();?>
<div>
A biblioteca exibirá o seguinte:
<div>
<!-- Author of the content -->
<span>
Written by Alexandru Pruteanu
</span>
<!-- The content -->
Here is the article text...
<div>
Documentação da JMicrodata
Todas as saídas html dos microdados são tratadas pela classe JMicrodata.
JMicrodata::htmlScope($scope);
Retorno:
itemscope itemtype="http://schema.org/$scope"
o Escopo html do Tipo fornecido, deve estar dentro de um elemento de tag html.
JMicrodata::htmlProperty($property);
Retorno:
itemprop="$property"
a html da Propriedade fornecida, deve estar dentro de um elemento de tag html.
JMicrodata::htmlSpan($content, $property = "", $scope = "", $inverse = false);
Retorno:
<span itemscope itemtype="http://schema.org/$scope" itemprop="$property">
$content
</span>
os microdados em uma tag , também está disponível um método JMicrodata::htmlDiv() com as mesmas funcionalidades.
JMicrodata::htmlMeta($content, $property, $scope = "", $inverse = false);
Retorno:
<meta $property $scope content="$content">
os microdados em uma tag <meta> com o conteúdo para máquinas, esse método não adiciona a metatag na seção <head> da página.
$microdata = JMicrodata($type = "", $flag = true);
Cria uma nova instância da classe JMicrodata e configura o Tipo atual, o parâmetro flag é para habilitar ou desabilitar a saída semântica de microdados html. Substitui para o tipo Thing se o tipo não estiver disponível ou não for fornecido.
$microdata->enable($flag = true);
Habilita ou desabilita a saída semântica de microdados html.
$microdata->isEnabled();
Retorna true se a saída html da semântica de microdados estiver habilitada.
$microdata->setType($type);
Define um novo Tipo de Schema.org, também há uma função $microdata->getType() para recuperar o Tipo atual.
$microdata->property($name);
Configura a Propriedade se disponível no escopo do Tipo atual, há também uma função $microdata->getProperty() para recuperar a Propriedade atual.
$microdata->content($value, $machineValue = null);
Configura um Valor de texto ou Valor de conteúdo para os microdados, também há uma função $microdata->getContent() para recuperar o valor de texto atual .
$microdata->fallback($type, $property);
Configura um Tipo e uma Propriedade de reserva, também existem $microdata->getFallbackType() e $microdata->getFallbackProperty() para recuperar o Tipo e a Propriedade de reserva. Substitui pelo tipo Thing se o Tipo não estiver disponível, substitui por null se a propriedade não estiver disponível.
$microdata->displayScope();
Retorno:
itemscope itemtype="http://schema.org/$scope
a html com o Escopo do Tipo atual, deve ser inserida dentro de um elemento tag.
$microdata->display($displayType = "", $emptyOutput = false);
Retorna a html de microdados, se a Propriedade não estiver disponível, verifica um(a) reserva, caso contrário, retorna .
Existem 4 tipos de $displayType:
- inline
- span
- html
- meta
Este método contém a lógica de exibição de microdados html, Se você especificar o parâmetro $displayType, os microdados serão retornados da maneira que você especificou e espera — para, Caso contrário, se o parâmetro $displayType estiver vazio, ele será processado pelo método display() e retornará a html da maneira correta, com o Tipo de Propriedade esperada (exemplo de expectedTypes = URL, Text, Person ...)
— O que acontece se você chamar display($displayType = "meta") ?
A html retornada estará dentro de uma tag html <meta>.
— O que acontece se você chamar display()?
O método verificará automaticamente o tipo esperado para a propriedade fornecida e retornará a html de microdados correta.
Existem 3 tipos de microdados:
- aninhado → exemplo:
itemprop="$property" itemscope itemtype="http://schema.org/$scope"
se também estiver disponível um $content, isso produzirá
<span itemprop="$property" itemscope itemtype="http://schema.org/$scope">$content</span>
- meta → exemplo:
<meta content="$content" itemprop="$property">
se nenhum $content estiver disponível, será gerado
itemprop="$property"
- normal → exemplo:
itemprop="$property"
se estiver disponível um $content, será gerado
<span itemprop="$property">$content</span>
Para alguns exemplos de uso, você pode ver o arquivo de teste da biblioteca https://github.com/joomla/joomla-cms/blob/master/tests/unit/suites/libraries/joomla/microdata/JMicrodataTest.php