0
# Fragment Extensions
1

2
Enhanced fragment handling for query-like and URI-like fragment operations with configurable prefixes.
3

4
## Fragment Query Extension
5

6
Treat fragments as query-like strings for parameter manipulation.
7

8
### Enhanced Properties
9

10
```javascript { .api }
11
// Configurable prefix for fragment queries (default: "?")
12
URI.fragmentPrefix: string;
13
```
14

15
### Enhanced Instance Methods
16

17
```javascript { .api }
18
/**
19
 * Get or set fragment prefix for this instance
20
 * @param value - New fragment prefix
21
 * @returns Current prefix or URI instance for chaining
22
 */
23
fragmentPrefix(value?: string): string | URI;
24

25
/**
26
 * Enhanced fragment method with query object support
27
 * @param value - Fragment value, true for object return, function for transform
28
 * @param build - Whether to rebuild URI immediately
29
 * @returns Fragment string, object, or URI instance for chaining
30
 */
31
fragment(value?: string | boolean | function, build?: boolean): string | object | URI;
32

33
/**
34
 * Add fragment query parameters
35
 * @param name - Parameter name or object of name-value pairs
36
 * @param value - Parameter value
37
 * @param build - Whether to rebuild URI immediately
38
 * @returns URI instance for chaining
39
 */
40
addFragment(name: string | object, value?: string, build?: boolean): URI;
41
addHash(name: string | object, value?: string, build?: boolean): URI; // Alias
42

43
/**
44
 * Set fragment query parameters
45
 * @param name - Parameter name or object of name-value pairs
46
 * @param value - Parameter value
47
 * @param build - Whether to rebuild URI immediately
48
 * @returns URI instance for chaining
49
 */
50
setFragment(name: string | object, value?: string, build?: boolean): URI;
51
setHash(name: string | object, value?: string, build?: boolean): URI; // Alias
52

53
/**
54
 * Remove fragment query parameters
55
 * @param name - Parameter name to remove
56
 * @param value - Specific value to remove
57
 * @param build - Whether to rebuild URI immediately
58
 * @returns URI instance for chaining
59
 */
60
removeFragment(name: string, value?: string, build?: boolean): URI;
61
removeHash(name: string, value?: string, build?: boolean): URI; // Alias
62
```
63

64
**Fragment Query Usage Examples:**
65

66
```javascript
67
// Import fragment query extension
68
import 'urijs/src/URI.fragmentQuery';
69

70
const uri = new URI('http://example.com/page#section');
71

72
// Configure fragment prefix
73
uri.fragmentPrefix('?'); // Default prefix
74
console.log(uri.fragmentPrefix()); // '?'
75

76
// Set fragment as query-like string
77
uri.fragment('?name=John&age=30');
78
console.log(uri.fragment()); // '?name=John&age=30'
79

80
// Get fragment as object
81
const fragmentObj = uri.fragment(true);
82
console.log(fragmentObj); // { name: 'John', age: '30' }
83

84
// Add fragment parameters
85
uri.addFragment('city', 'NYC')
86
   .addFragment('country', 'USA');
87
console.log(uri.fragment()); // '?name=John&age=30&city=NYC&country=USA'
88

89
// Set fragment parameters (replaces existing)
90
uri.setFragment({
91
  search: 'javascript',
92
  category: 'programming'
93
});
94
console.log(uri.fragment()); // '?search=javascript&category=programming'
95

96
// Remove fragment parameters
97
uri.removeFragment('category');
98
console.log(uri.fragment()); // '?search=javascript'
99

100
// Transform fragment with function
101
uri.fragment(function(data) {
102
  data.timestamp = Date.now();
103
  return data;
104
});
105

106
// Custom fragment prefix
107
uri.fragmentPrefix('!');
108
uri.setFragment('page', '1');
109
console.log(uri.fragment()); // '!page=1'
110
```
111

112
## Fragment URI Extension
113

114
Treat fragments as complete URI strings for nested URI manipulation.
115

116
### Enhanced Properties
117

118
```javascript { .api }
119
// Configurable prefix for fragment URIs (default: "!")
120
URI.fragmentPrefix: string;
121
```
122

123
### Enhanced Instance Methods
124

125
```javascript { .api }
126
/**
127
 * Enhanced fragment method with URI object support
128
 * @param value - Fragment value, true for URI return, URI object to set
129
 * @param build - Whether to rebuild URI immediately
130
 * @returns Fragment string, URI instance, or this URI for chaining
131
 */
132
fragment(value?: string | boolean | URI, build?: boolean): string | URI;
133

134
/**
135
 * Enhanced build method with fragment URI sync
136
 * @param deferBuild - Don't trigger automatic rebuilding
137
 * @returns Complete URI string
138
 */
139
build(deferBuild?: boolean): string;
140
```
141

142
**Fragment URI Usage Examples:**
143

144
```javascript
145
// Import fragment URI extension
146
import 'urijs/src/URI.fragmentURI';
147

148
const uri = new URI('http://example.com/app');
149

150
// Set fragment as URI string
151
uri.fragment('!/page/users?filter=active');
152
console.log(uri.toString()); // 'http://example.com/app#!/page/users?filter=active'
153

154
// Get fragment as URI instance
155
const fragmentUri = uri.fragment(true);
156
console.log(fragmentUri instanceof URI); // true
157
console.log(fragmentUri.pathname()); // '/page/users'
158
console.log(fragmentUri.query()); // 'filter=active'
159

160
// Manipulate fragment URI
161
fragmentUri.addQuery('sort', 'name')
162
           .pathname('/page/users/123');
163

164
// Fragment URI changes are automatically synced
165
console.log(uri.toString()); // 'http://example.com/app#!/page/users/123?filter=active&sort=name'
166

167
// Set fragment URI from another URI instance
168
const newFragmentUri = new URI('/different/path?param=value');
169
uri.fragment(newFragmentUri);
170
console.log(uri.toString()); // 'http://example.com/app#!/different/path?param=value'
171

172
// Complex fragment URI manipulation
173
const complexUri = new URI('http://spa.example.com/');
174
complexUri.fragment('!/app/dashboard');
175

176
const dashboardUri = complexUri.fragment(true);
177
dashboardUri.addQuery('tab', 'analytics')
178
            .addQuery('period', '7d')
179
            .fragment('chart-section');
180

181
console.log(complexUri.toString());
182
// 'http://spa.example.com/#!/app/dashboard?tab=analytics&period=7d#chart-section'
183

184
// Custom fragment URI prefix
185
complexUri.fragmentPrefix('#/');
186
complexUri.fragment('/router/path');
187
console.log(complexUri.toString()); // 'http://spa.example.com/#/router/path'
188
```
189

190
## Combined Usage Patterns
191

192
Using both extensions together for advanced fragment handling.
193

194
**Examples:**
195

196
```javascript
197
// Import both extensions
198
import 'urijs/src/URI.fragmentQuery';
199
import 'urijs/src/URI.fragmentURI';
200

201
// Start with basic URI
202
const appUri = new URI('http://myapp.com/');
203

204
// Use fragment as query-like for simple state
205
appUri.fragmentPrefix('?');
206
appUri.setFragment({
207
  modal: 'login',
208
  returnTo: '/dashboard'
209
});
210
console.log(appUri.toString()); // 'http://myapp.com/#?modal=login&returnTo=/dashboard'
211

212
// Switch to URI-like for complex routing
213
appUri.fragmentPrefix('!');
214
const routeUri = new URI('/app/users/123');
215
routeUri.addQuery('tab', 'profile');
216
appUri.fragment(routeUri);
217
console.log(appUri.toString()); // 'http://myapp.com/#!/app/users/123?tab=profile'
218

219
// Access and modify the fragment URI
220
const currentRoute = appUri.fragment(true);
221
currentRoute.segment(2, '456'); // Change user ID
222
currentRoute.setQuery('tab', 'settings'); // Change tab
223

224
console.log(appUri.toString()); // 'http://myapp.com/#!/app/users/456?tab=settings'
225

226
// Detect fragment type
227
function getFragmentType(uri) {
228
  const frag = uri.fragment();
229
  if (frag.startsWith('?')) return 'query';
230
  if (frag.startsWith('!')) return 'uri';
231
  return 'simple';
232
}
233

234
console.log(getFragmentType(appUri)); // 'uri'
235
```