# URL Parameters

SPARQLWorks™ encodes complete application states in URLs, enabling shareable, bookmarkable, and reproducible visualizations. This document explains all supported URL parameters.

## 📋 Parameter Overview

### Base URL Structure
```
https://sparqlworks.example.com/?[parameters]
```

### Parameter Types
- **Query Parameters**: SPARQL query and endpoint
- **Visualization Parameters**: Graph display settings
- **Filter Parameters**: Data filtering options
- **Authentication Parameters**: Secure credential sharing
- **Physics Parameters**: Layout and interaction settings

## 🔍 Query Parameters

### `q` - SPARQL Query
**Purpose**: Encodes the complete SPARQL query
**Format**: URL-encoded SPARQL query string
**Example**: `?q=CONSTRUCT%20%7B%20%3Fmovie%20dbo%3Acreator%20%3Fcreator%3B%20rdfs%3Alabel%20%3FmovieName.%20%7D%20WHERE%20%7B%20%3Fmovie%20dbo%3Acreator%20%3Fcreator%3B%20rdfs%3Alabel%20%3FmovieName.%20FILTER(%3Fcreator%20%3D%20dbr%3ASpike_Lee).%20%7D%20LIMIT%20200`

### `mode` - Query Mode
**Purpose**: Specifies Basic or Advanced mode
**Values**: `basic`, `advanced`
**Default**: `basic`
**Example**: `?mode=advanced`

### `custom` - Custom Query Flag
**Purpose**: Indicates manually edited Advanced queries
**Values**: `0` (generated), `1` (custom)
**Default**: `0` for Basic, `1` for Advanced
**Example**: `?custom=1`

### `limit` - Result Limit
**Purpose**: Sets LIMIT clause for Basic mode
**Values**: Positive integers (1-10000)
**Default**: `200`
**Example**: `?limit=500`

## 🌐 Endpoint Parameters

### `service` - SPARQL Endpoint
**Purpose**: Specifies the SPARQL endpoint URL
**Format**: Full HTTPS URL
**Default**: `https://demo.openlinksw.com/sparql`
**Example**: `?service=https%3A//query.wikidata.org/sparql`

### `urlfmt` - URL Format
**Purpose**: Controls how IRIs are opened
**Values**: `default`, `virtuoso`
**Default**: `default`
**Example**: `?urlfmt=virtuoso`

### `describe` - Describe Base
**Purpose**: Custom entity description service URL
**Format**: URL template with `{uri}` placeholder
**Example**: `?describe=https%3A//example.com/describe/%3Furi%3D`

## 🎨 Visualization Parameters

### `labels` - Friendly Labels
**Purpose**: Enables human-readable labels
**Values**: `0` (disabled), `1` (enabled)
**Default**: `1`
**Example**: `?labels=0`

### `lang` - Preferred Language
**Purpose**: Language preference for labels
**Values**: ISO language codes (`en`, `fr`, `de`, etc.)
**Default**: `en`
**Example**: `?lang=fr`

### `hideTypes` - Hide Type Relationships
**Purpose**: Hides `rdf:type` edges
**Values**: `0` (show), `1` (hide)
**Default**: `0`
**Example**: `?hideTypes=1`

### `annot` - Edge Annotations
**Purpose**: Controls edge display style
**Values**: `icons`, `names`
**Default**: `icons`
**Example**: `?annot=names`

## 🔍 Filter Parameters

### `types` - RDF Type Filter
**Purpose**: Comma-separated list of allowed rdf:types
**Format**: CURIEs separated by commas
**Example**: `?types=dbo%3AFilm%2Cdbo%3APerson`

### `props` - Property Filter
**Purpose**: Comma-separated list of allowed properties
**Format**: Full IRIs separated by commas
**Example**: `?props=http%3A//dbpedia.org/ontology/creator%2Chttp%3A//www.w3.org/2000/01/rdf-schema%23label`

### `groups` - Node Group Filter
**Purpose**: Comma-separated list of enabled node groups
**Format**: Group names separated by commas
**Values**: `external`, `class`, `category`, `role`, `literal`, `scheme`
**Example**: `?groups=external%2Cliteral%2Cclass`

## ⚡ Physics Parameters

### `chg` - Charge Strength
**Purpose**: Node repulsion force
**Values**: -1000 to 0
**Default**: -600 (auto-adjusted by graph size)
**Example**: `?chg=-800`

### `ld` - Link Distance
**Purpose**: Edge length in pixels
**Values**: 10 to 300
**Default**: 180 (auto-adjusted by graph size)
**Example**: `?ld=220`

### `hover` - Hover Focus
**Purpose**: Enables hover highlighting
**Values**: `0` (disabled), `1` (enabled)
**Default**: `1`
**Example**: `?hover=0`

## 🏷️ Label Parameters

### `lp` - Label Priority
**Purpose**: Custom label predicate priority order
**Format**: Comma-separated predicate CURIEs
**Default**: `skos:prefLabel,rdfs:label,schema:name,schema:title,foaf:name`
**Example**: `?lp=rdfs%3Alabel%2Cskos%3AprefLabel%2Cschema%3Aname`

## 📍 Position Parameters

### `pos` - Node Positions
**Purpose**: Preserves manual node positioning
**Format**: `id:x:y` tuples separated by `|`
**Encoding**: URL-encoded identifiers
**Limit**: Maximum 200 positions to avoid URL length limits
**Example**: `?pos=dbr%3AApple_Inc.%3A150%3A200%7Cdbr%3AGoogle%3A300%3A250`

## 🔐 Authentication Parameters

### Secure Sharing
**Note**: Authentication tokens are NOT shared via URL for security reasons. Users must authenticate separately when opening shared URLs.

## 📝 Complete Example

### Complex Query URL
```
https://sparqlworks.example.com/?q=CONSTRUCT%20%7B%20%3Fmovie%20dbo%3Acreator%20%3Fcreator%3B%20rdfs%3Alabel%20%3FmovieName.%20%7D%20WHERE%20%7B%20%3Fmovie%20dbo%3Acreator%20%3Fcreator%3B%20rdfs%3Alabel%20%3FmovieName.%20FILTER(%3Fcreator%20%3D%20dbr%3ASpike_Lee).%20%7D%20LIMIT%2050&mode=advanced&custom=1&service=https%3A//demo.openlinksw.com/sparql&labels=1&lang=en&hideTypes=0&annot=icons&types=dbo%3AFilm&groups=external%2Cliteral&chg=-700&ld=200&hover=1
```

### Decoded Parameters
- **q**: Full CONSTRUCT query for Spike Lee movies
- **mode**: Advanced mode
- **custom**: Custom query (not auto-generated)
- **service**: OpenLink demo endpoint
- **labels**: Friendly labels enabled
- **lang**: English preferred
- **hideTypes**: Show rdf:type relationships
- **annot**: Icon annotations for edges
- **types**: Only show films
- **groups**: External entities and literals
- **chg**: Charge strength -700
- **ld**: Link distance 200px
- **hover**: Hover focus enabled

## 🛠️ URL Construction

### Manual URL Building
1. **Start with base URL**: `https://sparqlworks.example.com/?`
2. **Add query**: `q=` + URL-encoded SPARQL query
3. **Add endpoint**: `&service=` + encoded endpoint URL
4. **Add settings**: Append other parameters as needed

### Programmatic Generation
```javascript
// Example URL construction
const params = new URLSearchParams();
params.set('q', sparqlQuery);
params.set('service', endpointUrl);
params.set('mode', 'advanced');
params.set('labels', '1');
const shareUrl = `${baseUrl}?${params.toString()}`;
```

### URL Encoding
- **SPARQL queries**: Use `encodeURIComponent()` for full queries
- **IRIs**: Encode special characters in URLs
- **Special characters**: Encode `{}`, `<>`, `|` in complex values
- **Length limits**: Be aware of browser URL length limits (~2000 characters)

## 📋 Parameter Reference Table

| Parameter | Type | Values | Default | Description |
|-----------|------|--------|---------|-------------|
| `q` | Query | URL-encoded SPARQL | - | Complete SPARQL query |
| `mode` | Query | `basic`, `advanced` | `basic` | Query composition mode |
| `custom` | Query | `0`, `1` | Auto | Custom query flag |
| `limit` | Query | 1-10000 | 200 | Basic mode LIMIT |
| `service` | Endpoint | URL | OpenLink demo | SPARQL endpoint |
| `urlfmt` | Endpoint | `default`, `virtuoso` | `default` | IRI opening format |
| `describe` | Endpoint | URL | Auto | Describe service URL |
| `labels` | Display | `0`, `1` | `1` | Friendly labels |
| `lang` | Display | Language code | `en` | Preferred language |
| `hideTypes` | Display | `0`, `1` | `0` | Hide rdf:type edges |
| `annot` | Display | `icons`, `names` | `icons` | Edge annotations |
| `types` | Filter | Comma-separated CURIEs | - | RDF type filter |
| `props` | Filter | Comma-separated IRIs | - | Property filter |
| `groups` | Filter | Comma-separated names | - | Node group filter |
| `chg` | Physics | -1000 to 0 | Auto | Charge strength |
| `ld` | Physics | 10-300 | Auto | Link distance |
| `hover` | Physics | `0`, `1` | `1` | Hover focus |
| `lp` | Labels | Comma-separated CURIEs | Default order | Label priority |
| `pos` | Layout | `id:x:y\|...` | - | Node positions |

## 🔄 URL Synchronization

### Automatic Updates
- **Query changes**: URL updates with new query
- **Setting changes**: Parameters added/modified automatically
- **Mode switches**: Mode parameter updated
- **Filter changes**: Filter parameters synchronized

### Manual Sharing
1. **Configure visualization**: Set up desired state
2. **Click share button**: Link icon next to controls
3. **Copy URL**: Automatically copies to clipboard
4. **Share/Bookmark**: Send to others or save for later

### State Restoration
- **URL loading**: All parameters applied on page load
- **Validation**: Invalid parameters ignored safely
- **Fallbacks**: Missing parameters use defaults
- **Conflicts**: Parameter combinations resolved automatically

## 🐛 Troubleshooting

### URL Too Long
- **Cause**: Large queries or many parameters
- **Solution**: Use shorter queries, reduce parameters
- **Alternative**: Share query separately, configure manually

### Parameters Not Applied
- **Cause**: Invalid parameter values
- **Check**: Verify parameter names and values
- **Debug**: Use browser developer tools

### Encoding Issues
- **Cause**: Improper URL encoding
- **Solution**: Use proper encoding functions
- **Test**: Validate URLs before sharing

### Browser Limits
- **URL length**: ~2000 characters in some browsers
- **Parameter count**: No hard limit, but performance impact
- **Special characters**: Ensure proper encoding

## 🔒 Security Considerations

### Safe Parameters
- **No credentials**: Authentication tokens never in URLs
- **Public data**: Only shareable information included
- **Endpoint validation**: URLs validated before use
- **XSS protection**: Parameters properly sanitized

### Privacy
- **No tracking**: URLs don't contain user-identifiable information
- **Session isolation**: URL state doesn't leak between users
- **Local storage**: Sensitive data stays client-side

---

[← Controls and Settings](Controls-and-Settings.md) | [Next: Technical Details →](Technical-Details.md)