Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 113 lines (71 sloc) 6.065 kb
8b2ad80 @Cocoanetics Updated readme
authored
1 DTCoreText
2 ==========
571ae6e @soffes Pretty readme to show off features
soffes authored
3
8b2ad80 @Cocoanetics Updated readme
authored
4 This project aims to duplicate the methods present on Mac OSX which allow creation of `NSAttributedString` from HTML code on iOS. Previously we referred to it as NSAttributedString+HTML (or NSAS+HTML in short) but this only covers about half of what this framework does.
5
04d37a0 @Cocoanetics Added Pledgie to Readme
authored
6 Please support us so that we can continue to make DTCoreText even more awesome!
7
6974ca2 @Cocoanetics try to replace paypal form button with regular button
authored
8 <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=M5DZ3PAN7NW8J">
9 <img src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!" />
10 </a>
04d37a0 @Cocoanetics Added Pledgie to Readme
authored
11
8b2ad80 @Cocoanetics Updated readme
authored
12 The project covers two broad areas:
13
14 1. Layouting - Interfacing with CoreText, generating NSAttributedString instances from HTML code
15 2. UI - several UI-related classes render these objects
571ae6e @soffes Pretty readme to show off features
soffes authored
16
17 This is useful for drawing simple rich text like any HTML document without having to use a `UIWebView`.
18
5c366fa @Cocoanetics Added link to Q&A
authored
19 Please read the [Q&A](http://www.cocoanetics.com/2011/08/nsattributedstringhtml-qa/).
20
170bbfb @Cocoanetics Restructured and unified attachment handling for img, video, iframe, obj...
authored
21 Your help is much appreciated. Please send pull requests for useful additions you make or ask me what work is required.
571ae6e @soffes Pretty readme to show off features
soffes authored
22
23 If you find brief test cases where the created `NSAttributedString` differs from the version on OSX please send them to us!
24
25 Follow [@cocoanetics](http://twitter.com/cocoanetics) on Twitter.
f6daeef @Cocoanetics Added note about CoreText loading performance workaround to Readme
authored
26
8b2ad80 @Cocoanetics Updated readme
authored
27 License
cfba4d8 @joepasq Added a more detailed installation guide using a subproject.
joepasq authored
28 -------
29
8b2ad80 @Cocoanetics Updated readme
authored
30 It is open source and covered by a standard BSD license. That means you have to mention *Cocoanetics* as the original author of this code. You can purchase a Non-Attribution-License from us.
31
befdca7 @Cocoanetics added Documentation target and link to gh-pages
authored
32 Documentation
33 -------------
34
35 Documentation can be [browsed online](http://cocoanetics.github.com/DTCoreText) or installed in your Xcode Organizer via the [Atom Feed URL](http://cocoanetics.github.com/DTCoreText/DTCoreText.atom).
36
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
37 Requirements
38 ------------
8b2ad80 @Cocoanetics Updated readme
authored
39
c67b0e8 @Cocoanetics updated read me to reflect decreased deployment target
authored
40 DTCoreText needs a minimum iOS deployment target of iOS 4.2 because of:
60cfab5 @Cocoanetics Updated readme
authored
41
42 - NSCache
43 - GCD-based threading and locking
44 - Blocks
44061fa @Cocoanetics Updated Readme
authored
45 - ARC
60cfab5 @Cocoanetics Updated readme
authored
46
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
47 DTCoreText is designed to be included as static library from a subproject, it embeds several classes from the DTFoundation project. If you want to use DTFoundation as well in your project you need to use the "Static Library (no DTFoundation)" target to avoid duplicate symbols.
48
49 Setup
50 -----
51
52 The best way to use DTCoreText is to add it in Xcode as a subproject of your project with the following steps.
53
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
54 1. Make DTCoreText a git submodule of your project
cfba4d8 @joepasq Added a more detailed installation guide using a subproject.
joepasq authored
55
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
56 `git submodule add https://github.com/Cocoanetics/DTCoreText.git Externals/DTCoreText`
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
57
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
58 2. DTCoreText uses DTHTMLParser and DTVersion from DTFoundation which is set up as a git submodule in Core/Externals/DTFoundation, so you need to get these files as well
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
59
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
60 `git submodule update --init --recursive`
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
61
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
62 3. Open the destination project and create an 'Externals' group.
63
64 4. 'Add files..' or drag `DTCoreText.xcodeproj` to the 'Externals' group
cfba4d8 @joepasq Added a more detailed installation guide using a subproject.
joepasq authored
65
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
66 5. In your application target's Build Phases: Target Dependencies add the "Static Library" from the DTCoreText sub project
300a8d8 @Cocoanetics Updated Readme
authored
67
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
68 6. In your application target's Build Phases: Link Binary With Libraries phase add the following:
cfba4d8 @joepasq Added a more detailed installation guide using a subproject.
joepasq authored
69
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
70 libDTCoreText.a (target from the DTCoreText sub-project)
71 libxml2.dylib
cfba4d8 @joepasq Added a more detailed installation guide using a subproject.
joepasq authored
72 ImageIO.framework
73 QuartzCore.framework
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
74 CoreText.framework
75 MobileCoreServices.framework
cfba4d8 @joepasq Added a more detailed installation guide using a subproject.
joepasq authored
76
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
77 7. Go to File: Project Settings… and change the derived data location to project-relative.
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
78
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
79 8. Add the DerivedData folder to your git ignore.
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
80
6d6085c @Cocoanetics Updated read me to reflect that DTFoundation is now a dependency as git ...
authored
81 9. In your application's target Build Settings:
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
82 - Add `$(PROJECT_DIR)` to `User Header Search Paths`, set to `recursive`
83 - Set `Always Search User Paths` to `Yes`.
84 - Add the `-ObjC` flag to your app target's `Other Linker Flags`
3880629 @Cocoanetics markdown
authored
85
13775dd @alunsford3 Modified the Readme.markdown to have more clear submodule instructions, ...
alunsford3 authored
86 OPTIONAL LINKER SETTINGS:
9baa6c6 @alunsford3 Step clarification and markup additions
alunsford3 authored
87 - If you find that your app crashes with an unrecognized selector from one of this library's categories, you might also need the `-all_load linker` flag. Alternatively you can use `-force-load` with the full path to the static library. This causes the linker to load all categories from the static library.
88 - If your app does not use ARC yet (but DTCoreText does) then you also need the `-fobjc-arc` linker flag.
f6daeef @Cocoanetics Added note about CoreText loading performance workaround to Readme
authored
89
8b2ad80 @Cocoanetics Updated readme
authored
90 Known Issues
91 ------------
f6daeef @Cocoanetics Added note about CoreText loading performance workaround to Readme
authored
92
93 CoreText has a problem prior to iOS 5 where it takes around a second on device to initialize its internal font lookup table. You have two workarounds available:
94
95 - trigger the loading on a background thread like shown in http://www.cocoanetics.com/2011/04/coretext-loading-performance/
96 - if you only use certain fonts then add the variants to the DTCoreTextFontOverrides.plist, this speeds up the finding of a specific font face from the font family
3e41ffc @Cocoanetics Updated Readme with new known issue
authored
97
98 Some combinations of fonts and unusual list types cause an extra space to appear. e.g. 20 px Courier + Circle
8b2ad80 @Cocoanetics Updated readme
authored
99
86b1501 @Cocoanetics Updated both readies with known differences between Mac's initWithHTML a...
authored
100 In many aspects DTCoreText is superior to the Mac version of generating NSAttributedStrings from HTML. These become apparent in the MacUnitTest where the output from both is directly compared. I am summarizing them here for references.
101
102 In the following "Mac" means the initWithHTML: methods there, "DTCoreText" means DTCoreText's initWithHTML and/or DTHTMLAttributedStringBuilder.
103
104 - Mac does not support the video tag, DTCoreText does.
105 - DTCoreText is able to synthesize small caps by putting all characters in upper case and using a second smaller font for lowercase characters.
106 - I suspect that Mac makes use of the -webkit-margin-* CSS styles for spacing the paragraphs, DTCoreText only uses the -webkit-margin-bottom and margin-bottom at present.
107 - Mac supports CSS following addresses, e.g. "ul ul" to change the list style for stacked lists. DTCoreText does not support that and so list bullets stay the same for multiple levels.
3f8b370 @Cocoanetics Fixed whitespace handling for PRE
authored
108 - Mac outputs newlines in PRE tags as \n, iOS replaces these with Unicode Line Feed characters so that the paragraph spacing is applied at the end of the PRE tag, not after each line. (iOS wraps code lines when layouting)
d65442a @Cocoanetics rewrite list support
authored
109 - Mac does not properly encode a double list start. iOS prints the empty list prefix.
9f535c3 @Cocoanetics Added fixes for unit test so that when testing output matches (wrong) Ma...
authored
110 - Mac seems to ignore list-style-position:outside, iOS does the right thing.
86b1501 @Cocoanetics Updated both readies with known differences between Mac's initWithHTML a...
authored
111
8b2ad80 @Cocoanetics Updated readme
authored
112 If you find an issue then you are welcome to fix it and contribute your fix via a GitHub pull request.
Something went wrong with that request. Please try again.