Skip to content

Commit 64c5fa9

Browse files
JabenJaben
authored
Merge pull request #64 from ChangemakerStudios/feature/readme-improvement
Improve and update README with current API examples
2 parents adc20e3 + 945706b commit 64c5fa9

1 file changed

Lines changed: 188 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 188 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,15 @@ public void ConfigureServices(IServiceCollection services)
8484

8585
```
8686
# Using GotenbergSharpClient
87-
*See the [linqPad folder](linqpad/)* for complete examples.
87+
*See the [linqPad folder](linqpad/)* for complete examples.
88+
89+
## Required Using Statements
90+
```csharp
91+
using Gotenberg.Sharp.API.Client;
92+
using Gotenberg.Sharp.API.Client.Domain.Builders;
93+
using Gotenberg.Sharp.API.Client.Domain.Builders.Faceted;
94+
using Gotenberg.Sharp.API.Client.Domain.Requests.Facets; // For Cookie, etc.
95+
```
8896

8997
### Html To Pdf
9098
*With embedded assets:*
@@ -139,13 +147,14 @@ public async Task<Stream> CreateFromUrl(string headerPath, string footerPath)
139147
}
140148
```
141149
## Merge Office Docs
142-
*Merges office documents and configures the request time-out:*
150+
*Merges office documents:*
143151

144152
```csharp
145153
public async Task<Stream> DoOfficeMerge(string sourceDirectory)
146154
{
147155
var builder = new MergeOfficeBuilder()
148-
.WithAsyncAssets(async a => a.AddItems(await GetDocsAsync(sourceDirectory)));
156+
.WithAsyncAssets(async a => a.AddItems(await GetDocsAsync(sourceDirectory)))
157+
.SetPdfFormat(LibrePdfFormats.A2b);
149158

150159
var request = await builder.BuildAsync();
151160
return await _sharpClient.MergeOfficeDocsAsync(request);
@@ -174,6 +183,92 @@ public async Task<Stream> CreateFromMarkdown()
174183
return await _sharpClient.HtmlToPdfAsync(request);
175184
}
176185
```
186+
### Working with Cookies
187+
*Add cookies to the Chromium cookie jar for authenticated requests (v2.8.1+):*
188+
189+
```csharp
190+
public async Task<Stream> CreatePdfWithCookies()
191+
{
192+
var builder = new UrlRequestBuilder()
193+
.SetUrl("https://example.com/protected")
194+
.SetConversionBehaviors(b =>
195+
{
196+
b.AddCookie(new Cookie
197+
{
198+
Name = "session_token",
199+
Value = "abc123xyz",
200+
Domain = "example.com",
201+
Path = "/",
202+
Secure = true,
203+
HttpOnly = true,
204+
SameSite = "Lax"
205+
});
206+
})
207+
.WithPageProperties(pp => pp.UseChromeDefaults());
208+
209+
var request = await builder.BuildAsync();
210+
return await _sharpClient.UrlToPdfAsync(request);
211+
}
212+
```
213+
214+
### Document Metadata
215+
*Add custom metadata to your PDFs (v2.6+):*
216+
217+
```csharp
218+
public async Task<Stream> CreatePdfWithMetadata()
219+
{
220+
var builder = new HtmlRequestBuilder()
221+
.AddDocument(doc => doc.SetBody("<html><body><h1>Document with Metadata</h1></body></html>"))
222+
.SetConversionBehaviors(b =>
223+
{
224+
b.SetMetadata(new Dictionary<string, object>
225+
{
226+
{ "Author", "John Doe" },
227+
{ "Title", "My Document" },
228+
{ "Subject", "Important Report" },
229+
{ "Keywords", "report, pdf, gotenberg" }
230+
});
231+
})
232+
.WithPageProperties(pp => pp.UseChromeDefaults());
233+
234+
var request = await builder.BuildAsync();
235+
return await _sharpClient.HtmlToPdfAsync(request);
236+
}
237+
```
238+
239+
### PDF Format Conversion
240+
*Convert PDFs to PDF/A formats (v2.8+):*
241+
242+
```csharp
243+
public async Task<Stream> ConvertToPdfA(string pdfPath)
244+
{
245+
var builder = new PdfConversionBuilder()
246+
.WithPdfs(b => b.AddItem("document.pdf", File.ReadAllBytes(pdfPath)))
247+
.SetPdfFormat(LibrePdfFormats.A2b);
248+
249+
var request = await builder.BuildAsync();
250+
return await _sharpClient.ConvertPdfDocumentsAsync(request);
251+
}
252+
```
253+
254+
### Single Page Output
255+
*Generate a single-page PDF from multi-page content (v2.8.1+):*
256+
257+
```csharp
258+
public async Task<Stream> CreateSinglePagePdf()
259+
{
260+
var builder = new UrlRequestBuilder()
261+
.SetUrl("https://www.example.com")
262+
.WithPageProperties(pp =>
263+
{
264+
pp.UseChromeDefaults()
265+
.SetSinglePage(true);
266+
});
267+
268+
var request = await builder.BuildAsync();
269+
return await _sharpClient.UrlToPdfAsync(request);
270+
}
271+
```
177272
### Webhook
178273
*All request types support webhooks*
179274

@@ -272,4 +367,93 @@ async Task<Stream> ExecuteRequestsAndMerge(IEnumerable<UrlRequest> requests)
272367
var request = mergeBuilder.Build();
273368
return await _sharpClient.MergePdfsAsync(request);
274369
}
275-
```
370+
```
371+
372+
## Advanced Features
373+
374+
### PDF/UA Support for HTML Conversions
375+
*Enable Universal Access for accessible PDFs from HTML (v2.4+):*
376+
377+
```csharp
378+
public async Task<Stream> CreateAccessiblePdf()
379+
{
380+
var builder = new HtmlRequestBuilder()
381+
.AddDocument(doc => doc.SetBody("<html><body><h1>Accessible Document</h1></body></html>"))
382+
.SetConversionBehaviors(b => b.SetPdfUa(true))
383+
.WithPageProperties(pp => pp.UseChromeDefaults());
384+
385+
var request = await builder.BuildAsync();
386+
return await _sharpClient.HtmlToPdfAsync(request);
387+
}
388+
```
389+
390+
### PDF/UA for PDF Conversions
391+
*Enable Universal Access when converting PDFs to PDF/A (v2.4+):*
392+
393+
```csharp
394+
public async Task<Stream> ConvertToAccessiblePdfA(string pdfPath)
395+
{
396+
var builder = new PdfConversionBuilder()
397+
.WithPdfs(b => b.AddItem("document.pdf", File.ReadAllBytes(pdfPath)))
398+
.SetPdfFormat(LibrePdfFormats.A2b)
399+
.EnablePdfUa(true);
400+
401+
var request = await builder.BuildAsync();
402+
return await _sharpClient.ConvertPdfDocumentsAsync(request);
403+
}
404+
```
405+
406+
### Flatten PDFs
407+
*Flatten PDF forms and annotations (v2.8+):*
408+
409+
```csharp
410+
public async Task<Stream> FlattenPdf(string pdfPath)
411+
{
412+
var builder = new PdfConversionBuilder()
413+
.WithPdfs(b => b.AddItem("form.pdf", File.ReadAllBytes(pdfPath)))
414+
.EnableFlatten(true);
415+
416+
var request = await builder.BuildAsync();
417+
return await _sharpClient.ConvertPdfDocumentsAsync(request);
418+
}
419+
```
420+
421+
### Skip Network Idle Event
422+
*Speed up conversions by skipping network idle wait (Gotenberg v8+ only):*
423+
424+
```csharp
425+
public async Task<Stream> FastConversion()
426+
{
427+
var builder = new UrlRequestBuilder()
428+
.SetUrl("https://example.com")
429+
.SetConversionBehaviors(b => b.SkipNetworkIdleEvent())
430+
.WithPageProperties(pp => pp.UseChromeDefaults());
431+
432+
var request = await builder.BuildAsync();
433+
return await _sharpClient.UrlToPdfAsync(request);
434+
}
435+
```
436+
437+
### Custom Page Properties
438+
*Fine-tune page dimensions and properties:*
439+
440+
```csharp
441+
public async Task<Stream> CustomPageProperties()
442+
{
443+
var builder = new HtmlRequestBuilder()
444+
.AddDocument(doc => doc.SetBody("<html><body><h1>Custom Page</h1></body></html>"))
445+
.WithPageProperties(pp =>
446+
{
447+
pp.SetPaperSize(PaperSizes.Letter)
448+
.SetMargins(Margins.Normal)
449+
.SetScale(0.95)
450+
.SetLandscape()
451+
.SetPrintBackground(true)
452+
.SetGenerateDocumentOutline(true)
453+
.SetOmitBackground(false);
454+
});
455+
456+
var request = await builder.BuildAsync();
457+
return await _sharpClient.HtmlToPdfAsync(request);
458+
}
459+
```

0 commit comments

Comments
 (0)