FAQ

Architecture & Design

Why does XWidget use XML instead of JSON?

XML was specifically designed for markup languages and document structure - it's the foundation of HTML, Android layouts, iOS XIBs, and XAML. JSON was not designed for UI hierarchies. While excellent for data interchange, it quickly becomes unnecessarily verbose and difficult to read when representing nested UI structures.

Compare this simple XML snippet:

<Container padding="16">
  <Text>Hello</Text>
</Container>

vs the JSON equivalent:

{
  "type": "Container",
  "padding": "16",
  "children": [
    {
      "type": "Text",
      "data": "Hello"
    }
  ]
}

XML gives you 50-70% more concise code, natural visual hierarchy, support for comments, and 30+ years of mature tooling. It's simply the right tool for UI markup.

How does XWidget handle Flutter API updates?

XWidget auto-generates inflaters from Flutter's widget definitions, ensuring 100% API compatibility automatically. When Flutter adds new widgets or properties, simply run xwidget generate inflaters and you immediately have support for all new features. There's no waiting for framework updates or manual maintenance - if Flutter supports it, XWidget supports it.

Can XWidget support custom widgets?

Absolutely! You can generate inflaters for your own custom widgets:

xwidget generate inflater lib/widgets/my_custom_widget.dart

Then use them in XML just like Flutter's built-in widgets:

<MyCustomWidget title="Hello" color="blue">
  <Text>Content</Text>
</MyCustomWidget>

This works for any Flutter widget, including third-party package widgets.

Development Workflow

How do I use XWidget fragments in my app?

Simply load a fragment by name:

XWidget.fromFragment('home')

Fragments are XML files stored in your assets folder. XWidget parses them and creates the corresponding Flutter widgets at runtime.

How do I test XWidget fragments?

You test them exactly like native Flutter widgets:

testWidgets('home screen test', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: XWidget.fromFragment('home'),
    ),
  );

  expect(find.text('Welcome'), findsOneWidget);
});

What you test is what users see - there's no conversion step or separate runtime format. The XML you write is the XML that runs.

Does XWidget work with hot reload?

Yes! When you edit XML fragments in your assets folder, Flutter's hot reload detects the change and updates your UI immediately. This gives you the same fast iteration cycle you're used to in Flutter development.

Can I mix XWidget fragments with regular Flutter widgets?

Absolutely! XWidget fragments are just Flutter widgets, so you can use them anywhere:

Column(
  children: [
    Text('Native Flutter widget'),
    XWidget.fromFragment('my_fragment'), // XWidget fragment
    ElevatedButton(...), // Native Flutter widget
  ],
)

This makes it easy to adopt XWidget incrementally - use it for screens that benefit from XML-based layouts, keep other screens native.

Where do I put my XML fragments?

Store them in your assets folder:

resources/
  fragments/
    home.xml
    profile.xml
    settings.xml

Then declare them in pubspec.yaml:

flutter:
  assets:
    - resources/fragments/

Performance & Compatibility

Does XWidget support all Flutter widgets?

Yes! XWidget auto-generates inflaters from Flutter's widget definitions, so every Flutter widget is supported. This includes: - All Material and Cupertino widgets - Layout widgets (Container, Column, Row, Stack, etc.) - Scrolling widgets (ListView, GridView, CustomScrollView, etc.) - Specialized widgets (via packages with generated inflaters)

When Flutter adds new widgets, regenerate inflaters and you have immediate support.

What about third-party package widgets?

Generate inflaters for any package:

flutter pub add awesome_package
xwidget generate inflaters --package awesome_package

Now you can use that package's widgets in XML fragments.

Is there a performance penalty for using XWidget?

The XML parsing happens once when the fragment loads, then you have native Flutter widgets - the same widgets you'd create in Dart code. There's a small one-time parsing cost (microseconds), but runtime performance is identical to hand-written Flutter code because the resulting widget tree is identical.

Can I use XWidget with Flutter Web, Desktop, and Mobile?

Yes! XWidget works on all Flutter platforms. Since it generates native Flutter widgets, your fragments work everywhere Flutter works - iOS, Android, Web, Windows, macOS, and Linux.

Migration & Adoption

Can I migrate an existing Flutter app to XWidget incrementally?

Yes! Start by converting one screen to an XWidget fragment, test it, then gradually convert more screens. You can have a hybrid app where some screens are native Flutter and others are XWidget fragments. There's no all-or-nothing decision.

How do I convert existing Flutter widgets to XWidget XML?

The conversion is straightforward since XML mirrors Flutter's widget structure:

Flutter:

Scaffold(
  appBar: AppBar(
    title: Text('Home'),
  ),
  body: Column(
    children: [
      Text('Welcome!'),
      ElevatedButton(
        onPressed: () => navigate('/profile'),
        child: Text('View Profile'),
      ),
    ],
  ),
)

XWidget:

<Scaffold>
  <AppBar title="Home"/>
  <Column>
    <Text>Welcome!</Text>
    <ElevatedButton onPressed="navigate('/profile')">
      <Text>View Profile</Text>
    </ElevatedButton>
  </Column>
</Scaffold>

The structure is nearly identical - just translate the syntax.

Advanced Features

Can fragments reference other fragments?

Yes! Use the <Fragment> tag to include other fragments:

<Scaffold>
  <AppBar title="Home"/>
  <Column>
    <Fragment src="header"/>
    <Fragment src="content"/>
    <Fragment src="footer"/>
  </Column>
</Scaffold>

This enables composition and reusability of UI components.

How do I handle dynamic data in fragments?

Use dependencies to inject data:

XWidget.fromFragment(
  'product_details',
  dependencies: {
    'product': product,
    'user': user,
  },
)

Then reference them in XML using EL (Expression Language):

<Text>${product.name}</Text>
<Text>${product.price}</Text>

Can I conditionally show/hide widgets based on data?

Yes, using the visible attribute with EL expressions:

<Text visible="${user.isPremium}">Premium Features</Text>
<Button visible="${!user.isPremium}" onPressed="upgrade">
  <Text>Upgrade to Premium</Text>
</Button>

Does XWidget support lists and iterations?

Yes, use the <forEach> tag:

<Column>
  <forEach var="item" in="${items}">
    <Card>
      <Text>${item.name}</Text>
    </Card>
  </forEach>
</Column>

How do I handle events and callbacks?

Use EL expressions for event handlers:

<ElevatedButton onPressed="navigateTo('/details')">
  <Text>View Details</Text>
</ElevatedButton>

The expressions are evaluated against your registered controllers and dependencies.

Can I use complex expressions in XML?

Yes! XWidget supports a full expression language:

<Text>${user.firstName + ' ' + user.lastName}</Text>
<Text visible="${items.length > 0}">Found ${items.length} items</Text>
<Container color="${isActive ? '#00FF00' : '#FF0000'}">
  <Text>${price * quantity}</Text>
</Container>

How do I debug XML parsing errors?

XWidget provides detailed error messages that show: - The line and column where the error occurred - What was expected vs what was found - The context around the error

Enable debug mode for even more detailed parsing information:

XWidget.configure(
  debugMode: true,
);

Can I validate my XML fragments before runtime?

Yes! XWidget can generate XSD schemas for validation:

xwidget generate schema

Then use any XML validator or IDE with XML support to validate your fragments against the schema, catching errors before you run your app.