public
Last active

JMicrodata library usage

  • Download Gist
README.md
Markdown

Readme

A Joomla! library to implement http://schema.org microdata semantics.
Link to the library https://github.com/joomla/joomla-cms/tree/master/libraries/joomla/microdata

The JMicrodata class uses the types.json file which contains all available http://schema.org Types and Properties.
The types.json was automatically created with the https://github.com/PAlexcom/Spider4Schema web crawler.

For usage examples you can see the test file https://github.com/joomla/joomla-cms/blob/master/tests/unit/suites/libraries/joomla/microdata/JMicrodataTest.php

JMicrodata class usage

All Microdata HTML output is handled by the JMicrodata class

<?php
JMicrodata::htmlScope($scope);
?>

Return itemscope itemtype="http://schema.org/$scope", the HTML Scope of the given Type, must be inside a HTML tag element.


<?php
JMicrodata::htmlProperty($property);  
?>

Return itemprop="$property", the HTML of the given Property, must be inside a HTML tag element.


<?php
JMicrodata::htmlSpan($content, $property = '', $scope = '', $inverse = false);
?>

Return <span itemscope itemtype="http://schema.org/$scope itemprop="$property">$content</span>, the microdata in a <span> tag, there is also available a JMicrodata::htmlDiv() method with the same functionalities.


<?php
JMicrodata::htmlMeta($content, $property, $scope = '', $inverse = false);
?>

Return <meta $property $scope content='$content'>, the microdata in a <meta> tag with content for machines.


<?php
$microdata = JMicrodata($type = '', $flag = true);
?>

Create a new instance of the JMicrodata class and setup the current Type, the flag param is for enabling or disabling HTML microdata semantics output. Fallback to Thing Type if the Type isn't available or given.


<?php
$microdata->enable($flag = true);
?>

Enable or Disable HTML Microdata semantics output.


<?php
$microdata->isEnabled();
?>

Return true if Microdata semantics HTML output are enabled.


<?php
$microdata->setType($type);
?>

Set a new Schema.org Type, there is also a $microdata->getType() function to retrieve the current Type.


<?php
$microdata->property($name);
?>

Setup the Property if available in the current Type Scope, there is also a $microdata->getProperty() function to retrieve the current Property.


<?php
$microdata->content($value, $machineValue = null);
?>

Setup a Text value or Content value for the Microdata, there is also a $microdata->getContent() function to retrieve the current Text value.


<?php
$microdata->fallback($type, $property);
?>

Setup a Fallback Type and Property, there are also the $microdata->getFallbackType() and $microdata->getFallbackProperty() to retrieve the Fallback Type and Fallback Property. Fallback to Thing Type if the Type isn't available, Fallback to null the Property if isn't available.


<?php
$microdata->displayScope();
?>

Return itemscope itemtype="http://schema.org/$scope the HTML with the Scope of the current Type, must be inserted inside a tag element.


<?php
$microdata->display($displayType = '', $emptyOutput = false);
?>

Return the Microdata HTML, if the Property isn't available it checks for a Fallback, otherwise return ''.

There are 4 types of $displayType:

  • inline
  • span
  • html
  • meta

This method contains the HTML Microdata display logic,
If the developer specify the $displayType param, the Microdata will be returned the way you specified and expect — to,
Otherwise if the $displayType param is empty it will be processed by the display() method and returned the HTML in the right way, with the expected Property Type (example of expectedTypes = URL, Text, Person ...)

— What happens if you call display($displayType = 'meta') ?
The returned HTML will be inside a <meta> HTML tag.

— What happend if you call display()?
The method will automatically check the expected type for the given Property, and will return the right Microdata HTML.

There are 3 types of Microdata:

  • nested → example: itemprop="author" itemscope itemtype="http://schema.org/Person, if there is also available a $content it will output <span itemprop="author" itemscope itemtype="http://schema.org/Person>$content</span>
  • meta → example: <meta content="2011-01-01" itemprop="datePublished">, if no $content is available will output itemprop="datePublished"
  • normal → example: itemprop="author", if there is available a $content will output <span itemprop="author">$content</span>

Example of Usage

<?php
$microdata = new JMicrodata('Article');
echo $microdata->property('author')->content('P.Alex')->fallback('Person', 'name')->display();
?>

It will output:

<span itemprop='author' itemscope itemtype='https://schema.org/Person'>
  <span itemprop='name'>
    P.Alex
  </span>
</span>

The display() method must be last called, for other methods there is no priority, once displayed the Microdata the params will be reseted.

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.