r_resources 1.0.1 icon indicating copy to clipboard operation
r_resources: ^1.0.1 copied to clipboard

Builder package for generating R file which contains project asset references

r_resources #

pub package style: effective dart Analyzer + Tests License: MIT

This package is made for R-file code generation using build_runner.

R file contains static access to application asset names and inherited access (via BuildContext) to localized String resources.

With this approach you will not be able to make a typo in any resource name.

How to use #

To use the resources code generation add dev dependency in your pubspec.yaml:

dev_dependencies:
  build_runner: <build_runner version here>
  r_resources: ^1.0.1

To generate R-file, run build_runner: flutter pub run build_runner build. r.dart file will be created in lib folder

Plain images and SVG #

In order to generate R-names for image assets, you need to follow these steps:

  1. Create assets folder in project root folder (your_app/assets)
  2. Create images folder for plain image files (such as .png, .jpg, etc.). And/Or create svg folder for .svg files.
  3. Add image assets to these folders.
  4. Add assets to pubspec.yaml:
flutter:
  assets:
    - assets/images/
    - assets/svg/
  1. Run code generation

Note: to add plain images for different scale factors you may add scaled folders inside images folder.

your_app:
  assets:
    images:
      2.0x:
        img.png
      3.0x:
        img.png
      img.png

After r.dart is generated, you can reference assets like follows:

Image.asset(R.images.ic_individual_schools);
SvgPicture.asset(R.svg.ic_filter);

Configuration file #

r_resources provides some configuration to code gen.

Add the r_options.yaml config file to project root folder. Example:

path: 'lib/codegen'

generate_strings: true

supported_locales:
  - en_US
  - en_GB
  - ru

fallback_locale: en_US

Parameters:

path - parameter describing where r.dart would be saved. Path should always start with lib folder. Equals lib by default.

generate_strings - parameter that turns on and off string resources generation. Equals false by default, since you may use other localized strings gen packages.

supported_locales - parameter describing which locales will be supported by your app. Equals en by default. It is only makes sence to add this parameter when generate_strings is true otherwise it will be ignored.

fallback_locale - parameter describing which locale translations will be used in case of missing translations. Equals en by default. It is only makes sence to add this parameter when generate_strings is true otherwise it will be ignored.

Strings #

r_resources provides a simple way to generate string translations to your app.

This generation is turned off dy default.

How to use Strings gen #

To start generating localized strings resources you should set generate_strings parameter to true in configuration file.

Also you may need to configure supported_locales and fallback_locale parameters.

All locale naming used by codegen is using the following format: <language_code>_<country_code>. country_code may be ommited to use generic language code for all nested countries. Examples: en_GB, ru, en. Note that en_GB is not the same as en.

After you configured generate_strings, supported_locales and fallback_locale parameters, you should add translation files to your_app/assets/strings.

In case you specified r_options.yaml like this:

generate_strings: true

supported_locales:
  - en_US
  - en_GB
  - ru

fallback_locale: en_US

then you should add en_US.json, en_GB.json and en_US.json files. And you need to make sure that en_US.json file contains all possible translations, since it will be used as a fallback.

Translations files are single json-s. Field names in different tranlstion files should match.

en_US.json (fallback locale):

{
    "label_lorem_ipsum": "Lorem ipsum",
    "label_color": "Color",
    "format_example": "Your object is ${object} and other is ${other}",
    "label_with_newline": "HELLO!\nI'm new line symbol (\\n)"
}

ru.json:

{
    "label_color": "Цвет",
    "format_example": "Ты передал object = ${object}"
}

With these files have been used to generate R, you can access localized values in code as follows:

Text(R.stringsOf(context).label_lorem_ipsum);
Text(R.stringsOf(context).label_color);

After successfull code generation r.dart will have 2 new classes:

  1. _Strings which instance can be accesed by R.stringsOf(context) and used as localized values container
  2. RStringsDelegate - the LocalizationsDelegate for type _Strings

You should use RStringsDelegate to configure localizations of your app widget:

return MaterialApp(
  ...,
  supportedLocales: RStringsDelegate.supportedLocales,
  localizationsDelegates: [
    RStringsDelegate(),
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  ...,
 );

Formatting #

This package is also supports localized formatting:

en_US.json (fallback locale):

{
    "format_example": "Your object is ${object} and other is ${other}"
}

ru.json:

{
    "format_example": "Ты передал object = ${object}"
}

It looks like string interpolation in json files. After generation you will have the following function instead of getter in _Strings class:

String format_example({
  required Object object,
  required Object other,
});

It can be used in code as follows:

Text(
  R.stringsOf(context).format_example(
    object: 12345,
    other: 'OTHER',
  ),
),

Planned features #

☑ Plain images

☑ SVG

☑ String resources

☐ Colors

☐ Text styles

☐ Themes

License #

Licensed under the MIT License.

2
likes
130
pub points
46%
popularity

Publisher

unverified uploader

Builder package for generating R file which contains project asset references

Homepage

Documentation

API reference

License

Icon for licenses.MIT (LICENSE)

Dependencies

build, flutter, glob, meta, path, yaml

More

Packages that depend on r_resources