Html Slicer #

The html_slicer package is a lightweight and efficient utility for slicing HTML strings while preserving the structure and validity of the HTML. It is designed for both Dart and Flutter projects, making it ideal for scenarios where you need to truncate HTML content to a specified maximum length of visible characters without breaking the HTML tags or structure. This package is particularly useful for applications that handle rich text or HTML content, such as web apps, mobile apps, or server-side Dart projects.

Features #

• Preserves HTML Structure: Ensures the HTML remains valid by properly closing open tags and handling self-closing tags.
• Customizable Length: Slice HTML content to a specified maximum number of visible characters.
• Preserve Newlines: Optionally preserve newline characters or replace them with spaces.
• Handles Special Tags: Preserves entire blocks of specific tags (e.g., <img>, <video>, <audio>, etc.) without counting their content toward the visible character limit.
• Cross-Platform: Works seamlessly in Dart projects (e.g., server-side or CLI apps) and Flutter projects (mobile, web, and desktop).
• Lightweight and Fast: Optimized for performance, making it suitable for both small and large-scale applications.

Installation 💻 #

❗ In order to start using Html Slicer you must have the Dart SDK installed on your machine.

For Dart Projects #

Run the following command in your terminal:

dart pub add html_slicer

For Flutter Projects #

Run the following command in your terminal:

flutter pub add html_slicer

Manual Installation #

Alternatively, you can manually add the html_slicer package to your pubspec.yaml file under dependencies:

dependencies:
  html_slicer: ^0.1.0

Then, run the following command to install the package:

• For Dart projects:

  dart pub get
  

• For Flutter projects:

  flutter pub get
  

Importing the Package #

Once installed, import the package in your Dart or Flutter code:

import 'package:html_slicer/html_slicer.dart';

Usage #

The package provides a single method, sliceHtml, which can be used to slice HTML strings while preserving their structure.

Method Signature #

String sliceHtml(String html,
    int maxLength, {
      bool preserveNewlines = true,
    });

Parameters #

• html: The input HTML string to be sliced.
• maxLength: The maximum number of visible characters to retain in the output.
• preserveNewlines: If true, newline characters in the input HTML are preserved in the output. If false, newline characters are replaced with spaces.

Returns #

• A valid HTML string truncated to the specified number of visible characters.

Example in Dart #

import 'package:html_slicer/html_slicer.dart';

void main() {
  String htmlContent = '''
    <div>
      <h1>Hello, World!</h1>
      <p>This is a <strong>sample</strong> HTML content.</p>
      <img src="image.jpg" alt="Sample Image">
    </div>
  ''';

  // Slice the HTML to a maximum of 20 visible characters
  String slicedHtml = sliceHtml(htmlContent, 20, preserveNewlines: true);

  print(slicedHtml);
}

Output #

The output will be a valid HTML string truncated to the specified number of visible characters:

<div>
    <h1>Hello, World!</h1>
    <p>This is a <strong>sample</strong> HTML...</p>
    <img src="image.jpg" alt="Sample Image">
</div>

Example in Flutter #

If you're using Flutter, you can use the html_slicer package to truncate HTML content for display in a Text widget or other UI components:

import 'package:flutter/material.dart';
import 'package:html_slicer/html_slicer.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    String htmlContent = '''
      <div>
        <h1>Hello, World!</h1>
        <p>This is a <strong>sample</strong> HTML content.</p>
        <img src="image.jpg" alt="Sample Image">
      </div>
    ''';

    String slicedHtml = sliceHtml(htmlContent, 20, preserveNewlines: true);

    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('HTML Slicer Example')),
        body: Padding(
          padding: EdgeInsets.all(16.0),
          child: Text(slicedHtml),
        ),
      ),
    );
  }
}

Use Cases #

• Truncating Rich Text: Display a preview of HTML content (e.g., blog posts, articles) without breaking the structure.
• Social Media Previews: Generate shortened HTML snippets for sharing on social media platforms.
• Email Clients: Truncate HTML emails while preserving their formatting and embedded media.
• Server-Side Dart: Use in backend applications to process and serve truncated HTML content.
• CLI Tools: Integrate into Dart command-line tools for HTML manipulation.

Continuous Integration 🤖 #

Html Slicer comes with a built-in GitHub Actions workflow powered by Very Good Workflows but you can also add your preferred CI/CD solution.

Out of the box, on each pull request and push, the CI formats, lints, and tests the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses Very Good Analysis for a strict set of analysis options used by our team. Code coverage is enforced using the Very Good Workflows.

Running Tests � #

To run all unit tests:

dart pub global activate coverage 1.2.0
dart test --coverage=coverage
dart pub global run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info

To view the generated coverage report you can use lcov.

# Generate Coverage Report
genhtml coverage/lcov.info -o coverage/

# Open Coverage Report
open coverage/index.html

Contributing #

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository. If you'd like to contribute code, feel free to fork the repository and submit a pull request.

Steps to Contribute #

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Make your changes and ensure all tests pass.
4. Submit a pull request with a detailed description of your changes.

License #

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments #

• Thanks to the Dart and Flutter communities for their continuous support and contributions.