Commit a86e9a3b authored by Jochum van der Ploeg's avatar Jochum van der Ploeg 🤔
Browse files

Preparing for initial release

parent 6c7a6d1b
Pipeline #320611026 passed with stages
in 5 minutes and 37 seconds
......@@ -4,6 +4,7 @@ stages:
- lint
- test
- publish
- deploy
dartdoc:
stage: lint
......@@ -121,3 +122,20 @@ pub_dev_publish:
except:
refs:
- branches
pages:
stage: deploy
script:
- cd example/ || exit 1
- flutter pub get
- flutter build web
- cp -r build/web ../public
artifacts:
paths:
- public
only:
refs:
- /^v.*$/
except:
refs:
- branches
\ No newline at end of file
<!-- When reporting a bug, please read this complete template and fill all the questions in order to get a better response -->
# Current bug behaviour
<!-- What is the current behaviour that you see? -->
# Expected behaviour
<!-- What behaviour did you expect? -->
# Steps to reproduce
<!-- This one is very important, please be very precise in how we can reproduce this bug -->
<!-- If possible please report steps based on the example from this plugin! -->
# Flutter doctor output
<!-- Execute in a terminal and put output into code block below -->
```
Output of: flutter doctor -v
```
# More environment information
<!--
Create a list of more environment information, like:
* Plugin version: 0.0.1
-->
# Log information
<!-- If you have any debug / error logging, please fill it here within the code block below -->
```
Enter log information in this code block
```
# More information
<!-- Do you have any other usefull information about this bug report? Please write it down here -->
<!-- Possible helpful information: references to other sites/repositories -->
<!-- DO NOT CHANGE ANYTHING BELOW THIS LINE -->
/label ~"type::bug"
<!-- When reporting a feature, please read this complete template and fill all the questions in order to get a better response -->
# Problem to solve
<!-- Which problem would be solved with this feature? -->
# Proposal
<!-- What do you propose as a solution? Add as much information as you can! -->
# More information
<!-- Do you have any other usefull information about this feature report? Please write it down here -->
<!-- Possible helpful information: references to other sites/repositories -->
<!-- DO NOT CHANGE ANYTHING BELOW THIS LINE -->
/label ~"type::feature"
<!-- When reporting a improvement, please read this complete template and fill all the questions in order to get a better response -->
# What could be improved
<!-- What part of the code/functionality could be improved? -->
# Why should this be improved
<!-- Why is this necessary to get improved? -->
# Any risks?
<!-- Are there any risks in improving this? Will the API change? Will other functionality change? -->
# More information
<!-- Do you have any other usefull information about this improvement report? Please write it down here -->
<!-- Possible helpful information: references to other sites/repositories -->
<!-- DO NOT CHANGE ANYTHING BELOW THIS LINE -->
/label ~"type::improvement"
# Contributing Guidelines
If you're interested in contributing to this project, here are a few ways to do so:
### Bug fixes
* If you find a bug, please first report it using [Gitlab issues](https://gitlab.com/wolfenrain/flavor_text/issues/new).
* Issues that have already been identified as a bug will be labelled ~"type::bug" .
* If you'd like to submit a fix for a bug, send a [Merge Request](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#merging-upstream) from your own fork, also read the [How To](#how-to) and [Development Guidelines](#development-guidelines).
* Include a test that isolates the bug and verifies that it was fixed.
* Also update the example and documentation if necessary.
### New Features
* If you'd like to add a feature to the library that doesn't already exist, feel free to describe the feature in a new [Gitlab issue](https://gitlab.com/wolfenrain/flavor_text/issues/new).
* Issues that have been identified as a feature request will be labelled ~"type::feature".
* If you'd like to implement the new feature, please wait for feedback from the project maintainers before spending too much time writing the code. In some cases, enhancements may not align well with the project objectives at the time.
* Implement your code and please read the [How To](#how-to) and [Development Guidelines](#development-guidelines).
* Also update the example and documentation where needed.
### Documentation & Miscellaneous
* If you think the documentation could be clearer, or you have an alternative implementation of something that may have more advantages, we would love to hear it.
* As always first file a report in a [Gitlab issue](https://gitlab.com/wolfenrain/flavor_text/issues/new).
* Issues that have been identified as a documentation change will be labelled ~"type::documentation".
* Implement the changes to the documentation, please read the [How To](#how-to) and [Development Guidelines](#development-guidelines).
# Requirements
For a contribution to be accepted:
* Take note of the [Development Guidelines](#development-guidelines)
* Code must follow existing styling conventions
* Commit message should start with a [issue number](#how-to) and should also be descriptive.
If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the issue. You can still continue to add more commits to the branch you have sent the Merge Request from.
# How To
* First of all [file an bug or feature report](https://gitlab.com/wolfenrain/flavor_text/issues/new) on this repository.
* [Fork the project](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) on Gitlab
* Clone the forked repository to your local development machine (e.g. `git clone https://gitlab.com/<YOUR_GITLAB_USER>/flavor_text.git`)
* Run `flutter pub get` in the cloned repository to get all the dependencies
* Create a new local branch based on issue number from first step (e.g. `git checkout -b 12-new-feature`)
* Make your changes
* When committing your changes, make sure to start the commit message with `#<issue-number>` (e.g. `git commit -m '#12 - New Feature added'`)
* Push your new branch to your own fork into the same remote branch (e.g. `git push origin 12-new-feature`)
* On Gitlab goto the [merge request page](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#merging-upstream) on your own fork and create a merge request to this reposistory
# Development Guidelines
* Documentation should be updated.
* Example application should be updated.
* Format the Flutter code accordingly.
* Note the [`analysis_options.yaml`](https://gitlab.com/wolfenrain/flavor_text/-/blob/master/analysis_options.yaml) and write code as stated in this file
# Test generating of `dartdoc`
* On local development make sure the `dartdoc` program is mentioned in your `$PATH`
* `dartdoc` can be found here: `<FLUTTER_INSTALL_DIR>/bin/cache/dart-sdk/bin/dartdoc`
* Generate docs with the following command: `dartdoc --no-auto-include-dependencies --quiet`
* Output will be placed into `doc/api/`
......@@ -9,6 +9,37 @@ A lightweight and fully customisable text parser for Flutter.
> Flavor text is often the last text on a card or on the rear of a toy card or
package, and is usually printed in italics or written between quotes to
distinguish it from game-affecting text.
> &mdash; <cite>[Flavor Text - Wikipedia](https://en.wikipedia.org/wiki/Flavor_text)</cite>
Writing rich text in Flutter can be a pain:
```dart
Text.rich(
TextSpan(
text: 'Welcome',
children: [
TextSpan(
text: 'To my amazing',
children: [
TextSpan(
text: 'App!',
style: TextStyle(fontWeight: FontWeight.bold),
),
],
style: TextStyle(color: Color(0xFFFF0000)),
)
],
),
),
```
But writing rich text with Flavor Text is simply:
```dart
FlavorText(
'Welcome <style color="0xFFFF0000">to my amazing <style fontWeight="bold">App!</style></style>',
),
```
## Installation
......@@ -20,6 +51,8 @@ Add `flavor_text` as a dependency in your pubspec.yaml file
See the [API Docs](https://pub.dev/documentation/flavor_text/latest/flavor_text/flavor_text-library.html)
for detailed information on how to use Flavor Text.
See the interactive example for of all the things that you can do with Flavor
Text: [Flavor Text example](https://wolfenrain.gitlab.io/flavor_text/#/)
## Usage
......@@ -27,27 +60,18 @@ Flavor Text allows you to create custom rich text using strings. You don't have
to mess with `Text.rich` and `TextSpan`'s. Just you, your text and a single
widget.
### Basic Usage
See the [Basic Usage](#basic-usage) section for an introduction or jump directly to the [Advanced Usage](#advanced-usage) section.
Before you can start using Flavor Text you will need to register the Tag
components that you are gonna use.
### Basic Usage
Flavor Text uses these Tag components to build your custom rich text. Flavor
Flavor Text uses Tag components to build your custom rich text. These Tag
components make the magic possible. Flavor
Text comes with a few [default Tag components](https://gitlab.com/wolfenrain/flavor_text/-/tree/main/lib/src/tags).
To use the default tags you need to register them first, thankfully Flavor Text
has a method for that:
You can register custom Tag components, see the [Advanced Usage](#advanced-usage)
section.
```dart
void main() {
FlavorText.registerDefaultTags();
...
}
```
Now that the default tags are registered you can start using them. First you
need to define the rich text you want to use as a string:
Let's start with defining the rich text you want to use as a string:
```dart
final richText = 'Hello <style color="0xFFFF0000">world</style>';
......@@ -59,15 +83,15 @@ string in our Widget tree like so:
```dart
@override
Widget build(BuildContext context) {
return Column(
children: [
...
FlavorText(richText),
...
],
);
return Column(
children: [
...
FlavorText(richText),
...
],
);
}
```
......@@ -78,18 +102,18 @@ and text alignment:
```dart
FlavorText(
richText,
style: TextStyle(
color: Colors.green,
),
textAlign: TextAlign.center,
richText,
style: TextStyle(
color: Colors.green,
),
textAlign: TextAlign.center,
)
```
You can also nest multiple tags, example:
```dart
final richText = 'Hello <style color="0xFFFF0000">world and <style weight="bold">you</style></style>!';
final richText = 'Hello <style color="0xFFFF0000">world and <style fontWeight="bold">you</style></style>!';
```
### Advanced Usage
......@@ -99,13 +123,10 @@ something specifically tailored to your usecase, you can easily create and
register your own tag.
First you need to create your own tag, for this example we will create a tag
that add the `Icons.help` icon in our text.
that adds the `Icons.help` icon to our text:
```dart
class HelpTag extends Tag {
@override
List<String> get supportedProperties => [];
@override
InlineSpan build(BuildContext context) {
return WidgetSpan(child: Icon(Icons.help));
......@@ -113,16 +134,16 @@ class HelpTag extends Tag {
}
```
You can then register it:
You can then register it by calling the `FlavorText.registerTag`:
```dart
void main() {
...
...
// The first argument is the tag key.
FlavorText.registerTag('help', () => HelpTag());
// The first argument is the tag key.
FlavorText.registerTag('help', () => HelpTag());
...
...
}
```
......@@ -131,6 +152,41 @@ Now that our new tag is registered we can use it in our text:
```dart
FlavorText('This text will end in an icon <help></help>');
// Or using self-closing syntax
// Or using a self-closing tag.
FlavorText('This text will end in an icon <help/>');
```
If we want to add some properties to our tag for more fine tuned control, for
example we want to be able to change the color:
```dart
class HelpTag extends Tag {
@override
List<Property> get supportedProperties => [Property('color')];
@override
InlineSpan build(BuildContext context) {
final colorValue = properties['color']?.value;
var color = Colors.black;
if (colorValue != null) {
color = Color(int.parse(colorValue));
}
return WidgetSpan(
child: Icon(
Icons.help,
color: color,
),
);
}
}
```
The `supportedProperties` define which properties are allowed on our tag, and we
can read the value by accessing the `properties` field.
Now that we have properties we can use these in our tag:
```dart
FlavorText('This text will end in an icon <help color="0xFF00FF00"/>');
```
\ No newline at end of file
dartdoc:
include: ['flavor_text']
exclude: ['FlavorText']
errors:
- ambiguous-doc-reference
- ambiguous-reexport
......@@ -16,4 +17,6 @@ dartdoc:
- private-api-across-packages
- unknown-file
- unknown-macro
warnings:
# Sadly there are unresolved reference in StatelessWidget and we inherit those.
- unresolved-doc-reference
#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
#include "Generated.xcconfig"
#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
#include "Generated.xcconfig"
# Uncomment this line to define a global platform for your project
# platform :ios, '9.0'
# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
ENV['COCOAPODS_DISABLE_STATS'] = 'true'
project 'Runner', {
'Debug' => :debug,
'Profile' => :release,
'Release' => :release,
}
def flutter_root
generated_xcode_build_settings_path = File.expand_path(File.join('..', 'Flutter', 'Generated.xcconfig'), __FILE__)
unless File.exist?(generated_xcode_build_settings_path)
raise "#{generated_xcode_build_settings_path} must exist. If you're running pod install manually, make sure flutter pub get is executed first"
end
File.foreach(generated_xcode_build_settings_path) do |line|
matches = line.match(/FLUTTER_ROOT\=(.*)/)
return matches[1].strip if matches
end
raise "FLUTTER_ROOT not found in #{generated_xcode_build_settings_path}. Try deleting Generated.xcconfig, then run flutter pub get"
end
require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelper'), flutter_root)
flutter_ios_podfile_setup
target 'Runner' do
use_frameworks!
use_modular_headers!
flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
end
end
import 'package:flavor_text/flavor_text.dart';
import 'package:dashbook/dashbook.dart';
import 'package:flavor_text/flavor_text.dart' hide Property;
import 'package:flutter/material.dart';
import 'package:flutter_highlight/flutter_highlight.dart';
/// Tag that adds an [Icons.help] icon in text.
class HelpTag extends Tag {
@override
List<String> get supportedProperties => [];
@override
InlineSpan build(BuildContext context) {
return WidgetSpan(child: Icon(Icons.help));
}
}
final lightTheme = {
'root': TextStyle(color: Colors.black, backgroundColor: Color(0x00000000)),
'string': TextStyle(color: Color(0xff50a14f)),
'attr': TextStyle(color: Color(0xff986801)),
'tag': TextStyle(color: Color(0xffe45649)),
};
final darkTheme = {
...lightTheme,
'root': lightTheme['root']!.copyWith(color: Colors.white),
};
void main() {
FlavorText.registerDefaultTags();
FlavorText.registerTag('help', () => HelpTag());
final dashbook = Dashbook.dualTheme(
title: 'flavor_text examples',
light: ThemeData.light(),
dark: ThemeData.dark(),
initWithLight: false,
);
final tagsStory = dashbook.storiesOf('Tags');
runApp(MyApp());
}
tagsStory.add('style', (context) {
final fontWeight = context.listProperty(
'fontWeight',
'normal',
StyleTag.fontWeights.keys.toList(),
);
final fontSize = context.numberProperty('fontSize', 24);
final letterSpacing = context.numberProperty('letterSpacing', 2);
final color = context.colorProperty('color', Colors.blue);
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flavor Text Example',
home: MyHomePage(),
return build('''<style
color="0x${color.value.toRadixString(16)}"
fontSize="$fontSize"
letterSpacing="$letterSpacing"
fontWeight="$fontWeight">
Hello world
</style>''');
}).add('icon', (context) {
final icon = context.listProperty('icon', 'home', [
'home',
'work',
'motorcycle',
]);
final fontWeight = context.listProperty(
'fontWeight',
'normal',
StyleTag.fontWeights.keys.toList(),
);
}
}
final fontSize = context.numberProperty('fontSize', 24);
final letterSpacing = context.numberProperty('letterSpacing', 2);
final color = context.colorProperty('color', Colors.blue);
return build('''<icon
color="0x${color.value.toRadixString(16)}"
fontSize="$fontSize"
letterSpacing="$letterSpacing"
fontWeight="$fontWeight">
$icon
</icon>''');
}).add('rainbow', (context) {
return build('<rainbow>Hello world</rainbow>');
});
class MyHomePage extends StatefulWidget {
@override
_MyHomePageState createState() => _MyHomePageState();
runApp(dashbook);
}
class _MyHomePageState extends State<MyHomePage> {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('Flavor Text Example')),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
FlavorText('Hello <style color="0xFFFF0000">world</style>!'),
FlavorText('Hello <help/> world!'),
],
),
),
);
}
Widget build(String text) {
return Builder(
builder: (context) {
final isLight = Theme.of(context).brightness == Brightness.light;
return Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
HighlightView(
text,
language: 'xml',
theme: isLight ? lightTheme : darkTheme,
),
SizedBox(height: 16),
FlavorText(text),
],
);
},
);
}
#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
#include "ephemeral/Flutter-Generated.xcconfig"
#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
#include "ephemeral/Flutter-Generated.xcconfig"
......@@ -5,6 +5,10 @@
import FlutterMacOS
import Foundation
import shared_preferences_macos
import url_launcher_macos
func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
SharedPreferencesPlugin.register(with: registry.registrar(forPlugin: "SharedPreferencesPlugin"))
UrlLauncherPlugin.register(with: registry.registrar(forPlugin: "UrlLauncherPlugin"))
}
platform :osx, '10.11'
# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
ENV['COCOAPODS_DISABLE_STATS'] = 'true'
project 'Runner', {
'Debug' => :debug,
'Profile' => :release,
'Release' => :release,
}
def flutter_root
generated_xcode_build_settings_path = File.expand_path(File.join('..', 'Flutter', 'ephemeral', 'Flutter-Generated.xcconfig'), __FILE__)
unless File.exist?(generated_xcode_build_settings_path)
raise "#{generated_xcode_build_settings_path} must exist. If you're running pod install manually, make sure \"flutter pub get\" is executed first"
end
File.foreach(generated_xcode_build_settings_path) do |line|
matches = line.match(/FLUTTER_ROOT\=(.*)/)
return matches[1].strip if matches
end
raise "FLUTTER_ROOT not found in #{generated_xcode_build_settings_path}. Try deleting Flutter-Generated.xcconfig, then run \"flutter pub get\""
end
require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelper'), flutter_root)
flutter_macos_podfile_setup
target 'Runner' do
use_frameworks!
use_modular_headers!
flutter_install_all_macos_pods File.dirname(File.realpath(__FILE__))
end
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_macos_build_settings(target)
end
end