sitegeist / chitchat
Random texts to be used as styleguide props
Installs: 5 576
Dependents: 3
Suggesters: 0
Security: 0
Stars: 2
Watchers: 4
Forks: 0
Open Issues: 0
Type:neos-package
Requires
- neos/fusion: ~8.0 || 8.2.x-dev || dev-main || dev-master
Requires (Dev)
- php: ^8.1
- phpstan/phpstan: ^1.8
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.7
This package is auto-updated.
Last update: 2024-10-25 12:08:19 UTC
README
Deterministic randomized text generator for styleguide props
Presentational components for the monocle styleguide tend to have longish @styleguide.props that are hard to maintain, tend to overshadow the actual component and often do not provide enough diversion to actually test different text lengths.
ChitChat generates pseudo random texts that can be used in styleguide props. The texts are generated uniquely for each insertion point (fusion path) using pseudo random numbers.
The implementation was inspired by the js library getlorem https://github.com/lukehaas/getlorem/. Also the word list we use started as a copy from getlorem.
Authors & Sponsors
- Melanie Wüst - wuest@sitegeist.de
- Martin Ficzel - ficzel@sitegeist.de
The development and the public-releases of this package is generously sponsored by our employer http://www.sitegeist.de.
Installation
Sitegeist.ChitChat is available via packagist and can be installed with the command composer require sitegeist/chitchat
.
We use semantic-versioning so every breaking change will increase the major-version number.
Usage
The Line
and Text
prototypes generate a pseudo random text.
The text is much longer and structured as multiple sentences.
Both prototypes allow to enable formatting via links
, strong
and em
.
prototype(Sitegeist.ChitChat:CardExample) < prototype(Neos.Fusion:Component) {
@styleguide {
title = "ChitChat CardExample"
props {
# a short text without formatting
title = Sitegeist.ChitChat:Line
# a textblock with multiple sentences and some formatting
description = Sitegeist.ChitChat:Text {
length = 250
link = true
strong = true
em = true
}
}
}
title = null
description = null
renderer = afx`
<div>
<h3>{props.title}</p>
<p>{props.description}</p>
</div>
`
}
For simulating longer and formatted texts chitchat brings prototypes to simulate
Html Headings, Paragraphs and Lists. Those allow to specify the expected structure
of the content
prop. Together with the afx syntax this allows to efficiently mock
larger texts.
prototype(Sitegeist.ChitChat:TextExample) < prototype(Neos.Fusion:Component) {
@styleguide {
title = "ChitChat TextExample"
props {
# a block with mutltiple headlines paragraphs and lists
content = afx`
<Sitegeist.ChitChat:H1 />
<Sitegeist.ChitChat:H2 />
<Sitegeist.ChitChat:P />
<Sitegeist.ChitChat:P />
<Sitegeist.ChitChat:P />
<Sitegeist.ChitChat:H3 />
<Sitegeist.ChitChat:UL />
<Sitegeist.ChitChat:H3 />
<Sitegeist.ChitChat:OL />
`
}
}
content = null
renderer = afx`
<div>{props.content}</div>
`
}
Base Prototypes
The base prototypes Text
and Line
will create text without block formatting whule
Number
creates integer numbers.
Sitegeist.ChitChat:Text
: (string) long textblock containing multiple sentencesSitegeist.ChitChat:Line
: (string) short textblock withoutSitegeist.ChitChat:Number
: (int)
All prototypes have the properties:
probability
(string|null) the name of the probability as configured in the settings.seed
(string|null) the source of randomness in addition to the fusion path
The Text
and Line
prototypes support in addition:
dictionary
(string|null) the name of the dictionaries as configured in the settingslength
(int|100 bzw. 500) the maximal length the text should havevariance
(float|0.5) the factor the actual length can be smaller than the configuredlength
.link
(bool|false) add links to some items<a href="#">...</s>
strong
(bool|false) make some items bold<strong>...</strong>
em
(bool|false) emphasize some items<em>...</em>
The Number
prototype supports in addition:
min
(int|0) the minimal number to createmax
(int|100) the maximal number to create
Textblock Fusion Prototypes
The textblocks extend the base prototypes with block formatting.
Otherwise they support the same properties as Text
and Line
.
Sitegeist.ChitChat:H1
: (string) A sentence in a h1-tagSitegeist.ChitChat:H2
: (string) A sentence in a h2-tagSitegeist.ChitChat:H3
: (string) A sentence in a h3-tagSitegeist.ChitChat:H4
: (string) A sentence in a h4-tagSitegeist.ChitChat:P
: (string) A sentence in a p-tag with links, strong and em
List Fusion Prototypes
The list prototypes extend the base prototypes with list formatting.
The prototypes have the properties as the base prototypes, in addition the
property number
allows to specify how many items are to be generated.
Sitegeist.ChitChat:UL
: (string) Multiple sentences as unordered list with links, strong and emSitegeist.ChitChat:OL
: (string) Multiple sentences as ordered list with links, strong and em
Additional properties:
number
(int|5) the number of items to generate ... defaults to a random number between 5 and 10
Configuration
The configuration allows to configure alternate implementations for
Sitegeist: ChitChat: # the dictionary and probability to use if nothing else is specified defaults: dictionary: pseudoLatin probability: predictable # providers for random numbers probablility: predictable: 'Sitegeist\ChitChat\Domain\PredictableProbabilityProvider' random: 'Sitegeist\ChitChat\Domain\RandomProbabilityProvider' # dictionaries dictionaries: pseudoLatin: 'Sitegeist\ChitChat\Domain\PseudoLatinDictionaryProvider'
Randomness vs predictability
While predictable text generation is important for stable tests and therefore is the default. The testing of frontend prototypes sometimes benefits from completely random texts that are regenerated on every call.
To allow this the probability mode can be configured via setting Setting
or fusion path probability
.
By default the modes random
and predictable
are available.
Replacing the dictionary or "how to speak klingon"
To implement custom dictionaries you can provide alternate implementations of the
interface \Sitegeist\ChitChat\Domain\DictionaryProviderInterface
.
The dictionaries are registered via Setting.yaml:
Sitegeist: ChitChat: dictionaries: klingon: 'Vendor\Example\KlingonDictionaryProvider'
And can later be used like this:
text = Sitegeist.ChitChat:Text {
dictionary = 'klingon'
}
Contribution
We will gladly accept contributions. Please send us pull requests.