Introducing WordArt for ColdFusion

WordArt for ColdFusion is available for free under new BSD License.

WordArt CFC generates image for insertion of typography on a webpage by converting text to image in various styles. There are over 25 different options available in this first release of WordArt.

Get WordArt CFC:

• Download CFC , or
• Download WordArt for CFWheels

Demo

This blog is just an HTML blog hosted on blogger, to see real output of WordArt CFC, see the WordArt demo.

Features

1. Various styles and alpha-color values.
2. Smart caching
3. Custom font directory
4. Rounded corners
5. StickerStyle (for placement in a corner of a web-page, or on right or left side)
6. Stroked text
7. Quoted text
8. Reflection
9. Shadows

Usage Syntax:

#getArt(<Your Message Here (string)>, <Image Options Here (struct)>)#

Basic Example:

Create object and call init():

<cfset wordart = createObject("component", "wordart").init() />

Use wordart.getArt() to generate images:

<cfoutput>
        #wordart.getArt("CFWheels is the future and the future is written in ColdFusion",
                {font="LinLibertine", fontstyle="bolditalic", fontSize=30})#
        #wordart.getArt("The future is written in ColdFusion")#
</cfoutput>

To prevent calling init() method in all requests, you can store the instance in your application or server scope as shown below:

<cfset application.wordart = createObject("component", "wordart").init() />

 

Using WordArt in CFWheels

If you are using WordArt plug-in for CFWheels then you would just use getArt() function since it is made available to your controllers and views. You will not prefix “wordart.” in your function calls. Example is shown below:

<cfoutput>
        #getArt(text="CFWheels is the future and the future is written in ColdFusion", options={style="blockquote", font="Trebuchet MS", fontstyle="bolditalic", fontSize=30, wrapWidth=350})#
</cfoutput>

 

 

Default font directory and image directory

By default, font directory is set to “files/fonts” (absolute path) and images directory is set to “images/wordart” (absolute path). There is a third path, urlPath, with which stored images can be accessed from browser.

1. urlPath – defaults to "/images/wordart/"
   path with which stored images can be accessed from browser
2. artDir – defaults to "#expandPath("images/wordart/")#"
   absolute path of directory where generated images are to be stored
3. fontDir – defaults to "#expandPath("files/fonts/")#"
   absolute path of directory where you store fonts. this directory is checked for fonts before system's font directory is checked. when a font is missing from both the folders, 'serif' font is used.

Font directory is used to check for font files and images directory is used to store the generated images. If these two folders are not present when you call WordArt.init() is called they will be automatically created. If you wish to use a different directory for fonts or images, use the following syntax:

<cfset wordart = createObject("component", "wordart").init(urlPath = "myArtFolder", artDir = expandPath("myArtFolder"), fontDir = expandPath("myFontFolder")) />

You may use setFontDirectory and setArtDirectory methods. Remember to pass only an absolute path for font directory and images(art) directory as shown above. The absolute path conditions apply to init(), setFontDirectory and setArtDirectory().

The urlPath must point to the same directory as artDir. The difference is that the urlPath is used in img tag’s src attribute while the artDir is used in server side for storing images. But both point to same directory.

 

System Installed Fonts

System installed fonts are used but priority is given to the font in the fontDirectory you have specified. So you don’t have to install every font you want to use in your site in your server. When you specify “LinLibertine” as the font, the component will check the file in your font directory using fileExists() method. If the file with .ttf extension is found component will use that font otherwise it will try to use system installed font.

 

WordArt.getArt Function:

The most important function of this component is getArt(). The function creates image using the 'text' argument and places an <img> tag in your document. If instead of placing <img> tag you wish to get the image URL then use the getArtUrl() function. getArt() and getArtUrl() both accept three arguments. Namely, "text", "options", and "useCache".

Arguments for getArt():

The function expects one mandatory argument and two optional arguments:

1. text – required. a string that would be rendered in the image.
2. options – optional. a struct that would define how the text would appear (style, font, fontSize, fontStyle, bgColor, fgColor, wrapWidth etc).
3. useCache – optional. true or false. defaults to true.

More on "options" argument:

1. options.style: In this version there are 3 styles:
   • simple
   • stroked or twitter
   • quote or blockquote
     
2. options.font: defines the font to use.
   • This font must be available in your font directory or must be installed in your system.
   • Java default font is "serif". When the font you specified is missing, “serif” will be used.
   • Only TTF fonts are supported. OTF have limited support in Java.
     
3. options.fontStyle: string that defines the font style. Valid values are:
   • "bold"
   • "bolditalic"
   • "italic"
   • "plain". (default)
     
4. options.fontSize: a number that defines the font size.
5. options.wrapWidth: the max width of image you wish to create
   • defaults to 0.
   • When the value is 0, no word wrapping is done and output is single line image.
     
6. options.bgAlpha    - background alpha. defaults to 0
7. options.fgAlpha    - foreground/text alpha. defaults to 255
8. options.strokeAlpha    - stroked alpha. defaults to 255. used when style=stroked.
9. options.quoteAlpha    - quote alpha. defaults to 255. used when style=quote
10. options.shadowAlpha    - shadow alpha. defaults to 125. used when shadow=true.
    
    • For all alpha values pass an integer that defines the opacity.
    • Valid values are from 0 to 255.
    • Number 0 = transparent
    • 255 = Opaque
      
11. options.bgColor    - background color.
    • defaults to FFFFFF.
    • since default alpha is 00, you will not see background color.
    • if you are not passing bgAlpha you should use 8 digit hexadecimal color code.
12. options.fgColor - foreground or text-color. defaults to 000000 (black)
13. options.strokeColor - defaults to 33CCFF
14. options.quoteColor - defaults to 666666
15. options.shadowColor - defaults to 000000
    
    • For all color values pass an 3digit hex OR 6digit hex, OR 8digit hex.
    • Examples:
      • 3 digit hex: #F00 is same as #FF0000. Both equals color Red.
      • 8 digit hex: #33FF0000. Color with alpha. Red with transparency of 20%.
        • First two part define transparency level.
        • Use 00 for complete transparent color. FF for opaque color.
    • Note: Always use # at the beginning for all color values.
      
16. options.shadow - boolean value true or false that implies drawing of shadow.
17. options.reflection - boolean value true or false that implies reflection effect.
    • Note: using reflection increases the height of image.
      
18. options.stickerStyle
    • Generates a trapezoid that can be placed on corner of the screen.
    • Or generates a 90 degrees rotated image for placement at 'east' or 'west' sides.
    • Valid values:
      • "ne" rotates text for placement at north-east corner
      • "nw" rotates text for placement at north-west corner
      • "sw" rotates text for placement at south-west corner
      • "se" rotates text for placement at south-east corner
      • "west" rotates text for placement at west
      • "east" rotates text for placement at east
        
19. options.shadowX    - x coordinate offset for shadow. used for drawing shadow.
20. options.shadowY    - y coordinate offset for shadow. used for drawing shadow.
21. options.reflectGap - gap between image and reflection.
22. options.reflectHeight – number value in fraction to define extra height added to height of generated text.
    • Defaults to 1.
    • Use this to reduce the additional empty space at the bottom of reflection.
    • Note that the reflection also includes the white space of the original image.
      
23. options.fadeHeight – number value in fraction to define height of fade. defaults to 0.4
24. options.reflectOpacity - opacity at the start of mirror effect. defaults to 100. valid values are 0 to 255.
25. options.top
26. options.bottom
27. options.left
28. options.right
29. options.cornerRadius - draws a rounded rectangle. defaults to 0.

Examples of various available styles:

Simple paragraph: style = “simple”

A simple sentence with wrapWidth set to 300. Foreground color is FFC8C6C3. Its an eight digit hexadecimal color value with first two characters FF imply an opaque color. If first two characters were 00 it would be transparent. Alternatively you can use fgAlpha if you find yourself uncomfortable with 8 digit hex. Note that 6 digit hex is also supported.

wordart.getArt(text='She stopped. She said, "Hello there!", and moved on.',
    options={style="simple", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    fgColor="##FFc8c6c3", wrapWidth=300})

 

Block-quote: style = “quote”

Note: you can change appearance of quote using quoteColor and quoteAlpha properties. You can also pass both color and alpha to quoteColor using 8 character hexadecimal string, example: #33CCCCCC.

wordart.getArt(text='She stopped. She said, "Hello there!", and moved on.',
    options={style="quote", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    top=3, left=3, right=3, bottom=3, wrapWidth=330})

Text with reflection: reflection=true

wordart.getArt(text='tell-a-friend',
    options={style="simple", font="PICOBLA_", fontSize=24, fontStyle="bold",
        reflection=true})

Reflection with different bgColor and fgColor.

wordart.getArt(text='tell-a-friend',
    options={style="simple", font="PICOBLA_", fontSize=24, fontStyle="bold",
       bgColor="##FF111111", fgColor="##FFFFFFFF", 
        reflection=true})

Reflection with different bgColor and fgColor and with extra padding.

wordart.getArt(text='tell-a-friend',
    options={style="simple", font="PICOBLA_", fontSize=24, fontStyle="bold",
        bgColor="##FF111111", fgColor="##FFFFFFFF",
        top=10, left=10, right=10, reflection=true})

 

Reducing extra space added by reflection effect. reflectHeight = 0.6

wordart.getArt(text='tell-a-friend',
    options={style="simple", font="PICOBLA_", fontSize=24, fontStyle="bold",
        bgColor="##FF111111", fgColor="##FFFFFFFF",
        top=10, left=10, right=10, reflection=true, reflectHeight=0.6})

Corner banner with reflection and padding:

wordart.getArt(text='tell-a-friend',
    options={style="simple", font="PICOBLA_", fontSize=24, fontStyle="bold",
        bgColor="##FF111111", fgColor="##FFFFFFFF",
        top=10, left=10, right=10, stickerStyle="nw", reflection=true})

Corner Sticker: stickerStyle = “sw” (south west banner)

wordart.getArt(text='South West Sticker',
    options={style="simple", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    bgColor="##FF565656", fgColor="##FFc8c6c3",
    top=10, left=10, right=10, bottom=10, stickerStyle="sw"})

 

 

Corner Sticker: stickerStyle = “ne” (north east banner)

wordart.getArt(text='Wheels on Fire',
    options={style="simple", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    bgColor="##FFc8c6c3", fgColor="##FF565656",
    top=10, left=10, right=10, bottom=10, stickerStyle="ne"})

 

Rounded corners: cornerRadius = 8

wordart.getArt(text='Start',
    options={style="simple", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    top=3, left=9, right=9, bottom=3, cornerRadius=8, bgColor="##fffb2222", fgColor="##FFFFFFFF"})

 

Stroked text: style = “stroked”

Note: since my blog’s background is also white, in this example, you will not see white background I am setting.

wordart.getArt(text='Start',
    options={style="stroked", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    top=3, left=9, right=9, bottom=3, cornerRadius=8, bgColor="##ffffffff", fgColor="##FFFFFFFF"})

Stroked text with shadow: shadow = true

wordart.getArt(text='Start',
    options={style="stroked", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    top=3, left=9, right=9, bottom=3, fgColor="##FFFFFFFF",  shadow=true})

Stroked text with red stroke: strokeColor = “#fffb2222”

wordart.getArt(text='Start',
    options={style="stroked", font="Trebuchet MS", fontSize=24, fontStyle="bold",
    top=3, left=9, right=9, bottom=3, strokeColor="##fffb2222", fgColor="##FFFFFFFF"})

Sticker for left side: stickerStyle = “west”

wordart.getArt(text='Sticker Style: West!',
    options={style="simple", font="Trebuchet MS", fontSize=24, fontStyle="bold",
        bgColor="##FF111111", fgColor="##FFFFFFFF",
        top=5, bottom=10, left=10, right=10, stickerStyle="west"})

 

Sticker for right side: stickerStyle = “east”

wordart.getArt(text='Sticker Style: West!',
    options={style="simple", font="Trebuchet MS", fontSize=24, fontStyle="bold",
        bgColor="##FF111111", fgColor="##FFFFFFFF",
        top=5, bottom=10, left=10, right=10, stickerStyle="east"})

 

The alternative function getArtUrl()

It is possible that you only want to read the generated image’s URL to gain more fine control and write your own <img> tag. You will use getArtUrl() method for that purpose.

Other Important Functions:

1. getArtDirectory – returns the folder path that is used to store generated images.
2. setArtDirectory – sets the folder path for storing generated images. Use absolute paths only. (ex: C:\webroot\images\wordart\). This path should be accessible URL of your website from a browser.
3. getFontDirectory – returns the folder path that is used to look up TTF fonts before system font folder is used.
4. setFontDirectory – sets the folder path for true-type font look ups. Use absolute paths only (ex: C:\webroot\mysite\fonts\)
5. getArtUrlPath - returns the path that is used to access generated images from the browser.
6. setArtUrlPath - sets the path that is used to access generated images from the browser.

Set-up: Before you begin:

Download the CFC and place it inside your application. If you are using CFWheels framework, you need not make any changes. However, if you are not using any framework or are using some other framework, you will have to call the init() function first. The init function returns the instance of WordArt component. Save this instance in your application scope. Once you have the instance of WordArt in your application scope, you will have to call setArtDirectory() and setFontDirectory() functions once.

Setting font directory and art directory:

Suppose you have stored WordArt.cfc inside a folder named “myComponents”. And you wish to use “files/fonts” as your fonts folder and “images/wordart/” folder for storing fonts. This is what you would write (in most cases you will write initialization code in Application.cfc onApplicationStart)

<cffunction name="onApplicationStart">

application.wordart = createObject("component", "myComponents.wordart").init();
application.setFontDirectory(expandPath("files/fonts/"));
application.setArtDirectory(expandPath("images/wordart/"));
application.setArtUrlPath("images/wordart/");     // this is how images are accessible from a browser

</cffunction>

The above four lines can be shrink to single line call by passing the three paths to init() function as arguments.

application.wordart = createObject("component", "myComponents.wordart").init(urlPath="images/wordart/", artDir=expandPath("images/wordart/"), fontDir=expandPath("files/fonts/"));

Contribute

If you make changes kindly let me know by sharing the code.

Send your Feedback

I’d like to hear how you are using the CFC. There are literally thousands of possible combinations! If you are going to use the component take time to share your page’s URL by posting a comment in the WordArt forums.

Visit this project's wiki to learn about usage and features.

View source code of CFC WordArt.cfc

Read-only SVN access is available at http://svn.codecurry.com/WordArtCFC – username: guest and password: guest