You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by ol...@apache.org on 2017/12/18 10:49:00 UTC
[sling-site] branch master updated (3ac498f -> 6039404)
This is an automated email from the ASF dual-hosted git repository.
olli pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git.
from 3ac498f Added Apache Sling Servlets Resolver 2.4.22
new 79dbf0d SLING-7167 Adjust READMEs
new 6039404 SLING-7167 Adjust READMEs
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../assets/documentation/bundles/hapi/browser1.png | Bin 0 -> 40918 bytes
.../assets/documentation/bundles/hapi/browser2.png | Bin 0 -> 88843 bytes
.../assets/documentation/bundles/hapi/python1.png | Bin 0 -> 31309 bytes
.../assets/documentation/bundles/hapi/python2.png | Bin 0 -> 25918 bytes
.../assets/documentation/bundles/hapi/python3.png | Bin 0 -> 13094 bytes
.../assets/documentation/bundles/hapi/python4.png | Bin 0 -> 47394 bytes
src/main/jbake/content/documentation/bundles.md | 2 +
.../content/documentation/bundles/distribution.md | 252 +++++++++++++++++++++
.../jbake/content/documentation/bundles/hapi.md | 208 +++++++++++++++++
9 files changed, 462 insertions(+)
create mode 100644 src/main/jbake/assets/documentation/bundles/hapi/browser1.png
create mode 100644 src/main/jbake/assets/documentation/bundles/hapi/browser2.png
create mode 100644 src/main/jbake/assets/documentation/bundles/hapi/python1.png
create mode 100644 src/main/jbake/assets/documentation/bundles/hapi/python2.png
create mode 100644 src/main/jbake/assets/documentation/bundles/hapi/python3.png
create mode 100644 src/main/jbake/assets/documentation/bundles/hapi/python4.png
create mode 100644 src/main/jbake/content/documentation/bundles/distribution.md
create mode 100644 src/main/jbake/content/documentation/bundles/hapi.md
--
To stop receiving notification emails like this one, please contact
['"commits@sling.apache.org" <co...@sling.apache.org>'].
[sling-site] 01/02: SLING-7167 Adjust READMEs
Posted by ol...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
olli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
commit 79dbf0d1f2553710aa4ba7ae78cd9f7d0f32b8a5
Author: Oliver Lietz <ol...@apache.org>
AuthorDate: Mon Dec 18 11:25:59 2017 +0100
SLING-7167 Adjust READMEs
---
src/main/jbake/content/documentation/bundles.md | 1 +
.../content/documentation/bundles/distribution.md | 252 +++++++++++++++++++++
2 files changed, 253 insertions(+)
diff --git a/src/main/jbake/content/documentation/bundles.md b/src/main/jbake/content/documentation/bundles.md
index 374aeef..a0643bd 100644
--- a/src/main/jbake/content/documentation/bundles.md
+++ b/src/main/jbake/content/documentation/bundles.md
@@ -12,6 +12,7 @@ tags=bundles,modules
* [Rendering Content - Default GET servlets (servlets.get)](/documentation/bundles/rendering-content-default-get-servlets.html)
* [Validation](/documentation/bundles/validation.html)
* [Repository Initialization](/documentation/bundles/repository-initialization.html)
+* [Distribution](/documentation/bundles/distribution.html)
## Resource Providers
diff --git a/src/main/jbake/content/documentation/bundles/distribution.md b/src/main/jbake/content/documentation/bundles/distribution.md
new file mode 100644
index 0000000..255e3bd
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/distribution.md
@@ -0,0 +1,252 @@
+title=Content Distribution
+type=page
+status=published
+tags=distribution
+~~~~~~
+
+## Overview
+
+The Sling Content Distribution module main goal is allowing distribution of content (Sling resources) among different Sling
+instances. The term "distribution" here means the ability of picking one or more resources on a certain Sling instance in order
+to copy and persist them onto another Sling instance. The Sling Content Distribution module is able to distribute content
+by:
+
+ - "pushing" from Sling instance A to Sling instance B
+ - "pulling" from Sling instance B to Sling instance A
+ - "synchronizing" Sling instances A and B via a (third) coordinating instance C
+
+### Bundles
+
+The Sling Content Distribution module consists of the following bundles:
+
+ - `org.apache.sling.distribution.api`: this is where the APIs are defined
+ - `org.apache.sling.distribution.core`: this is where the basic infrastructure for distributing content is implemented
+ - `org.apache.sling.distribution.kryo-serializer`: Kryo based distribution package serializer
+ - `org.apache.sling.distribution.avro-serializer`: Apache Avro based distribution package serializer
+ - `org.apache.sling.distribution.sample`: this is a set of sample configurations and implementations for demo purpose
+ - `org.apache.sling.distribution.it`: this is the integration testing suite
+
+## Design
+
+The Sling Content Distribution aims to be: _Reliable_, _simple_ and _extensible_.
+
+Reliability means that the system should be able to keep working also in presence of failures regarding I/O, network, etc.
+An example of such problems is when pushing content from instance A to instance B fails because B is unreachable: in such
+ scenarios instance A should be able to keep pushing (pulling, etc.) content to other instances seamlessly. Another example
+ is when delivery of a certain content (package) fails too many times the distribution module should be able to either drop
+ it or move it into a different "bucket" of failed items.
+Simplicity means that this module should be able to accomplish its tasks by providing clear, minimal and easy to use APIs together
+with smart but not overly complicated or "hacky" implementations (see ["Simple software is hard"](http://events.linuxfoundation.org/events/apachecon-europe/program/schedule)).
+Extensibility means that the Sling Content Distribution module provides a set of APIs for distributing resources where each
+component coming into place during the distribution lifecycle can be extended or totally replaced.
+
+A distribution _request_ represents the need of aggregating some resources and to copy them from / to another Sling instance.
+Such requests are handled by _agents_ that are the main entry point for working with the distribution module.
+Each agent distributes content from one or more sources to one or more targets, such distribution can be triggered by:
+
+ - "pushing" the content to the (remote) target instances
+ - "pulling" content from the (remote) source instances
+ - "coordinating" instances, that is they are used to synchronize multiple instances by having them as both sources and targets
+
+An _agent_ is capable of handling a certain distribution _request_ by creating one or more _packages_ of resources out of it
+from the source(s), dispatching such _packages_ to one or more _queues_ and of processing such queued _packages_ by persisting
+them into the target instance(s).
+
+The process of creating one or more packages is called _exporting_ as such operation may either happen locally to the agent
+(the "push" scenario) or remotely (the "pull" scenario).
+
+The process of persisting one or more packages is called _importing_ as such operation may either happen locally (the "pull"
+scenario) or remotely (the "push" scenario).
+
+In order to properly handle large number of _requests_ against the same _agent_ each of them is provided with _queues_
+where the exported _packages_ are sent, the _agent_ takes then care to process such a _queue_ in order to _import_ each
+_package_.
+
+
+### Distribution agents configuration
+
+Distribution agents configurations are proper OSGi configurations (backed by nodes of type `sling:OsgiConfig` in the repository).
+
+There are specialized factories for each supported scenario:
+
+- "forward" agents, see [ForwardDistributionAgentFactory-publish.json](https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/publish/org.apache.sling.distribution.agent.impl.ForwardDistributionAgentFactory-publish.json).
+- "reverse" agents, see [ReverseDistributionAgentFactory-publish-reverse.json](https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/publish-reverse/org.apache.sling.distribution.agent.impl.ReverseDistributionAgentFactory-publish-reverse.json).
+- "sync" agents, see [SyncDistributionAgentFactory-pubsync.json](https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.author/pubsync/org.apache.sling.distribution.agent.impl.SyncDistributionAgentFactory-pubsync.json).
+- "queue" agents, see [QueueDistributionAgentFactory-reverse.json](https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-sample.git;a=blob_plain;f=src/main/resources/SLING-CONTENT/libs/sling/distribution/install.publish/reverse/org.apache.sling.distribution.agent.impl.QueueDistributionAgentFactory-reverse.json).
+
+For example a "forward" agent can be defined specifying
+
+- The name of the agent (name property)
+- The sub service name used to access content and build packages (serviceName property)
+- The endpoints where the packages are to be imported (packageImporter.endpoints property)
+
+The sample package contains endpoints for exposing configuration for distribution agents.
+The _DistributionConfigurationResourceProviderFactory_ is used to expose agent configurations as resources.
+
+ {
+ "jcr:primaryType": "sling:OsgiConfig",
+ "provider.roots": [ "/libs/sling/distribution/settings/agents" ],
+ "kind" : "agent"
+ }
+
+Distribution agents' configurations can be retrieved via `HTTP GET`:
+
+ $ curl -u admin:admin http://localhost:8080/libs/sling/distribution/settings/agents/{agentName}.json
+
+### Distribution agents services
+
+Each distribution agent is an OSGi service and is resolved using a [Sling Resource Provider](#Resource_Providers) who locate it under `libs/sling/distribution/services/agents`.
+
+The _DistributionConfigurationResourceProviderFactory_ allows one to configure HTTP endpoints to access distribution OSGI configurations.
+The sample package contains endpoints for exposing distribution agents.
+The _DistributionServiceResourceProviderFactory_ is used to expose agent services as resources.
+
+ {
+ "jcr:primaryType": "sling:OsgiConfig",
+ "provider.roots": [ "/libs/sling/distribution/services/agents" ],
+ "kind" : "agent"
+ }
+
+Distribution agents can be triggered by sending `HTTP POST` requests to
+
+`http://$host:$port/libs/sling/distribution/services/agents/{agentName}`
+
+with HTTP parameters `action` and `path`.
+
+### Distribution queues
+
+#### In Memory queue
+
+That's a draft implementation using an in memory blocking queue together with a Sling scheduled processor which periodically fetches the first item of each queue and trigger a distribution of such an item.
+It's not suitable for production as it's currently not persisted and therefore restarting the bundle / platform would not keep the queue together with its items.
+
+#### Sling Job Handling based queue
+
+That's a queue implementation based on the queues and jobs provided by Sling Event bundle.
+Each item addition to a queue triggers the creation of a Sling job which will handle the processing of that item in the queue.
+By default Sling queues for distribution have the following options:
+
+- ordered
+- with max priority
+- with infinite retries
+- keeping job history
+
+### Distribution of packages among queues
+
+Each distribution agent uses a specific queue distribution mechanism, specified via a 'queue distribution strategy', which defines how packages are routed into agent queues.
+The currently available distribution strategies are
+
+- single: the agent has one only queue and all the items are routed there
+- priority path: the agent can route a configurable set of paths (note that this configuration is currently global for the system, not per agent) to a dedicated priority queue while all the others go to the default queue
+- error aware: the agent has one default queue for all the items, items failing for a configurable amount of times are either dropped or moved to an error queue (depending on configuration)
+
+
+## Usecases
+
+### Forward distribution
+
+In order to configure the "forward" distribution workflow, that transfers content from an author instance to a publish instance:
+
+- configure a remote importer on publish
+- configure a "forward" agent on author pointing to the url of the importer on publish
+
+Send `HTTP POST`request to `http://localhost:8080/libs/sling/distribution/services/agents/publish` with parameters `action=ADD` and `path=/content`
+
+#### Create/update content
+
+ $ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action=ADD' -d 'path=/content/sample1'
+
+#### Delete content
+
+ $ curl -v -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish -d 'action= DELETE' -d 'path=/content/sample1'
+
+### Reverse distribution
+
+In order to configure the "reverse" distribution workflow, that transfers content from a publish instance to an author instance:
+- configure a queue agent on publish to hold the packages that need to be distributed to author
+- configure a remote exporter on publish that exports package from the queue agent
+- configure a "reverse" agent on author pointing to the url of the exporter on publish
+
+Send `HTTP POST`request to `http://localhost:8080/libs/sling/distribution/services/agents/publish-reverse` with parameters `action=PULL`
+
+
+#### Create/update content
+
+ $ curl -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/reverse -d 'action=ADD' -d 'path=/content/sample1'
+ $ curl -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/publish-reverse -d 'action=PULL'
+
+### Sync distribution
+
+
+In order to configure the "sync" distribution workflow, that transfers content from two publish instances via an author instance:
+- configure a remote exporter on each publish instance
+- configure a remote importer on each publish instance
+- configure a "sync" agent on author pointing to the urls of the exporter and importers on publish
+
+Send `HTTP POST`request to `http://localhost:8080/libs/sling/distribution/services/agents/pubsync` with parameters `action=PULL`
+
+
+#### Create/update content
+
+ $ curl -u admin:admin http://localhost:8081/libs/sling/distribution/services/agents/reverse-pubsync -d 'action=ADD' -d 'path=/content/sample1'
+ $ curl -u admin:admin http://localhost:8080/libs/sling/distribution/services/agents/pubsync -d 'action=PULL'
+
+### Installation
+
+- install the dependency bundles on all Sling instances
+- install Sling Distribution api, core, samples on all Sling instances
+
+## HTTP API
+
+### API Requirements
+We need to expose APIs for configuring, commanding and monitoring distribution agents.
+
+- Configuration API should allow:
+ - CRUD operations for agent configs
+- Command API (eventually issued to multiple agents at once) should allow:
+ - to trigger a distribution request on a specific agent
+ - to explicitly create and export a package
+ - to explicitly import a formerly created package
+- Monitoring API should allow:
+ - inspection to internal queues of distribution agents
+ - inspection of commands history
+
+### API endpoints
+
+#### Configuration API
+- Create config: - POST _/libs/sling/distribution/settings/agents_
+- Read config - GET _/libs/sling/distribution/settings/agents/{agentName}_
+- Update config - PUT _/libs/sling/distribution/settings/agents/{agentName}_
+- Delete config - DELETE _/libs/sling/distribution/settings/agents/{agentName}_
+
+#### Command API
+- Distribute - POST _/libs/sling/distribution/services/agents/{agentName}_
+- Import package - POST _/libs/sling/distribution/services/importers/{importerName}_
+- Export package - POST _/libs/sling/distribution/services/exporters/{exporterName}_
+
+#### Monitoring API
+- Distribution history - GET _/libs/sling/distribution/services/agents/{agentName}/log_
+- Agent queue inspection - GET _/libs/sling/distribution/services/agents/{agentName}/queues_
+
+## Java API
+
+There is a single entry point in triggering a distribution workflow, via [Distributor](https://gitbox.apache.org/repos/asf?p=sling-org-apache-sling-distribution-api.git;a=blob_plain;f=src/main/java/org/apache/sling/distribution/Distributor.java) API.
+
+ Distributor.distribute(agentName, resourceResolver, distributionRequest)
+
+## Extensions
+
+The following extensions for Apache Sling Content Distribution exist.
+
+### Apache Avro serializer
+The _org.apache.sling.distribution.avro-serializer_ contains a _DistributionContentSerializer_ based on [Apache Avro](http://avro.apache.org).
+
+### Kryo serializer
+The _org.apache.sling.distribution.kryo-serializer_ contains a _DistributionContentSerializer_ based on [Kryo](http://github.com/EsotericSoftware/kryo).
+
+## Ideas for future developments
+
+- distributed configuration
+- pushing to / pulling from JMS (pros: established pattern for producers/consumers problems, cons: other library / systems involved as a possible PoF)
+- WebSocket support (pros: once established it's bidirectional and therefore also publish can directly push stuff to author)
+- asynchronous import of packages (pros: parallel transport and import, cons: complex management of multiple queues on different publish instances)
--
To stop receiving notification emails like this one, please contact
"commits@sling.apache.org" <co...@sling.apache.org>.
[sling-site] 02/02: SLING-7167 Adjust READMEs
Posted by ol...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
olli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
commit 60394041f1e4869cbdd3616f4f0c903567fd6902
Author: Oliver Lietz <ol...@apache.org>
AuthorDate: Mon Dec 18 11:47:31 2017 +0100
SLING-7167 Adjust READMEs
---
.../assets/documentation/bundles/hapi/browser1.png | Bin 0 -> 40918 bytes
.../assets/documentation/bundles/hapi/browser2.png | Bin 0 -> 88843 bytes
.../assets/documentation/bundles/hapi/python1.png | Bin 0 -> 31309 bytes
.../assets/documentation/bundles/hapi/python2.png | Bin 0 -> 25918 bytes
.../assets/documentation/bundles/hapi/python3.png | Bin 0 -> 13094 bytes
.../assets/documentation/bundles/hapi/python4.png | Bin 0 -> 47394 bytes
src/main/jbake/content/documentation/bundles.md | 1 +
.../jbake/content/documentation/bundles/hapi.md | 208 +++++++++++++++++++++
8 files changed, 209 insertions(+)
diff --git a/src/main/jbake/assets/documentation/bundles/hapi/browser1.png b/src/main/jbake/assets/documentation/bundles/hapi/browser1.png
new file mode 100644
index 0000000..4d2441e
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/hapi/browser1.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/hapi/browser2.png b/src/main/jbake/assets/documentation/bundles/hapi/browser2.png
new file mode 100644
index 0000000..581e281
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/hapi/browser2.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/hapi/python1.png b/src/main/jbake/assets/documentation/bundles/hapi/python1.png
new file mode 100644
index 0000000..24398f4
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/hapi/python1.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/hapi/python2.png b/src/main/jbake/assets/documentation/bundles/hapi/python2.png
new file mode 100644
index 0000000..a82bcfe
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/hapi/python2.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/hapi/python3.png b/src/main/jbake/assets/documentation/bundles/hapi/python3.png
new file mode 100644
index 0000000..0adfb56
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/hapi/python3.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/hapi/python4.png b/src/main/jbake/assets/documentation/bundles/hapi/python4.png
new file mode 100644
index 0000000..8f89759
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/hapi/python4.png differ
diff --git a/src/main/jbake/content/documentation/bundles.md b/src/main/jbake/content/documentation/bundles.md
index a0643bd..ebb6ae7 100644
--- a/src/main/jbake/content/documentation/bundles.md
+++ b/src/main/jbake/content/documentation/bundles.md
@@ -53,6 +53,7 @@ The OSGi installer is a very flexible and powerful service to manage provisionin
* [Sling Metrics](/documentation/bundles/metrics.html)
* [Servlet Helpers](/documentation/bundles/servlet-helpers.html)
* [Context-Aware Configuration](/documentation/bundles/context-aware-configuration/context-aware-configuration.html)
+* [HApi - Hypermedia API tools](/documentation/bundles/hapi.html)
## Content Presentation and Rendering
* [Scripting](/documentation/bundles/scripting.html) (aka Templating)
diff --git a/src/main/jbake/content/documentation/bundles/hapi.md b/src/main/jbake/content/documentation/bundles/hapi.md
new file mode 100644
index 0000000..b8dda21
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/hapi.md
@@ -0,0 +1,208 @@
+title=HApi - Hypermedia API tools
+type=page
+status=published
+tags=hypermedia
+~~~~~~
+
+# <a name="section-1">HApi - Hypermedia API tools</a>
+
+The hypermedia API tools are a way to enable sling component developers to add metadata information to their HTML components and easily define an API using the html markup generated by the components.
+
+HApi tools work with [sightly](http://docs.adobe.com/docs/en/aem/6-0/develop/sightly.html), JSP or any scripting language that can call java code. For understanding how microdata works, read the next section, [Hypermedia API with Microdata](#section-2).
+
+To see how the HApi implemetation works, read [How HApi works, by example](#section-3)
+
+## <a name="section-install">Installation</a>
+ The two bundles, core and samplecontent need sightly installed on the sling instance.
+
+ You can then install both with _mvn clean install sling:install_
+
+ After that, to check the sample page go to http://localhost:8080/apps/sling/hapi_sample/site/site.html and check out the sample page.
+
+ See below for consuming the API with a generic client.
+
+
+## <a name="section-2">Hypermedia API with Microdata</a>
+There is a lot of confusion surrounding this term, but shortly put, it's an API having content with links. We can use it a way of defining a protocol-agnostic API for our resources, designing it from the client-side, using the html markup as the media type. This means the requested resource representation would be displayed in browsers out-of-the-box, but also understood by any user or automaton which understands the API. Such APIs can be defined for XML, HTML, JSON and becomes a hyperme [...]
+
+For us out there in a hurry, let's take the following short example from the [schema.org](http://schema.org/docs/gs.html) page:
+
+ <div itemscope itemtype="http://schema.org/Movie">
+ <h1 itemprop="name">Avatar</h1>
+ <span itemprop="genre">Science fiction</span>
+ <a href="../movies/avatar-theatrical-trailer.html" itemprop="trailer">Trailer</a>
+
+ <div itemprop="director" itemscope itemtype="http://schema.org/Person">
+ Director: <span itemprop="name">James Cameron</span> (born <span itemprop="birthDate">August16, 1954)</span>
+ </div>
+ </div>
+
+The attribute _itemscope_ defines a scope for an object. The (optional) _itemtype_ links to a description of the type of the object. Inside an element with an _itemscope_ attribute, we have descendant elements with a property _itemprop_. This means the _name_ property will point to the enclosed object, which is the simple text "Avatar". Similarly, the _genre_ property is "Science Fiction".
+
+The _director_ property is not a simple type, so it defines a new _itemscope_. Also, the _itemtype_ shows it's a Person. Now, the schema for Person defines the _name_ and the _birthDate_ properties, which are pointed to the same way as above.
+
+## <a name="section-3">How HApi works, by example</a>
+
+In order to see how HApi works, the best way is to check an example. In the sample content module, we have a demo app that defines an API and uses that in the sightly components. The best way to start is to analyze the end result and acknowledge it's usefuleness:
+
+### <a name="section-3a">Consuming the API</a>
+
+The app looks like this in the browser:
+
+
+The generated content looks something like this for the first card:
+
+ <div itemtype="/apps/sling/hapi_sample/types/album_card.html" itemscope="itemscope" class="card-asset">
+ <a href="details.html" rel="self">
+ <img itemprop="thumbnail" itemtype="/libs/sling/hapi/types/image.html" alt="" src="assets/preview-small-album.png" class="show-grid">
+
+ <div>
+ <h4 itemprop="title" itemtype="/libs/sling/hapi/types/text.html">PIC 001</h4>
+
+ <p class="type">album</p>
+
+ <p itemprop="cards" itemtype="/libs/sling/hapi/types/number.html" class="size">5</p>
+ <meta itemprop="disabled" itemtype="/libs/sling/hapi/types/boolean.html" content="false">
+ <div class="myinfo">
+ <p class="mymodified">
+ <i>Modified</i>
+ <span itemprop="modified" itemtype="/libs/sling/hapi/types/text.html" class="date">2 days ago</span>
+ <span>Admin</span>
+ </p>
+ </div>
+ </div>
+ </a>
+ </div>
+
+The entities that have semantic meaning to us (e.g. Are part of the API) are the elements annotated with microdata, links and forms:
+
+ * `<div itemtype="/apps/sling/hapi_sample/types/album_card.html" itemscope="itemscope" class="card-asset">`
+ * `<a href="details.html" rel="self">`
+ * `<link ...>`
+ * `<form ... >`
+
+ Because the API is defined using the generated HTML (same consumed by the browser), we can consume the _real_ content using any microdata thin, application-agnostic client.
+ A simple example is using [a simple html python client](https://github.com/dulvac/htmlapi-client-python/blob/master/htmlapi_client.py), but any client can be used. Here's what it can do:
+
+
+
+We can see that we have two objects in the page/ resource (because I've chosen to expose just two), one of type **pic_card** and one of type **album_card**. The types are URLs resolvable in sling. They look something like this in the browser:
+
+
+
+Let's continue using the html client to consume our API:
+
+
+
+
+For a hypermedia API, we use links as a way to change the state of the application, like it happens in the browser:
+
+
+
+So navigating/ changing state works by using the semantic meaning of links in html. Except the enter() function, there is no http url needed to use the sling web application. If you define your links and link relations correctly, any microdata client like this can change the state, in addition to consuming the content defined through the microdata hypermedia API.
+
+As you've probably noticed, we use some domain-specific types for _itemtype_. This is how you define the types:
+
+### Defining the types
+
+The types are defined as nt:unstructured nodes in the repository with a certain _sling:resourceType_ configurable in the OSGi config of the HApiUtil service:
+
+ {
+
+ "fqdn": "org.apache.sling.hapi_sample.album_card",
+ "description": "A demo card type for HApi",
+ "name": "album_card",
+ "sling:resourceType": "sling/hapi/components/type",
+ "parameters": [ ],
+ "extends": "/apps/sling/hapi_sample/types/demo_card",
+ "jcr:primaryType": "nt:unstructured",
+ "thumbnail":
+
+ {
+
+ "description": "The thumbnail of the demo pic card",
+ "type": "org.apache.sling.hapi.common.Image",
+ "multiple": true,
+ "jcr:primaryType": "nt:unstructured"
+
+ },
+ "disabled":
+ {
+
+ "description": "Whether this album is disabled or not",
+ "type": "org.apache.sling.hapi.common.Boolean",
+ "multiple": false,
+ "jcr:primaryType": "nt:unstructured"
+
+ },
+ "modified":
+ {
+
+ "description": "When was the pic last modified",
+ "type": "org.apache.sling.hapi.common.Text",
+ "multiple": false,
+ "jcr:primaryType": "nt:unstructured"
+
+ },
+ "cards":
+ {
+
+ "description": "The number of pictures in this album",
+ "type": "org.apache.sling.hapi.common.Number",
+ "multiple": false,
+ "jcr:primaryType": "nt:unstructured"
+
+ },
+ "users":
+
+ {
+ "description": "The numbers of users for this album",
+ "type": "org.apache.sling.hapi.common.Number",
+ "multiple": false,
+ "jcr:primaryType": "nt:unstructured"
+ }
+
+ }
+
+### Using the sightly HApiUse class
+
+After defining the types needed for the component in question, you can immediately benefit from the HApi tools and add the microdata annotations. There is also validation for the properties and the itemtype for properties is added automatically by the tools.
+
+This is how a sightly component using it looks like:
+
+ <div data-sly-use.card="${'org.apache.sling.hapi.sightly.HApiUse' @type='/apps/sling/hapi_sample/types/pic_card'}"
+ data-sly-attribute="${card.itemtype}" class="card-asset">
+ <a rel="self" href="details.html">
+ <img data-sly-attribute="${card.itemprop.thumbnail}" class="show-grid" src="assets/preview-small.png" alt="">
+
+ <div>
+ <h4 data-sly-attribute="${card.itemprop['title']}">PIC 001</h4>
+
+ <p class="type">PSD</p>
+
+ <p data-sly-attribute="${card.itemprop.resolution}"
+ data-sly-use.resolution="${'org.apache.sling.hapi.sightly.HApiUse' @type=card.proptype.resolution}" class="resolution">
+ <span data-sly-attribute="${resolution.itemprop.width}">1620</span> x <span
+ data-sly-attribute="${resolution.itemprop.height}">670</span>
+ </p>
+
+ <p data-sly-attribute="${card.itemprop.size}" class="size">249KB</p>
+ <meta data-sly-attribute="${card.itemprop.disabled}" content="false"/>
+ <div class="myinfo">
+ <p class="mymodified">
+ <i>Modified</i>
+ <span data-sly-attribute="${card.itemprop.modified}" class="date">2 days ago</span>
+ <span>Admin</span>
+ </p>
+ </div>
+ </div>
+ </a>
+ </div>
+
+
+The sightly script snippet above produces the html we saw in the section [Consuming the API](#section-3a).
+You only need to parameterize the use object once with the type identifier and the tool can validate the properties and infer the property type and automatically add the required itemtype attribute. Were we to try the following attribute on the pic_card markup, we'd get a runtime exception:
+
+ <img data-sly-attribute="${card.itemprop.inexistent_property}" class="show-grid" src="assets/preview-small.png" alt=""></span>
+
+ org.apache.sling.hapi.HApiException: Property inexistent_property does not exist for type /apps/hapi-sample/types/pic_card
--
To stop receiving notification emails like this one, please contact
"commits@sling.apache.org" <co...@sling.apache.org>.