Scaffolding services

#Introduction LODSPeaKr provides a simple mechanism to create services (see Example: How to set up a service) and passing arguments (see Passing arguments to services) to them. In newer versions, it is also possible to create services including slashes (see Creating services with slashes). Since version 20130208, it is also possible to define a different set of templates and queries based on the arguments.

#How does scaffolding work?

First, you create a service as usual (see Example: How to set up a service). Later you run

utils/lodspk.sh scaffold service myService

This script will ask for patterns that the arguments of this service should match in order to execute a certain subcomponent. These patterns can include regular expressions (see at the bottom of this page for a quick reference of Regular Expressions). For each pattern created, there will be a subcomponent, which contains the same files as a regular component. These subcomponents are named pattern0, pattern1, etc. and are associated to each pattern.

If one one of these patterns matches, the service will use the related subcomponent instead of the regulat template and queries. If none of these patterns matches, the default will be the original service template/queries, as any regular service.

Note: Be aware that the order in which the patterns are used to match the arguments is not defined, so be careful that the patterns are well defined.

#Example Lets say we want to have a service that perform the following operations

• When there is only a username as an argument (e.g., http://server/nuevo/alangrafu), show all the projects of that user
• When there is a username and a project as an argument (e.g., http://server/nuevo/alangrafu/lodspeakr), show all the commits for that project
• When there is a username and a project as an argument and the word description (e.g., http://server/nuevo/alangrafu/lodspeakr/description), show only the description of the project
• If there none of these conditions are met, show a list of all the users of the system

$ utils/lodspk.sh scaffold service nuevo
You are about to scaffold service nuevo
You can use regular expressions to match different arguments

====EXAMPLE====
^\d+$

will match if there is only ONE argument that are only digits such as http://server/nuevo/123
but NOT http://server/nuevo/123asd or http://server/nuevo/asd


See http://0n.cl/7 for more details about regular expressions


==== NEW SCAFFOLD PATTERN (1) ===

What pattern the arguments should follow (Hint: use regular expressions)? ^\w+$
Is '^\w+$' correct? y

Do you want to add a new a new pattern [y/n]? y

==== NEW SCAFFOLD PATTERN (2) ===

What pattern the arguments should follow (Hint: use regular expressions)? ^\w+/\w+$    
Is '^\w+/\w+$' correct? y

Do you want to add a new a new pattern [y/n]? y

==== NEW SCAFFOLD PATTERN (3) ===

What pattern the arguments should follow (Hint: use regular expressions)? ^\w+/\w+/description$
Is '^\w+/\w+/description$' correct? y

Do you want to add a new a new pattern [y/n]? n


==== PATTERNS ====
These are the regular expressions you entered


^\w+$
^\w+/\w+$
^\w+/\w+/description$


Confirm they are OK [y/n]? y

If pattern '^\w+$' matches the arguments, subComponent 'pattern0' will be used
If pattern '^\w+/\w+$' matches the arguments, subComponent 'pattern1' will be used
If pattern '^\w+/\w+/description$' matches the arguments, subComponent 'pattern2' will be used

Scaffold created

A new file called scaffold.ttl will be created in the root of the service (in this case components/services/nuevo/). The content of the scaffold.ttl file should be something like

@prefix lodspk: <http://lodspeakr.org/vocab/> .
@prefix dcterms: <http://purl.org/dc/terms/> .

<#service> a lodspk:ScaffoldedService ;
 lodspk:scaffold <#pattern0> ;
 lodspk:scaffold <#pattern1> ;
 lodspk:scaffold <#pattern2> ;
 dcterms:identifier "nuevo" .



#If pattern '^\w+$' matches the arguments, subComponent 'pattern0' will be used
<#pattern0> a lodspk:Pattern;
 lodspk:uriPattern "^\\w+$";
 dcterms:identifier "0";
 lodspk:subComponent "pattern0".

#If pattern '^\w+/\w+$' matches the arguments, subComponent 'pattern1' will be used
<#pattern1> a lodspk:Pattern;
 lodspk:uriPattern "^\\w+/\\w+$";
 dcterms:identifier "1";
 lodspk:subComponent "pattern1".

#If pattern '^\w+/\w+/description$' matches the arguments, subComponent 'pattern2' will be used
<#pattern2> a lodspk:Pattern;
 lodspk:uriPattern "^\\w+/\\w+/description$";
 dcterms:identifier "2";
 lodspk:subComponent "pattern2".

For each pattern a subdirectory called pattern0, pattern1, pattern2 will be created under components/services/nuevo/ as well. The content of each subcomponent is the same as a regular service

###Known bug The default HTML template uses a relative reference to include the menu

{%include "../../includes/header.inc"%}

since subcomponents are one level lower in the filesystem tree, these include should be edited to become

{%include "../../../includes/header.inc"%}

This is a trivial bug that should be fixed soon.

#Regular expressions quick reference Taken form the PHP documentation

• [abc] A single character: a, b or c
• [^abc] Any single character but a, b, or c
• [a-z] Any single character in the range a-z
• [a-zA-Z] Any single character in the range a-z or A-Z
• ^ Start of line
• $ End of line
• \A Start of string
• \z End of string
• . Any single character
• \s Any whitespace character
• \S Any non-whitespace character
• \d Any digit
• \D Any non-digit
• \w Any word character (letter, number, underscore)
• \W Any non-word character
• \b Any word boundary character
• (...) Capture everything enclosed
• (a|b) a or b
• a? Zero or one of a
• a* Zero or more of a
• a+ One or more of a
• a{3} Exactly 3 of a
• a{3,} 3 or more of a
• a{3,6} Between 3 and 6 of a