Guide
Introduction
Wordsmith is a blazing fast, multi-byte safe, one-stop text manipulation toolkit for Craft CMS.
Features
- Trim and truncate text or HTML (by paragraph, word, or character)
- Beautify your typography (smart quotes, widow-prevention, ampersand styling, etc.)
- Change case and inflection
- Transliterate international text
- Search, count, isolate, and replace substrings
- Parse Emoji, using standard and short names
- Parse Markdown, in several flavors (including Parsedown)
- Parse names to get their parts (e.g. first name, last name, etc.)
- Parse a URL to get its parts (e.g. host name, path, query string, fragment, etc.)
- Get YouTube video ID from a URL
- Match and re-case Roman numerals
- Calculate text statistics like word count, sentence count, and readability
- Tell whether a variable value is string-like
- …and much more…
Usage
All of Wordsmith’s methods are available in your Twig templates as inline filters, filter blocks, or functions.
INLINE FILTER
{{ 'Lorem ipsum.' | trim }} |
FILTER BLOCK
{% filter trim %} |
FUNCTION
{{ trim('Lorem ipsum.') }} |
As a best practice, I recommend using the inline filter and filter block style only for methods that return text. For methods that return a number, array object, or other non-string value, using the function synatx will probably feel most ‘correct’.
You should also use the named argument syntax for providing parameter values when needed.
For example, while you could technically invoke the chop
method like this:{{ text | chop(3, 'w') }}
…you should instead explicitly name the arguments, like this:{{ text | chop(limit=3, unit='w') }}
By using this named argument syntax, you don’t need to supply all the possible parameters if you aren’t using them, and you’re guaranteed that your templates will keep working if the API changes.
For purposes of semantic versioning, the names of parameters are guaranteed to not change within a major version, but their order may.)
List of methods (abridged)
amp
apTitleize
automatedReadabilityIndex
averageWordsPerSentence
between
camelize
caps
chop
colemanLiauIndex
daleChallReadabilityScore
dasherize
emojify
entitle
firstName
firstWord
fleschKincaidReadingEase
fleschKincaidGradeLevel
givenName
gunningFogScore
hacksaw
humanize
hyphenate
isStringy
lastName
lastWord
lowerCaseRoman
markdown
md
ordinal
ordinalize
parsedown
parsedownExtra
parseName
parseUrl
pde
pascalize
pluralize
readTime
sentenceCount
singularize
slugify
smartypants
smogIndex
spacheReadabilityScore
substringAfterFirst
substringAfterLast
substringBeforeFirst
substringBeforeLast
substringBetween
substringCount
surname
titleize
typogrify
typogrifyFeed
underscore
underscored
upperCamelize
upperCaseRoman
urlFragment
urlHost
urlPass
urlPath
urlPort
urlQuery
urlScheme
urlUser
trim
trimLeft
trimRight
wc
widont
wrapAmps
wrapCaps
wordcount
youtubeId
Requirements
License
Wordsmith is “Postcardware” — Open-source and free to use… And if it helps you out, please send me a digital ‘postcard’ and let me know how you’re using it.
Support
Wordsmith is free and community-supported.
If you’d like to report a bug or make improvements/contributions to the code, please open a GitHub Issue or submit a Pull Request to the dev
branch.
If you’d like to request implementation support or commission a customization for your project, please email Support.
Thanks
Thanks for using Wordsmith!