diff --git a/.eslintrc.json b/.eslintrc.json index 79f1739be..25ab723db 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -1,4 +1,7 @@ { + "parserOptions": { + "ecmaVersion": 6 + }, "env": { "node": true, "mocha": true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7b15c8f1..b6708b8b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ We are always happy to receive code and documentation contributions to the frame 1. This framework is released under the [Apache license][license]. Any code you submit will be released under that license. For substantial contributions, we may ask you to sign a [Contributor License Agreement (CLA)][cla]. 2. For any significant features or API changes please reach out to us to avoid any duplicate effort. -3. Adding to the included transforms, transformGroups, formats, and templates, please read [this section](#what-should-be-included). +3. Adding to the included transforms, transformGroups, and formats, please read [this section](#what-should-be-included). ## Code Style @@ -29,8 +29,8 @@ We are always happy to receive code and documentation contributions to the frame We use ESLint on the code to ensure a consistent style. Any new code committed must pass our ESLint tests. Take a look at our [ESLint file][eslint]. ### Code Rules -1. **Do not mutate property names or values in a format or template.** Mutations like this should happen in a transformer. -1. **Be as generic as possible.** Do not hard-code any values or configuration in formats or templates. +1. **Do not mutate property names or values in a format.** Mutations like this should happen in a transformer. +1. **Be as generic as possible.** Do not hard-code any values or configuration in formats. 1. **Fail loudly.** Users should be aware if something is missing or configurations aren't correct. This will help debug any issues instead of failing silently. 1. **Rely on few dependencies.** This framework is meant to be extended and allows for customization. We don't want to bring a slew of dependencies that most people don't need. @@ -38,9 +38,9 @@ We use ESLint on the code to ensure a consistent style. Any new code committed m Anything that contributes to the idea of creating cross-platform styles. -### What transforms/transform groups/formats/templates should be included? +### What transforms/transform groups/formats should be included? -If it has a generic and flexible enough use-case, it can be included. We would like to keep this type of code to a minimum because we don't want to be a swiss army knife that does everything out of the box. Instead, we want to focus on core tasks that are useful to the largest number of projects. The spirit of this framework is to allow flexibility and modularity so that anyone can fit it to their needs. This is why you can write your own transforms, formats, and templates with the register methods. +If it has a generic and flexible enough use-case, it can be included. We would like to keep this type of code to a minimum because we don't want to be a swiss army knife that does everything out of the box. Instead, we want to focus on core tasks that are useful to the largest number of projects. The spirit of this framework is to allow flexibility and modularity so that anyone can fit it to their needs. This is why you can write your own transforms, and formats with the register methods. ### Where do things go? @@ -51,7 +51,7 @@ We separate each function/method into its own file and group them into directori Any new features should implement the proper unit tests. We use mocha and chai to test our framework. -If you are adding a new transform, action, format, or template, please add new unit tests. You can see examples in test/formats. +If you are adding a new transform, action, or format: please add new unit tests. You can see examples in test/formats. [issues]: https://github.com/amzn/style-dictionary/issues diff --git a/README.md b/README.md index d9551c8c2..13a5379e4 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ This tells the style dictionary build system how and what to build. The default "buildPath": "build/android/", "files": [{ "destination": "font_dimens.xml", - "template": "android/fontDimens" + "format": "android/fontDimens" }] } } @@ -140,8 +140,7 @@ This tells the style dictionary build system how and what to build. The default | platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. | | platform.files | Array (optional) | Files to be generated for this platform. | | platform.file.destination | String (optional) | Location to build the file, will be appended to the buildPath. | -| platform.file.format | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. Must declare a format or a template. | -| platform.file.template | String (optional) | Template used to generate the file. Can be a built-in one or you can create your own. [More on formats and templates](https://amzn.github.io/style-dictionary/formats_and_templates) | +| platform.file.format | String (optional) | Format used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats) | | platform.file.options | Object (optional) | A set of extra options associated with the file. | | platform.file.options.showFileHeader | Boolean | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true". | @@ -256,7 +255,7 @@ The comment will appear in the output files, where relevant or the output forma ## Extending -The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms, templates, and formats. +The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms and formats. ```javascript const StyleDictionary = require('style-dictionary').extend('config.json'); @@ -275,7 +274,7 @@ StyleDictionary.registerTransform({ StyleDictionary.buildAllPlatforms(); ``` -For more information on creating your own transforms, templates, and formats, take a look at our [docs](https://amzn.github.io/style-dictionary/). +For more information on creating your own transforms and formats, take a look at our [docs](https://amzn.github.io/style-dictionary/). ## Mascot diff --git a/__tests__/__configs/test.json b/__tests__/__configs/test.json index f8cde2eeb..feab04c97 100644 --- a/__tests__/__configs/test.json +++ b/__tests__/__configs/test.json @@ -52,13 +52,13 @@ "files": [ { "destination": "android/colors.xml", - "template": "android/colors" + "format": "android/colors" },{ "destination": "android/font_dimen.xml", - "template": "android/fontDimens" + "format": "android/fontDimens" },{ "destination": "android/dimens.xml", - "template": "android/dimens" + "format": "android/dimens" } ], "actions": [ @@ -71,10 +71,10 @@ "files": [ { "destination": "style_dictionary.plist", - "template": "ios/plist" + "format": "ios/plist" },{ "destination": "style_dictionary.h", - "template": "ios/macros" + "format": "ios/macros" } ] } diff --git a/__tests__/buildFiles.test.js b/__tests__/buildFiles.test.js index 2e4e972d4..7897a9f2c 100644 --- a/__tests__/buildFiles.test.js +++ b/__tests__/buildFiles.test.js @@ -97,10 +97,10 @@ describe('buildFiles', () => { ).toThrow('Build path must end in a trailing slash or you will get weird file names.'); }); - it('should throw if template or formatter missing', () => { + it('should throw if missing a format', () => { expect( buildFiles.bind(null, dictionary, platformWithoutFormatter), - ).toThrow('Please supply a template or formatter'); + ).toThrow('Please supply a format'); }); it('should work without buildPath', () => { diff --git a/__tests__/formats/__snapshots__/all.test.js.snap b/__tests__/formats/__snapshots__/all.test.js.snap index 22b868b7a..44e2328bf 100644 --- a/__tests__/formats/__snapshots__/all.test.js.snap +++ b/__tests__/formats/__snapshots__/all.test.js.snap @@ -1,5 +1,76 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP +exports[`formats all should return android/colors as a string 1`] = ` +" + + + + #FF0000 + + +" +`; + +exports[`formats all should return android/dimens as a string 1`] = ` +" + + + + + +" +`; + +exports[`formats all should return android/fontDimens as a string 1`] = ` +" + + + + + +" +`; + +exports[`formats all should return android/integers as a string 1`] = ` +" + + + + + +" +`; + +exports[`formats all should return android/strings as a string 1`] = ` +" + + + + + +" +`; + +exports[`formats all should return css/fonts.css as a string 1`] = ` +" +" +`; + exports[`formats all should return css/variables as a string 1`] = ` "/** * Do not edit directly @@ -7,8 +78,276 @@ exports[`formats all should return css/variables as a string 1`] = ` */ :root { + --color_red: #FF0000; +} +" +`; + +exports[`formats all should return ios/colors.h as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import + + +typedef NS_ENUM(NSInteger, ) { +color_red +}; + +@interface : NSObject ++ (NSArray *)values; ++ (UIColor *)color:()color; +@end +" +`; + +exports[`formats all should return ios/colors.m as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import \\".h\\" + + +@implementation + ++ (UIColor *)color:()colorEnum{ + return [[self values] objectAtIndex:colorEnum]; +} + ++ (NSArray *)values { + static NSArray* colorArray; + static dispatch_once_t onceToken; + + dispatch_once(&onceToken, ^{ + colorArray = @[ +#FF0000 + ]; + }); + + return colorArray; +} + +@end +" +`; + +exports[`formats all should return ios/macros as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import +#import + + + +#define color_red #FF0000 + +" +`; + +exports[`formats all should return ios/plist as a string 1`] = ` +" + + + + + + color_red + + r + NaN + g + NaN + b + NaN + a + 1 + + + + +" +`; + +exports[`formats all should return ios/singleton.h as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// +#import +#import + +@interface : NSObject + ++ (NSDictionary *)properties; ++ (NSDictionary *)getProperty:(NSString *)keyPath; ++ (nonnull)getValue:(NSString *)keyPath; + +@end +" +`; + +exports[`formats all should return ios/singleton.m as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import \\".h\\" + +@implementation + ++ (NSDictionary *)getProperty:(NSString *)keyPath { + return [[self properties] valueForKeyPath:keyPath]; +} + ++ (nonnull)getValue:(NSString *)keyPath { + return [[self properties] valueForKeyPath:[NSString stringWithFormat:@\\"%@.value\\", keyPath]]; +} + ++ (NSDictionary *)properties { + static NSDictionary * dictionary; + static dispatch_once_t onceToken; + + dispatch_once(&onceToken, ^{ + dictionary = @{ + @\\"color\\": @{ + @\\"red\\": @{ + @\\"value\\": #FF0000, + @\\"name\\": @\\"color_red\\", + @\\"category\\": @\\"color\\", + @\\"type\\": @\\"red\\" + } + } + }; + }); + + return dictionary; } + +@end + + +" +`; + +exports[`formats all should return ios/static.h as a string 1`] = ` +" +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import + + + +extern const color_red; +" +`; + +exports[`formats all should return ios/static.m as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import \\".h\\" + + + + const color_red = #FF0000; +" +`; + +exports[`formats all should return ios/strings.h as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import + + + +extern NSString * const color_red; + +@interface : NSObject ++ (NSArray *)values; +@end +" +`; + +exports[`formats all should return ios/strings.m as a string 1`] = ` +" +// +// __output/ +// +// Do not edit directly +// Generated on Sat, 01 Jan 2000 00:00:00 GMT +// + +#import \\".h\\" + + + +NSString * const color_red = #FF0000; + +@implementation + ++ (NSArray *)values { + static NSArray* array; + static dispatch_once_t onceToken; + + dispatch_once(&onceToken, ^{ + array = @[ + @{ + @\\"value\\": #FF0000, + @\\"name\\": @\\"color_red\\", + @\\"category\\": @\\"color\\", + @\\"type\\": @\\"red\\" + } + ]; + }); + + return array; +} + +@end + + " `; @@ -18,7 +357,7 @@ exports[`formats all should return javascript/es6 as a string 1`] = ` * Generated on Sat, 01 Jan 2000 00:00:00 GMT */ -" +export const color_red = \\"#FF0000\\";" `; exports[`formats all should return javascript/module as a string 1`] = ` @@ -30,7 +369,19 @@ exports[`formats all should return javascript/module as a string 1`] = ` module.exports = { \\"color\\": { \\"red\\": { - \\"value\\": \\"#FF0000\\" + \\"value\\": \\"#FF0000\\", + \\"original\\": { + \\"value\\": \\"#FF0000\\" + }, + \\"name\\": \\"color_red\\", + \\"attributes\\": { + \\"category\\": \\"color\\", + \\"type\\": \\"red\\" + }, + \\"path\\": [ + \\"color\\", + \\"red\\" + ] } } };" @@ -45,7 +396,19 @@ exports[`formats all should return javascript/object as a string 1`] = ` var _styleDictionary = { \\"color\\": { \\"red\\": { - \\"value\\": \\"#FF0000\\" + \\"value\\": \\"#FF0000\\", + \\"original\\": { + \\"value\\": \\"#FF0000\\" + }, + \\"name\\": \\"color_red\\", + \\"attributes\\": { + \\"category\\": \\"color\\", + \\"type\\": \\"red\\" + }, + \\"path\\": [ + \\"color\\", + \\"red\\" + ] } } };" @@ -71,7 +434,19 @@ exports[`formats all should return javascript/umd as a string 1`] = ` return { \\"color\\": { \\"red\\": { - \\"value\\": \\"#FF0000\\" + \\"value\\": \\"#FF0000\\", + \\"original\\": { + \\"value\\": \\"#FF0000\\" + }, + \\"name\\": \\"color_red\\", + \\"attributes\\": { + \\"category\\": \\"color\\", + \\"type\\": \\"red\\" + }, + \\"path\\": [ + \\"color\\", + \\"red\\" + ] } } }; @@ -83,7 +458,19 @@ exports[`formats all should return json as a string 1`] = ` "{ \\"color\\": { \\"red\\": { - \\"value\\": \\"#FF0000\\" + \\"value\\": \\"#FF0000\\", + \\"original\\": { + \\"value\\": \\"#FF0000\\" + }, + \\"name\\": \\"color_red\\", + \\"attributes\\": { + \\"category\\": \\"color\\", + \\"type\\": \\"red\\" + }, + \\"path\\": [ + \\"color\\", + \\"red\\" + ] } } }" @@ -114,7 +501,7 @@ exports[`formats all should return less/variables as a string 1`] = ` * Generated on Sat, 01 Jan 2000 00:00:00 GMT */ -" +@color_red: #FF0000;" `; exports[`formats all should return scss/icons as a string 1`] = ` @@ -132,7 +519,7 @@ exports[`formats all should return scss/variables as a string 1`] = ` * Generated on Sat, 01 Jan 2000 00:00:00 GMT */ -" +$color_red: #FF0000;" `; exports[`formats all should return sketch/palette as a string 1`] = ` diff --git a/__tests__/formats/all.test.js b/__tests__/formats/all.test.js index 5f4c2ef00..8958587cc 100644 --- a/__tests__/formats/all.test.js +++ b/__tests__/formats/all.test.js @@ -26,9 +26,34 @@ var file = { }; var dictionary = { + "allProperties": [{ + value: '#FF0000', + original: { value: '#FF0000' }, + name: 'color_red', + attributes: { + category: 'color', + type: 'red', + item: undefined, + subitem: undefined, + state: undefined + }, + path: ['color','red'] + }], "properties": { "color": { - "red": {"value": "#FF0000"} + "red": { + value: '#FF0000', + original: { value: '#FF0000' }, + name: 'color_red', + attributes: { + category: 'color', + type: 'red', + item: undefined, + subitem: undefined, + state: undefined + }, + path: ['color','red'] + } } } }; diff --git a/__tests__/register/format.test.js b/__tests__/register/format.test.js index 282b4a050..97acf8197 100644 --- a/__tests__/register/format.test.js +++ b/__tests__/register/format.test.js @@ -22,14 +22,14 @@ describe('register', () => { StyleDictionaryExtended.registerFormat.bind(null, { formatter: function() {} }) - ).toThrow('transform name must be a string'); + ).toThrow('Can\'t register format; format.name must be a string'); expect( StyleDictionaryExtended.registerFormat.bind(null, { name: 1, formatter: function() {} }) - ).toThrow('transform name must be a string'); + ).toThrow('Can\'t register format; format.name must be a string'); expect( StyleDictionaryExtended.registerFormat.bind(null, { @@ -43,46 +43,46 @@ describe('register', () => { name: {}, formatter: function() {} }) - ).toThrow('transform name must be a string'); + ).toThrow('Can\'t register format; format.name must be a string'); }); - it('should error if formatter is not a function', () => { + it('should error if format is not a function', () => { expect( StyleDictionaryExtended.registerFormat.bind(null, { name: 'test' }) - ).toThrow('format formatter must be a function'); + ).toThrow('Can\'t register format; format.formatter must be a function'); expect( StyleDictionaryExtended.registerFormat.bind(null, { name: 'test', formatter: 1 }) - ).toThrow('format formatter must be a function'); + ).toThrow('Can\'t register format; format.formatter must be a function'); expect( StyleDictionaryExtended.registerFormat.bind(null, { name: 'test', formatter: 'name' }) - ).toThrow('format formatter must be a function'); + ).toThrow('Can\'t register format; format.formatter must be a function'); expect( StyleDictionaryExtended.registerFormat.bind(null, { name: 'test', formatter: [] }) - ).toThrow('format formatter must be a function'); + ).toThrow('Can\'t register format; format.formatter must be a function'); expect( StyleDictionaryExtended.registerFormat.bind(null, { name: 'test', formatter: {} }) - ).toThrow('format formatter must be a function'); + ).toThrow('Can\'t register format; format.formatter must be a function'); }); - it('should work if name and formatter are good', () => { + it('should work if name and format are good', () => { StyleDictionaryExtended.registerFormat({ name: 'scss', formatter: function() {} diff --git a/docs/api.md b/docs/api.md index 2a3e46525..3d7c5342d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -203,11 +203,13 @@ StyleDictionary.registerFormat({ * * * ### registerTemplate -> StyleDictionary.registerTemplate(template) ⇒ [style-dictionary](#module_style-dictionary) +> ~~StyleDictionary.registerTemplate(template) ⇒ [style-dictionary](#module_style-dictionary)~~ +***Deprecated*** + Add a custom template to the Style Dictionary diff --git a/docs/extending.md b/docs/extending.md index c966db9a6..e3ed1904e 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -1,6 +1,6 @@ # Extending -The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms, templates, and formats. +The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms and formats. * [registerTransform](api.md#registertransform) * [registerTransformGroup](api.md#registertransformgroup) diff --git a/docs/formats.md b/docs/formats.md index 6301d1160..91eef1561 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -1,11 +1,12 @@ # Formats -Formats are one of the ways to create files that act as interfaces for your style dictionary. For example, you want to be able to -use your style dictionary in CSS. You can use the `css/variables` template which will create a CSS file with variables from -your style dictionary. You can define custom formats with the [`registerFormat`](api.md#registerformat). +Formats define the output of your created files. For example, to use your styles in CSS +you use the `css/variables` format. This will create a CSS file containing the variables from +your style dictionary. -Templates and Formats serve the same purpose: use your style dictionary as data to build a file. You use formats in your config -file under platforms > [platform] > files > [file] +### Using formats + +You use formats in your config file under platforms > [platform] > files > [file] ```json { @@ -15,7 +16,7 @@ file under platforms > [platform] > files > [file] "transformGroup": "css", "files": [ { - "template": "css/variables", + "format": "css/variables", "destination": "variables.css" } ] @@ -24,18 +25,67 @@ file under platforms > [platform] > files > [file] } ``` +There is an extensive (but not exhaustive) list of [included formats](#pre-defined-formats) available in Style Dictionary. + + +### Creating Formats + +You can create custom formats using the [`registerFormat`](api.md#registerformat) function. + + +### Using a template / templating engine to create a format + +A formatter is just a simple function and created easily with most templating engines. Templates are useful if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of just the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier. + +Any templating language can work as there is a node module for it. All you need to do is register a format that calls your template and returns a string. + +Here is a quick example for Lodash. + +```js +const styleDictionary = require('style-dictionary').extend('config.json'); +const _ = require('lodash'); ->*__How are Templates different than Formats?__* +const template = _.template( fs.readFileSync('templates/myFormat.template') ); ->Mainly syntactic sugar; anything you can do in a Template you can do in a Format. Use whichever is easier for you to write. We find -that Templates are good if you have a lot of boilerplate code around where the style dictionary will go (like writing ObjectiveC files). -Formats are better if there is little to no boilerplate code like a flat SCSS variables file. +styleDictionary.registerFormat({ + name: 'my/format', + formatter: template +}); + +// format: 'my/format' is now available for use... +``` + +And another example for Handlebars. + +```js +const styleDictionary = require('style-dictionary').extend('config.json'); +const Handlebars = require('handlebars'); + +const template = Handlebars.compile( fs.readFileSync('templates/MyTemplate.hbs') ); + +styleDictionary.registerFormat({ + name: 'my/format', + formatter: function(dictionary, platform) { + return template({ + properties: dictionary.properties, + options: platform + }); + } +}); + +// format: 'my/format' is now available for use... +``` ---- ## Pre-defined Formats -[lib/common/formats.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/formats.js) +These are the formats included in Style Dictionary by default, pulled from [lib/common/formats.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/formats.js) + +Want a format? [You can request it here](https://github.com/amzn/style-dictionary/issues). + +You created a format and think it should be included? [Send us a PR](https://github.com/amzn/style-dictionary/pulls). + ### css/variables @@ -209,6 +259,240 @@ export const ColorBackgroundBase = '#ffffff'; export const ColorBackgroundAlt = '#fcfcfcfc'; ``` +* * * + +### android/colors + + +Creates a color resource xml file with all the colors in your style dictionary. + +**Example** +```xml + + + #fffaf3f2 + #fff0cccc + #ffe19d9c +``` + +* * * + +### android/dimens + + +Creates a dimen resource xml file with all the sizes in your style dictionary. + +**Example** +```xml + + + 5.00dp + 10.00dp + 15.00dp +``` + +* * * + +### android/fontDimens + + +Creates a dimen resource xml file with all the font sizes in your style dictionary. + +**Example** +```xml + + + 10.00sp + 13.00sp + 15.00sp +``` + +* * * + +### android/integers + + +Creates a resource xml file with all the integers in your style dictionary. It filters your +style properties by `prop.attributes.category === 'time'` + +**Todo** + +- Update the filter on this. + +**Example** +```xml + + + 1000 + 2000 + 4000 +``` + +* * * + +### android/strings + + +Creates a resource xml file with all the strings in your style dictionary. Filters your +style properties by `prop.attributes.category === 'content'` + +**Example** +```xml + + + + + +``` + +* * * + +### ios/macros + + +Creates an Objective-C header file with macros for style properties + +**Example** +```objectivec +#import +#import + +#define ColorFontLink [UIColor colorWithRed:0.00f green:0.47f blue:0.80f alpha:1.00f] +#define SizeFontTiny 176.00f +``` + +* * * + +### ios/plist + + +Creates an Objective-C plist file + +**Todo** + +- Fix this template and add example and usage + + +* * * + +### ios/singleton.m + + +Creates an Objective-C implementation file of a style dictionary singleton class + +**Todo** + +- Add example and usage + + +* * * + +### ios/singleton.h + + +Creates an Objective-C header file of a style dictionary singleton class + +**Todo** + +- Add example and usage + + +* * * + +### ios/static.h + + +Creates an Objective-C header file of a static style dictionary class + +**Todo** + +- Add example and usage + + +* * * + +### ios/static.m + + +Creates an Objective-C implementation file of a static style dictionary class + +**Todo** + +- Add example and usage + + +* * * + +### ios/colors.h + + +Creates an Objective-C header file of a color class + +**Todo** + +- Add example and usage + + +* * * + +### ios/colors.m + + +Creates an Objective-C implementation file of a color class + +**Todo** + +- Add example and usage + + +* * * + +### ios/strings.h + + +Creates an Objective-C header file of strings + +**Todo** + +- Add example and usage + + +* * * + +### ios/strings.m + + +Creates an Objective-C implementation file of strings + +**Todo** + +- Add example and usage + + +* * * + +### css/fonts.css + + +Creates CSS file with @font-face declarations + +**Todo** + +- Add example and usage + + +* * * + +### static-style-guide/index.html + + +Creates a generic static html page + +**Todo** + +- Add example and usage + + * * * ### json @@ -288,4 +572,3 @@ Creates a sketchpalette file of all the base colors ``` * * * - diff --git a/docs/package_structure.md b/docs/package_structure.md index 61e523b74..95babcf1d 100644 --- a/docs/package_structure.md +++ b/docs/package_structure.md @@ -40,7 +40,7 @@ The default way is to use a config.json file in the root of your package. Here i "files": [{ "filter": { "category": "color" }, "destination": "style_dictionary_colors.xml", - "template": "android/colors" + "format": "android/colors" }] } } @@ -50,15 +50,14 @@ The default way is to use a config.json file in the root of your package. Here i | Attribute | Type | Description | | :--- | :--- | :--- | | source | Array[String] | An array of paths to JSON files that contain style properties. The Style Dictionary will do a deep merge of all of the JSON files so you can separate your properties into multiple files. | -| platforms | Object | An object containing platform config objects that describe how the Style Dictionary should build for that platform. You can add any arbitrary attributes on this object that will get passed to formats/templates and actions (more on these in a bit). This is useful for things like build paths, name prefixes, variable names, etc. | +| platforms | Object | An object containing platform config objects that describe how the Style Dictionary should build for that platform. You can add any arbitrary attributes on this object that will get passed to formats and actions (more on these in a bit). This is useful for things like build paths, name prefixes, variable names, etc. | | platform.transforms | Array[String] (optional) | An array of [transforms](transforms.md) to be performed on the style properties object. These will transform the properties in a non-desctructive way so each platform can transform the properties. Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. | | platform.transformGroup | String (optional) | A string that maps to an array of transforms. This makes it easier to reference transforms by grouping them together. You must either define this or `transforms`. | | platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. | | platform.files | Array (optional) | Files to be generated for this platform. | | platform.file.destination | String (optional) | Location to build the file, will be appended to the buildPath. | -| platform.file.format | String (optional) | [Format](formats.md) used to generate the file. Can be a built-in one or you can create your own. Must declare a format or a template. | +| platform.file.format | String (optional) | [Format](formats.md) used to generate the file. Can be a built-in one or you can create your own. | | platform.file.filter | Function/Object (optional) | A function or object used to filter the properties that will be included in the file. If a function is provided, each property will be passed to the function and the result (true or false) will determine whether the property is included. If an object is provided, each property will be matched against the object using a partial deep comparison to determine whether the property is included. | -| platform.file.template | String (optional) | [Template](templates.md) used to generate the file. Can be a built-in one or you can create your own. | | platform.file.options | Object (optional) | A set of extra options associated with the file. | | platform.file.options.showFileHeader | Boolean | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true". | | platform.actions | Array[String] (optional) | [Actions](actions.md) to be performed after the files are built for that platform. Actions can be any arbitrary code you want to run like copying files, generating assets, etc. You can use pre-defined actions or create custom actions. | diff --git a/docs/templates.md b/docs/templates.md index 7d5d580b5..b60932215 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -1,283 +1,7 @@ # Templates -Templates are one of the ways to create files that act as interfaces for your style dictionary. For example, you want to be able to -use your style dictionary in Android. You can use the `android/colors` template which will create an Anroid resource XML file from -your style dictionary. You can define custom templates with the [`registerTemplate`](api.md#registertemplate). +Templates are deprecated in favor of [Formats](formats.md) and will be removed in the future. If you want to create a custom template, create a [Format that uses templating](formats.md#using-a-template-templating-engine-to-create-a-format). -Templates and Formats serve the same purpose: use your style dictionary as data to build a file. You use templates in your config -file under platforms > [platform] > files > [file] +>*__Why are Templates being deprecated in favor of Formats?__* -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "android": { - "transformGroup": "android", - "files": [ - { - "template": "android/colors", - "destination": "colors.xml" - } - ] - } - } -} -``` - ->*__How are Templates different than Formats?__* - ->Mainly syntactic sugar; anything you can do in a Template you can do in a Format. Use whichever is easier for you to write. We find -that Templates are good if you have a lot of boilerplate code around where the style dictionary will go (like writing ObjectiveC files). -Formats are better if there is little to no boilerplate code like a flat SCSS variables file. - -### Using a different templating language - -If you are partial to Handlebars or some other templating language, anything will work as long as there is a node module for it. -All you need to do is register a custom format which calls your template and returns a string. Here is a quick example for Handlebars. - -```js -const StyleDictionary = require('style-dictionary').extend('config.json'); -const Handlebars = require('handlebars'); - -const template = Handlebars.compile( fs.readFileSync('templates/MyTemplate.hbs') ); - -styleDictionary.registerFormat({ - name: 'myTemplate', - formatter: function(dictionary, platform) { - return template({ - properties: dictionary.properties, - options: platform - }); - } -}); - -styleDictionary.buildAllPlatforms(); -``` - ----- - -## Pre-defined Templates - -[lib/common/templates.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/templates.js) - -### android/colors - - -Creates a color resource xml file with all the colors in your style dictionary. - -**Example** -```xml - - - #fffaf3f2 - #fff0cccc - #ffe19d9c -``` - -* * * - -### android/dimens - - -Creates a dimen resource xml file with all the sizes in your style dictionary. - -**Example** -```xml - - - 5.00dp - 10.00dp - 15.00dp -``` - -* * * - -### android/fontDimens - - -Creates a dimen resource xml file with all the font sizes in your style dictionary. - -**Example** -```xml - - - 10.00sp - 13.00sp - 15.00sp -``` - -* * * - -### android/integers - - -Creates a resource xml file with all the integers in your style dictionary. It filters your -style properties by `prop.attributes.category === 'time'` - -**Todo** - -- Update the filter on this. - -**Example** -```xml - - - 1000 - 2000 - 4000 -``` - -* * * - -### android/strings - - -Creates a resource xml file with all the strings in your style dictionary. Filters your -style properties by `prop.attributes.category === 'content'` - -**Example** -```xml - - - - - -``` - -* * * - -### ios/macros - - -Creates an Objective-C header file with macros for style properties - -**Example** -```objectivec -#import -#import - -#define ColorFontLink [UIColor colorWithRed:0.00f green:0.47f blue:0.80f alpha:1.00f] -#define SizeFontTiny 176.00f -``` - -* * * - -### ios/plist - - -Creates an Objective-C plist file - -**Todo** - -- Fix this template and add example and usage - - -* * * - -### ios/singleton.m - - -Creates an Objective-C implementation file of a style dictionary singleton class - -**Todo** - -- Add example and usage - - -* * * - -### ios/singleton.h - - -Creates an Objective-C header file of a style dictionary singleton class - -**Todo** - -- Add example and usage - - -* * * - -### ios/static.h - - -Creates an Objective-C header file of a static style dictionary class - -**Todo** - -- Add example and usage - - -* * * - -### ios/static.m - - -Creates an Objective-C implementation file of a static style dictionary class - -**Todo** - -- Add example and usage - - -* * * - -### ios/colors.h - - -Creates an Objective-C header file of a color class - -**Todo** - -- Add example and usage - - -* * * - -### ios/colors.m - - -Creates an Objective-C implementation file of a color class - -**Todo** - -- Add example and usage - - -* * * - -### ios/strings.h - - -Creates an Objective-C header file of strings - -**Todo** - -- Add example and usage - - -* * * - -### ios/strings.m - - -Creates an Objective-C implementation file of strings - -**Todo** - -- Add example and usage - - -* * * - -### css/fonts.css - - -Creates CSS file with @font-face declarations - -**Todo** - -- Add example and usage - - -* * * +>It is a simplification for users, no power is being removed. Templates were syntactic sugar; anything you could do in a Template you can do in a Format. Since they both did the same thing people became confused on which method they were supposed to use for output. Even worse, we actually required you to know if the output you wanted was created as a format or as a template, even for those formats and template included in Style Dictionary by default. This was a bad plan and caused problems. Additionally, Style Dictionary aims to provide power and flexibility without forcing you to use any particular system and only Lodash Templates were supported under the old system. Using formats, you can use any Templating engine you would like. diff --git a/example/basic/README.md b/example/basic/README.md index 852f841fb..dbdabab7d 100644 --- a/example/basic/README.md +++ b/example/basic/README.md @@ -136,4 +136,4 @@ Now lets make a change and see how that affects things. Open up `properties/colo **Huzzah!** -Now go forth and create! Take a look at all the built-in [transforms](https://amzn.github.io/style-dictionary/transforms#built-in-transforms), [formats, and templates](https://amzn.github.io/style-dictionary/formats_and_templates#built-in-formats). +Now go forth and create! Take a look at all the built-in [transforms](https://amzn.github.io/style-dictionary/#/transforms?id=pre-defined-transforms) and [formats](https://amzn.github.io/style-dictionary/#/formats?id=pre-defined-formats). diff --git a/example/basic/config.json b/example/basic/config.json index 1ad87b61e..942e328ac 100644 --- a/example/basic/config.json +++ b/example/basic/config.json @@ -14,10 +14,10 @@ "buildPath": "build/android/", "files": [{ "destination": "font_dimens.xml", - "template": "android/fontDimens" + "format": "android/fontDimens" },{ "destination": "colors.xml", - "template": "android/colors" + "format": "android/colors" }] }, "ios": { @@ -25,7 +25,7 @@ "buildPath": "build/ios/", "files": [{ "destination": "StyleDictionaryColor.h", - "template": "ios/colors.h", + "format": "ios/colors.h", "className": "StyleDictionaryColor", "type": "StyleDictionaryColorName", "filter": { @@ -35,7 +35,7 @@ } },{ "destination": "StyleDictionaryColor.m", - "template": "ios/colors.m", + "format": "ios/colors.m", "className": "StyleDictionaryColor", "type": "StyleDictionaryColorName", "filter": { @@ -45,7 +45,7 @@ } },{ "destination": "StyleDictionarySize.h", - "template": "ios/static.h", + "format": "ios/static.h", "className": "StyleDictionarySize", "type": "float", "filter": { @@ -55,7 +55,7 @@ } },{ "destination": "StyleDictionarySize.m", - "template": "ios/static.m", + "format": "ios/static.m", "className": "StyleDictionarySize", "type": "float", "filter": { diff --git a/example/complete/config.json b/example/complete/config.json index 92dad20df..00f8cd07b 100644 --- a/example/complete/config.json +++ b/example/complete/config.json @@ -9,7 +9,7 @@ "prefix": "StyleDictionary", "files": [{ "destination": "StyleDictionarySize.h", - "template": "ios/static.h", + "format": "ios/static.h", "type": "float", "className": "StyleDictionarySize", "filter": { @@ -19,7 +19,7 @@ } },{ "destination": "StyleDictionarySize.m", - "template": "ios/static.m", + "format": "ios/static.m", "type": "float", "className": "StyleDictionarySize", "filter": { @@ -29,7 +29,7 @@ } },{ "destination": "StyleDictionaryIcons.h", - "template": "ios/strings.h", + "format": "ios/strings.h", "className": "StyleDictionaryIcons", "filter": { "attributes": { @@ -39,7 +39,7 @@ } },{ "destination": "StyleDictionaryIcons.m", - "template": "ios/strings.m", + "format": "ios/strings.m", "className": "StyleDictionaryIcons", "filter": { "attributes": { @@ -49,7 +49,7 @@ } },{ "destination": "StyleDictionaryColor.h", - "template": "ios/colors.h", + "format": "ios/colors.h", "className": "StyleDictionaryColor", "type": "StyleDictionaryColorName", "filter": { @@ -59,7 +59,7 @@ } },{ "destination": "StyleDictionaryColor.m", - "template": "ios/colors.m", + "format": "ios/colors.m", "className": "StyleDictionaryColor", "type": "StyleDictionaryColorName", "filter": { @@ -69,11 +69,11 @@ } },{ "destination": "StyleDictionaryProperties.h", - "template": "ios/singleton.h", + "format": "ios/singleton.h", "className": "StyleDictionaryProperties" },{ "destination": "StyleDictionaryProperties.m", - "template": "ios/singleton.m", + "format": "ios/singleton.m", "className": "StyleDictionaryProperties" }] }, @@ -86,16 +86,16 @@ "template": "android/colors" },{ "destination": "style_dictionary_font_dimens.xml", - "template": "android/fontDimens" + "format": "android/fontDimens" },{ "destination": "style_dictionary_dimens.xml", - "template": "android/dimens" + "format": "android/dimens" },{ "destination": "style_dictionary_integers.xml", - "template": "android/integers" + "format": "android/integers" },{ "destination": "style_dictionary_strings.xml", - "template": "android/strings" + "format": "android/strings" }] }, diff --git a/example/s3/config.json b/example/s3/config.json index b5fe9cdfe..0912ec013 100644 --- a/example/s3/config.json +++ b/example/s3/config.json @@ -8,14 +8,14 @@ "buildPath": "build/ios/", "files": [{ "destination": "StyleDictionaryMacros.h", - "template": "ios/macros" + "format": "ios/macros" },{ "destination": "StyleDictionary.h", - "template": "ios/singleton.h", + "format": "ios/singleton.h", "className": "StyleDictionary" },{ "destination": "StyleDictionary.m", - "template": "ios/singleton.m", + "format": "ios/singleton.m", "className": "StyleDictionary" }] }, @@ -25,19 +25,19 @@ "buildPath": "build/android/", "files": [{ "destination": "style_dictionary_colors.xml", - "template": "android/colors" + "format": "android/colors" },{ "destination": "style_dictionary_font_dimens.xml", - "template": "android/fontDimens" + "format": "android/fontDimens" },{ "destination": "style_dictionary_dimens.xml", - "template": "android/dimens" + "format": "android/dimens" },{ "destination": "style_dictionary_integers.xml", - "template": "android/integers" + "format": "android/integers" },{ "destination": "style_dictionary_strings.xml", - "template": "android/strings" + "format": "android/strings" }] }, diff --git a/index.js b/index.js index 2022cdc2e..aedb740a1 100644 --- a/index.js +++ b/index.js @@ -10,6 +10,10 @@ * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions * and limitations under the License. */ +var chalk = require('chalk'); +var GroupMessages = require('./lib/utils/groupMessages'); +var TEMPLATE_DEPRECATION_WARNINGS = GroupMessages.GROUP.TemplateDeprecationWarnings; +var REGISTER_TEMPLATE_DEPRECATION_WARNINGS = GroupMessages.GROUP.RegisterTemplateDeprecationWarnings; /** * Style Dictionary module @@ -32,7 +36,6 @@ var StyleDictionary = { transform: require('./lib/common/transforms'), transformGroup: require('./lib/common/transformGroups'), format: require('./lib/common/formats'), - template: require('./lib/common/templates'), action: require('./lib/common/actions'), registerTransform: require('./lib/register/transform'), @@ -52,3 +55,62 @@ var StyleDictionary = { }; module.exports = StyleDictionary; + +process.on('exit', function () { + if(GroupMessages.count(TEMPLATE_DEPRECATION_WARNINGS) > 0) { + var template_warnings = GroupMessages.flush(TEMPLATE_DEPRECATION_WARNINGS).join('\n '); + console.log(chalk.bold.yellow(` +⚠️ DEPRECATION WARNING ️️️️️⚠️ +Templates are deprecated and will be removed, please update your config to use formats. +This is an example of how to update your config.json: + +Before: + "files": [{ + "destination": "colors.xml", + "template": "android/colors" + }] + +After: + "files": [{ + "destination": "colors.xml", + "format": "android/colors" + }] + +Your current config used the following templates: + ${template_warnings} +`)); + } + + if(GroupMessages.count(REGISTER_TEMPLATE_DEPRECATION_WARNINGS) > 0) { + var register_template_warnings = GroupMessages.flush(REGISTER_TEMPLATE_DEPRECATION_WARNINGS).join('\n '); + console.log(chalk.bold.yellow(` +⚠️ DEPRECATION WARNING ️️️️️⚠️ +The registerTemplate method is deprecated and will be removed, please +migrate to registerFormat. You can use any templating engine you would +like, you just need to require/import it. This is an example of how to +update your code using a lodash template (the template engine previously +used by registerTemplate): + +Before: + registerTemplate({ + name: 'template/name', + template: templateFile, + }); + +After: + registerFormat({ + name: 'template/name', + formatter: _.template( fs.readFileSync( templateFile ) ), + }); + +Note that formatter is a function that takes in a style dictionary +and returns a string with the formatted output. There is a second +argument available that contains the configuration being used to +process the style dictionary. + +Calls to registerTemplate included the registration of the following +custom templates: + ${register_template_warnings}`)); + } + +}); diff --git a/lib/buildFiles.js b/lib/buildFiles.js index ec347a16f..7b1089931 100644 --- a/lib/buildFiles.js +++ b/lib/buildFiles.js @@ -30,12 +30,10 @@ function buildFiles(dictionary, platform) { } _.each(platform.files, function (file) { - if (file.template) { - buildFile(file.destination, file.template.bind(file), platform, dictionary, file.filter); - } else if (file.format) { + if (file.format) { buildFile(file.destination, file.format.bind(file), platform, dictionary, file.filter); } else { - throw new Error('Please supply a template or formatter') + throw new Error('Please supply a format'); } }); } diff --git a/lib/cleanDirs.js b/lib/cleanDirs.js index a5e0b8b8f..fdfd08a24 100644 --- a/lib/cleanDirs.js +++ b/lib/cleanDirs.js @@ -29,14 +29,12 @@ function cleanDirs(dictionary, platform) { throw new Error('Build path must end in a trailing slash or you will get weird file names.') } - // while neither the template, format, or dictionary are used by clean file I'm passing them in for symmetry to buildFile + // while neither the format or dictionary are used by clean file I'm passing them in for symmetry to buildFile _.each(platform.files, function (file) { - if (file.template) { - cleanDir(file.destination, file.template.bind(file), platform, dictionary); - } else if (file.format) { + if (file.format) { cleanDir(file.destination, file.format.bind(file), platform, dictionary); } else { - throw new Error('Please supply a template or formatter') + throw new Error('Please supply a format') } }); } diff --git a/lib/cleanFiles.js b/lib/cleanFiles.js index e9ec068a1..5c6c8bb9f 100644 --- a/lib/cleanFiles.js +++ b/lib/cleanFiles.js @@ -29,11 +29,9 @@ function cleanFiles(dictionary, platform) { throw new Error('Build path must end in a trailing slash or you will get weird file names.') } - // while neither the template, format, or dictionary are used by clean file I'm passing them in for symmetry to buildFile + // while neither the format or dictionary are used by clean file I'm passing them in for symmetry to buildFile _.each(platform.files, function (file) { - if (file.template) { - cleanFile(file.destination, file.template.bind(file), platform, dictionary); - } else if (file.format) { + if (file.format) { cleanFile(file.destination, file.format.bind(file), platform, dictionary); } else { throw new Error('Please supply a template or formatter') diff --git a/lib/common/formats.js b/lib/common/formats.js index 68489adab..b9a222bc8 100644 --- a/lib/common/formats.js +++ b/lib/common/formats.js @@ -11,7 +11,8 @@ * and limitations under the License. */ -var _ = require('lodash'); +var fs = require('fs'), + _ = require('lodash'); function fileHeader(options) { var to_ret = ''; @@ -293,6 +294,233 @@ module.exports = { }).join('\n'); }, + // Android templates + /** + * Creates a color resource xml file with all the colors in your style dictionary. + * + * @memberof Formats + * @kind member + * @example + * ```xml + * + * + * #fffaf3f2 + * #fff0cccc + * #ffe19d9c + * ``` + */ + 'android/colors': _.template( + fs.readFileSync(__dirname + '/templates/android/colors.template') + ), + + /** + * Creates a dimen resource xml file with all the sizes in your style dictionary. + * + * @memberof Formats + * @kind member + * @example + * ```xml + * + * + * 5.00dp + * 10.00dp + * 15.00dp + * ``` + */ + 'android/dimens': _.template( + fs.readFileSync(__dirname + '/templates/android/dimens.template') + ), + + /** + * Creates a dimen resource xml file with all the font sizes in your style dictionary. + * + * @memberof Formats + * @kind member + * @example + * ```xml + * + * + * 10.00sp + * 13.00sp + * 15.00sp + * ``` + */ + 'android/fontDimens': _.template( + fs.readFileSync(__dirname + '/templates/android/fontDimens.template') + ), + + /** + * Creates a resource xml file with all the integers in your style dictionary. It filters your + * style properties by `prop.attributes.category === 'time'` + * + * @memberof Formats + * @kind member + * @todo Update the filter on this. + * @example + * ```xml + * + * + * 1000 + * 2000 + * 4000 + * ``` + */ + 'android/integers': _.template( + fs.readFileSync(__dirname + '/templates/android/integers.template') + ), + + /** + * Creates a resource xml file with all the strings in your style dictionary. Filters your + * style properties by `prop.attributes.category === 'content'` + * + * @memberof Formats + * @kind member + * @example + * ```xml + * + * + * + * + * + * ``` + */ + 'android/strings': _.template( + fs.readFileSync(__dirname + '/templates/android/strings.template') + ), + + // iOS templates + /** + * Creates an Objective-C header file with macros for style properties + * + * @memberof Formats + * @kind member + * @example + * ```objectivec + * #import + * #import + * + * #define ColorFontLink [UIColor colorWithRed:0.00f green:0.47f blue:0.80f alpha:1.00f] + * #define SizeFontTiny 176.00f + * ``` + */ + 'ios/macros': _.template( + fs.readFileSync(__dirname + '/templates/ios/macros.template') + ), + + /** + * Creates an Objective-C plist file + * + * @memberof Formats + * @kind member + * @todo Fix this template and add example and usage + */ + 'ios/plist': _.template( + fs.readFileSync(__dirname + '/templates/ios/plist.template') + ), + + /** + * Creates an Objective-C implementation file of a style dictionary singleton class + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/singleton.m': _.template( + fs.readFileSync(__dirname + '/templates/ios/singleton.m.template') + ), + + /** + * Creates an Objective-C header file of a style dictionary singleton class + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/singleton.h': _.template( + fs.readFileSync(__dirname + '/templates/ios/singleton.h.template') + ), + + /** + * Creates an Objective-C header file of a static style dictionary class + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/static.h': _.template( + fs.readFileSync(__dirname + '/templates/ios/static.h.template') + ), + + /** + * Creates an Objective-C implementation file of a static style dictionary class + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/static.m': _.template( + fs.readFileSync(__dirname + '/templates/ios/static.m.template') + ), + + /** + * Creates an Objective-C header file of a color class + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/colors.h': _.template( + fs.readFileSync(__dirname + '/templates/ios/colors.h.template') + ), + + /** + * Creates an Objective-C implementation file of a color class + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/colors.m': _.template( + fs.readFileSync(__dirname + '/templates/ios/colors.m.template') + ), + + /** + * Creates an Objective-C header file of strings + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/strings.h': _.template( + fs.readFileSync(__dirname + '/templates/ios/strings.h.template') + ), + + /** + * Creates an Objective-C implementation file of strings + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'ios/strings.m': _.template( + fs.readFileSync(__dirname + '/templates/ios/strings.m.template') + ), + + // Css templates + + /** + * Creates CSS file with @font-face declarations + * + * @memberof Formats + * @kind member + * @todo Add example and usage + */ + 'css/fonts.css': _.template( + fs.readFileSync(__dirname + '/templates/css/fonts.css.template') + ), + + // Web templates + /** * Creates a JSON file of the style dictionary. * diff --git a/lib/common/templates.js b/lib/common/templates.js deleted file mode 100644 index c8b881b30..000000000 --- a/lib/common/templates.js +++ /dev/null @@ -1,215 +0,0 @@ -/* - * Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with - * the License. A copy of the License is located at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR - * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions - * and limitations under the License. - */ - -var fs = require('fs'), - _ = require('lodash'); - -/** - * @namespace Templates - */ -module.exports = { - // Android templates - - /** - * Creates a color resource xml file with all the colors in your style dictionary. - * - * @memberof Templates - * @example - * ```xml - * - * - * #fffaf3f2 - * #fff0cccc - * #ffe19d9c - * ``` - */ - 'android/colors': _.template( - fs.readFileSync(__dirname + '/templates/android/colors.template')), - - /** - * Creates a dimen resource xml file with all the sizes in your style dictionary. - * - * @memberof Templates - * @example - * ```xml - * - * - * 5.00dp - * 10.00dp - * 15.00dp - * ``` - */ - 'android/dimens': _.template( - fs.readFileSync(__dirname + '/templates/android/dimens.template')), - - /** - * Creates a dimen resource xml file with all the font sizes in your style dictionary. - * - * @memberof Templates - * @example - * ```xml - * - * - * 10.00sp - * 13.00sp - * 15.00sp - * ``` - */ - 'android/fontDimens': _.template( - fs.readFileSync(__dirname + '/templates/android/fontDimens.template')), - - /** - * Creates a resource xml file with all the integers in your style dictionary. It filters your - * style properties by `prop.attributes.category === 'time'` - * - * @memberof Templates - * @todo Update the filter on this. - * @example - * ```xml - * - * - * 1000 - * 2000 - * 4000 - * ``` - */ - 'android/integers': _.template( - fs.readFileSync(__dirname + '/templates/android/integers.template')), - - /** - * Creates a resource xml file with all the strings in your style dictionary. Filters your - * style properties by `prop.attributes.category === 'content'` - * - * @memberof Templates - * @example - * ```xml - * - * - * - * - * - * ``` - */ - 'android/strings': _.template( - fs.readFileSync(__dirname + '/templates/android/strings.template')), - - // iOS templates - - /** - * Creates an Objective-C header file with macros for style properties - * - * @memberof Templates - * @example - * ```objectivec - * #import - * #import - * - * #define ColorFontLink [UIColor colorWithRed:0.00f green:0.47f blue:0.80f alpha:1.00f] - * #define SizeFontTiny 176.00f - * ``` - */ - 'ios/macros': _.template( - fs.readFileSync(__dirname + '/templates/ios/macros.template')), - - /** - * Creates an Objective-C plist file - * - * @memberof Templates - * @todo Fix this template and add example and usage - */ - 'ios/plist': _.template( - fs.readFileSync(__dirname + '/templates/ios/plist.template')), - - /** - * Creates an Objective-C implementation file of a style dictionary singleton class - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/singleton.m': _.template( - fs.readFileSync(__dirname + '/templates/ios/singleton.m.template')), - - /** - * Creates an Objective-C header file of a style dictionary singleton class - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/singleton.h': _.template( - fs.readFileSync(__dirname + '/templates/ios/singleton.h.template')), - - /** - * Creates an Objective-C header file of a static style dictionary class - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/static.h': _.template( - fs.readFileSync(__dirname + '/templates/ios/static.h.template')), - - /** - * Creates an Objective-C implementation file of a static style dictionary class - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/static.m': _.template( - fs.readFileSync(__dirname + '/templates/ios/static.m.template')), - - /** - * Creates an Objective-C header file of a color class - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/colors.h': _.template( - fs.readFileSync(__dirname + '/templates/ios/colors.h.template')), - - /** - * Creates an Objective-C implementation file of a color class - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/colors.m': _.template( - fs.readFileSync(__dirname + '/templates/ios/colors.m.template')), - - /** - * Creates an Objective-C header file of strings - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/strings.h': _.template( - fs.readFileSync(__dirname + '/templates/ios/strings.h.template')), - - /** - * Creates an Objective-C implementation file of strings - * - * @memberof Templates - * @todo Add example and usage - */ - 'ios/strings.m': _.template( - fs.readFileSync(__dirname + '/templates/ios/strings.m.template')), - - // Css templates - - /** - * Creates CSS file with @font-face declarations - * - * @memberof Templates - * @todo Add example and usage - */ - 'css/fonts.css': _.template( - fs.readFileSync(__dirname + '/templates/css/fonts.css.template')), -}; diff --git a/lib/common/templates/css/fonts.css.template b/lib/common/templates/css/fonts.css.template index 3e57aa5d2..3118b45b7 100644 --- a/lib/common/templates/css/fonts.css.template +++ b/lib/common/templates/css/fonts.css.template @@ -1,4 +1,4 @@ -<% _.forIn(properties.asset.font, function(font) { +<% _.forIn(properties && properties.asset && properties.asset.font, function(font) { var fileFormatArr = []; if (font.eot) { fileFormatArr.push("url('../" + font.eot.value + "');\n\tsrc: url('../" + font.eot.value + "?#iefix') format('embedded-opentype')"); @@ -25,4 +25,4 @@ font-style: <%= font.style.value %>;<% } if (font.weight) { %> font-weight: <%= font.weight.value %>;<% } %> } -<% }); %> \ No newline at end of file +<% }); %> diff --git a/lib/common/templates/ios/colors.h.template b/lib/common/templates/ios/colors.h.template index dffe2f89e..8ff68aa8c 100644 --- a/lib/common/templates/ios/colors.h.template +++ b/lib/common/templates/ios/colors.h.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/colors.m.template b/lib/common/templates/ios/colors.m.template index 721718920..6066c154f 100644 --- a/lib/common/templates/ios/colors.m.template +++ b/lib/common/templates/ios/colors.m.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/macros.template b/lib/common/templates/ios/macros.template index 99b6fa69e..277a8bfcc 100644 --- a/lib/common/templates/ios/macros.template +++ b/lib/common/templates/ios/macros.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/plist.template b/lib/common/templates/ios/plist.template index 3a046b8d3..9836d2e8a 100644 --- a/lib/common/templates/ios/plist.template +++ b/lib/common/templates/ios/plist.template @@ -26,7 +26,7 @@ var props = _.filter(allProperties, function(prop) { var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print(""); } %> diff --git a/lib/common/templates/ios/singleton.h.template b/lib/common/templates/ios/singleton.h.template index 63d3c4603..f31abae0f 100644 --- a/lib/common/templates/ios/singleton.h.template +++ b/lib/common/templates/ios/singleton.h.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/singleton.m.template b/lib/common/templates/ios/singleton.m.template index de497e41b..de939fa5f 100644 --- a/lib/common/templates/ios/singleton.m.template +++ b/lib/common/templates/ios/singleton.m.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/static.h.template b/lib/common/templates/ios/static.h.template index 675a258ca..1862bea5a 100644 --- a/lib/common/templates/ios/static.h.template +++ b/lib/common/templates/ios/static.h.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/static.m.template b/lib/common/templates/ios/static.m.template index 0fdbfb5da..e3113bf32 100644 --- a/lib/common/templates/ios/static.m.template +++ b/lib/common/templates/ios/static.m.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/strings.h.template b/lib/common/templates/ios/strings.h.template index b529021b5..8c0bc0a27 100644 --- a/lib/common/templates/ios/strings.h.template +++ b/lib/common/templates/ios/strings.h.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/common/templates/ios/strings.m.template b/lib/common/templates/ios/strings.m.template index 34c87e283..d8b302e96 100644 --- a/lib/common/templates/ios/strings.m.template +++ b/lib/common/templates/ios/strings.m.template @@ -21,7 +21,7 @@ var showFileHeader = (this.options && this.options.hasOwnProperty('showFileHeader')) ? this.options.showFileHeader : true; if(showFileHeader) { print("// Do not edit directly\n"); - print("// Generated on " + new Date()); + print("// Generated on " + new Date().toUTCString()); } %> // diff --git a/lib/register/format.js b/lib/register/format.js index 44d76e0a4..00f4372d4 100644 --- a/lib/register/format.js +++ b/lib/register/format.js @@ -11,7 +11,6 @@ * and limitations under the License. */ - /** * Add a custom format to the style dictionary * @static @@ -33,11 +32,12 @@ */ function registerFormat(options) { if (typeof options.name !== 'string') - throw new Error('transform name must be a string'); + throw new Error('Can\'t register format; format.name must be a string'); if (typeof options.formatter !== 'function') - throw new Error('format formatter must be a function'); + throw new Error('Can\'t register format; format.formatter must be a function'); this.format[options.name] = options.formatter; + return this; } diff --git a/lib/register/template.js b/lib/register/template.js index 203e236c5..4e4560409 100644 --- a/lib/register/template.js +++ b/lib/register/template.js @@ -13,11 +13,15 @@ var fs = require('fs'), _ = require('lodash'), - chalk = require('chalk'); + chalk = require('chalk'), + GroupMessages = require('../utils/groupMessages'); + +var REGISTER_TEMPLATE_DEPRECATION_WARNINGS = GroupMessages.GROUP.RegisterTemplateDeprecationWarnings; /** * Add a custom template to the Style Dictionary * @static + * @deprecated registerTemplate will be removed in the future, please use registerFormat * @memberof module:style-dictionary * @param {Object} template * @param {String} template.name - The name of your template. You will refer to this in your config.json file. @@ -39,9 +43,14 @@ function registerTemplate(options) { if (!fs.existsSync(options.template)) throw new Error('Can\'t find template: ' + chalk.red(JSON.stringify(options.template))); + GroupMessages.add( + REGISTER_TEMPLATE_DEPRECATION_WARNINGS, + `${options.name}` + ); + var template_string = fs.readFileSync( options.template ); - this.template[options.name] = _.template( template_string ); + this.format[options.name] = _.template( template_string ); return this; } diff --git a/lib/transform/config.js b/lib/transform/config.js index a5df04451..0a97392de 100644 --- a/lib/transform/config.js +++ b/lib/transform/config.js @@ -12,11 +12,14 @@ */ var _ = require('lodash'), - chalk = require('chalk'); + chalk = require('chalk'), + GroupMessages = require('../utils/groupMessages'); + +var TEMPLATE_DEPRECATION_WARNINGS = GroupMessages.GROUP.TemplateDeprecationWarnings; /** * Takes a platform config object and returns a new one - * that has transforms, formats, templates, and actions + * that has transforms, formats, and actions * mapped properly. * @private * @param {Object} config @@ -50,8 +53,12 @@ function transformConfig(config, dictionary) { to_ret.files = _.map(config.files, function(file) { if (file.template) { - if (dictionary.template[file.template]) { - return _.extend({}, file, {template: dictionary.template[file.template]}); + if (dictionary.format[file.template]) { + GroupMessages.add( + TEMPLATE_DEPRECATION_WARNINGS, + `${file.destination} (template: ${file.template})` + ); + return _.extend({}, file, {format: dictionary.format[file.template]}); } else { throw new Error('Can\'t find template: ' + file.template); } @@ -62,7 +69,7 @@ function transformConfig(config, dictionary) { throw new Error('Can\'t find format: ' + file.format); } } else { - throw new Error('Please supply a format or template for file: ' + JSON.stringify(file)); + throw new Error('Please supply a format for file: ' + JSON.stringify(file)); } }); diff --git a/lib/utils/groupMessages.js b/lib/utils/groupMessages.js index cd24bc82a..bd7a25280 100644 --- a/lib/utils/groupMessages.js +++ b/lib/utils/groupMessages.js @@ -16,6 +16,8 @@ var GroupMessages = { GROUP: { PropertyReferenceWarnings: 'Property Reference Errors', PropertyValueCollisions: 'Property Value Collisions', + TemplateDeprecationWarnings: 'Template Deprecation Warnings', + RegisterTemplateDeprecationWarnings: 'Register Template Deprecation Warnings', }, flush: function (messageGroup) { @@ -29,7 +31,9 @@ var GroupMessages = { if(!groupedMessages[messageGroup]) { groupedMessages[messageGroup] = []; } - groupedMessages[messageGroup].push(message); + if(groupedMessages[messageGroup].indexOf(message) === -1) { + groupedMessages[messageGroup].push(message); + } } }, diff --git a/scripts/generateDocs.js b/scripts/generateDocs.js index 8518cb956..964141940 100644 --- a/scripts/generateDocs.js +++ b/scripts/generateDocs.js @@ -72,17 +72,3 @@ fs.ensureFileSync( FORMATS_PATH ); fs.writeFileSync( FORMATS_PATH, formats ); execSync(`git add ${FORMATS_PATH}`); console.log(FORMATS_PATH + ' generated.'); - -const TEMPLATES_PATH = './docs/templates.md' -const templates = jsdoc2md.renderSync({ - files: ['lib/common/templates.js'], - template: fs.readFileSync('scripts/handlebars/templates/templates.hbs').toString(), - 'no-gfm': true, - separators: true, - partial: ['scripts/handlebars/header.hbs','scripts/handlebars/body.hbs'] -}); - -fs.ensureFileSync( TEMPLATES_PATH ); -fs.writeFileSync( TEMPLATES_PATH, templates ); -execSync(`git add ${TEMPLATES_PATH}`); -console.log(TEMPLATES_PATH + ' generated.'); diff --git a/scripts/handlebars/templates/formats.hbs b/scripts/handlebars/templates/formats.hbs index aabc98a42..678e51563 100644 --- a/scripts/handlebars/templates/formats.hbs +++ b/scripts/handlebars/templates/formats.hbs @@ -1,11 +1,12 @@ # Formats -Formats are one of the ways to create files that act as interfaces for your style dictionary. For example, you want to be able to -use your style dictionary in CSS. You can use the `css/variables` template which will create a CSS file with variables from -your style dictionary. You can define custom formats with the [`registerFormat`](api.md#registerformat). +Formats define the output of your created files. For example, to use your styles in CSS +you use the `css/variables` format. This will create a CSS file containing the variables from +your style dictionary. -Templates and Formats serve the same purpose: use your style dictionary as data to build a file. You use formats in your config -file under platforms > [platform] > files > [file] +### Using formats + +You use formats in your config file under platforms > [platform] > files > [file] ```json { @@ -15,7 +16,7 @@ file under platforms > [platform] > files > [file] "transformGroup": "css", "files": [ { - "template": "css/variables", + "format": "css/variables", "destination": "variables.css" } ] @@ -24,19 +25,66 @@ file under platforms > [platform] > files > [file] } ``` +There is an extensive (but not exhaustive) list of [included formats](#pre-defined-formats) available in Style Dictionary. + + +### Creating Formats + +You can create custom formats using the [`registerFormat`](api.md#registerformat) function. + + +### Using a template / templating engine to create a format + +A formatter is just a simple function and created easily with most templating engines. Templates are useful if there is a lot of boilerplate code to insert (e.g. ObjectiveC files). If the output consists of just the values (e.g. a flat SCSS variables file), writing a formatter function directly may be easier. + +Any templating language can work as there is a node module for it. All you need to do is register a format that calls your template and returns a string. + +Here is a quick example for Lodash. + +```js +const styleDictionary = require('style-dictionary').extend('config.json'); +const _ = require('lodash'); + +const template = _.template( fs.readFileSync('templates/myFormat.template') ); + +styleDictionary.registerFormat({ + name: 'my/format', + formatter: template +}); + +// format: 'my/format' is now available for use... +``` + +And another example for Handlebars. + +```js +const styleDictionary = require('style-dictionary').extend('config.json'); +const Handlebars = require('handlebars'); ->*__How are Templates different than Formats?__* +const template = Handlebars.compile( fs.readFileSync('templates/MyTemplate.hbs').toString() ); ->Mainly syntactic sugar; anything you can do in a Template you can do in a Format. Use whichever is easier for you to write. We find -that Templates are good if you have a lot of boilerplate code around where the style dictionary will go (like writing ObjectiveC files). -Formats are better if there is little to no boilerplate code like a flat SCSS variables file. +styleDictionary.registerFormat({ + name: 'my/format', + formatter: function(dictionary, platform) { + return template({ + properties: dictionary.properties, + options: platform + }); + } +}); + +// format: 'my/format' is now available for use... +``` ---- ## Pre-defined Formats -[lib/common/formats.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/formats.js) +These are the formats included in Style Dictionary by default, pulled from [lib/common/formats.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/formats.js) + +Want a format? [You can request it here](https://github.com/amzn/style-dictionary/issues). + +You created a format and think it should be included? [Send us a PR](https://github.com/amzn/style-dictionary/pulls). + -{{#namespace name="Formats"}} -{{>members~}} -{{/namespace}} +{{#namespace name="Formats"}}{{>members~}}{{/namespace}} diff --git a/scripts/handlebars/templates/templates.hbs b/scripts/handlebars/templates/templates.hbs deleted file mode 100644 index aded13597..000000000 --- a/scripts/handlebars/templates/templates.hbs +++ /dev/null @@ -1,65 +0,0 @@ -# Templates - -Templates are one of the ways to create files that act as interfaces for your style dictionary. For example, you want to be able to -use your style dictionary in Android. You can use the `android/colors` template which will create an Anroid resource XML file from -your style dictionary. You can define custom templates with the [`registerTemplate`](api.md#registertemplate). - -Templates and Formats serve the same purpose: use your style dictionary as data to build a file. You use templates in your config -file under platforms > [platform] > files > [file] - -```json -{ - "source": ["properties/**/*.json"], - "platforms": { - "android": { - "transformGroup": "android", - "files": [ - { - "template": "android/colors", - "destination": "colors.xml" - } - ] - } - } -} -``` - ->*__How are Templates different than Formats?__* - ->Mainly syntactic sugar; anything you can do in a Template you can do in a Format. Use whichever is easier for you to write. We find -that Templates are good if you have a lot of boilerplate code around where the style dictionary will go (like writing ObjectiveC files). -Formats are better if there is little to no boilerplate code like a flat SCSS variables file. - -### Using a different templating language - -If you are partial to Handlebars or some other templating language, anything will work as long as there is a node module for it. -All you need to do is register a custom format which calls your template and returns a string. Here is a quick example for Handlebars. - -```js -const StyleDictionary = require('style-dictionary').extend('config.json'); -const Handlebars = require('handlebars'); - -const template = Handlebars.compile( fs.readFileSync('templates/MyTemplate.hbs') ); - -styleDictionary.registerFormat({ - name: 'myTemplate', - formatter: function(dictionary, platform) { - return template({ - properties: dictionary.properties, - options: platform - }); - } -}); - -styleDictionary.buildAllPlatforms(); -``` - ----- - -## Pre-defined Templates - -[lib/common/templates.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/templates.js) - -{{#namespace name="Templates"}} -{{>members~}} -{{/namespace}}