Ezplatform Admin Ui Modules Laravel Package

Getting Started

First Steps

1. Installation Add the package via npm/yarn in your eZ Platform Admin UI project:

   yarn add @ezsystems/ezplatform-admin-ui-modules
   

   Ensure your project uses React 16.8+ (for hooks) and eZ Platform Admin UI (v3.x+).

2. Locate Core Components Browse the source code (if available) or check the dist folder for pre-built components. Key entry points:

   • Button (e.g., @ezsystems/ezplatform-admin-ui-modules/Button)
   • Modal (e.g., @ezsystems/ezplatform-admin-ui-modules/Modal)
   • DataGrid (for tabular data)
   • Form utilities (e.g., field components, validation helpers).

3. First Use Case: Adding a Button Import and use the Button component in your admin panel:

   import { Button } from '@ezsystems/ezplatform-admin-ui-modules/Button';
   
   function MyComponent() {
     return <Button label="Save" onClick={() => console.log('Saved')} />;
   }
   

Implementation Patterns

Common Workflows

1. Styling & Theming

   • Components follow eZ Platform’s design system (e.g., colors, spacing). Override via CSS modules or styled-components:

     import styled from 'styled-components';
     const StyledButton = styled(Button)`
       background: #ff0000;
     `;
     

   • Use theme prop (if supported) for dynamic theming:

     <Button theme="danger" label="Delete" />
     

2. Forms & Validation

   • Leverage Field and Form components for consistent input handling:

     import { Field, Form } from '@ezsystems/ezplatform-admin-ui-modules/Form';
     <Form onSubmit={handleSubmit}>
       <Field name="title" label="Title" type="text" />
     </Form>
     

   • Integrate with eZ Platform’s API (e.g., ContentService) for backend validation.

3. DataGrid Integration

   • Use DataGrid for CRUD operations with server-side data:

     import { DataGrid } from '@ezsystems/ezplatform-admin-ui-modules/DataGrid';
     <DataGrid
       columns={columns}
       data={fetchContentItems()}
       onRowClick={handleRowClick}
     />
     

   • Pair with useFetch or useQuery hooks for data loading.

4. Modal Dialogs

   • Standardize modals for actions (e.g., confirmations):

     import { Modal } from '@ezsystems/ezplatform-admin-ui-modules/Modal';
     <Modal
       title="Confirm"
       onClose={handleClose}
       actions={[
         <Button key="cancel" label="Cancel" onClick={handleClose} />,
         <Button key="confirm" label="Confirm" onClick={handleConfirm} />,
       ]}
     >
       Are you sure?
     </Modal>
     

5. Integration with eZ Platform Services

   • Use useService hook (if available) to inject eZ services:

     const { contentService } = useService('contentService');
     

Advanced Patterns

1. Custom Components

   • Extend base components (e.g., wrap Button for analytics):

     const TrackedButton = ({ label, onClick, ...props }) => (
       <Button
         label={label}
         onClick={() => {
           trackEvent('button_click', { label });
           onClick();
         }}
         {...props}
       />
     );
     

2. Internationalization (i18n)

   • Use useTranslation (if supported) for labels:

     const { translate } = useTranslation();
     <Button label={translate('admin.save')} />
     

3. Server-Side Rendering (SSR)

   • Ensure components are SSR-compatible (e.g., avoid window checks). Test with next-server or laravel-mix SSR.

4. Testing

   • Mock eZ services and use @testing-library/react:

     test('renders button', () => {
       const { getByText } = render(<Button label="Test" />);
       expect(getByText('Test')).toBeInTheDocument();
     });
     

Gotchas and Tips

Pitfalls

1. Dependency Conflicts

   • Issue: Conflicts with other React versions or eZ Platform packages.
   • Fix: Use resolutions in package.json or yarn.lock to enforce versions:

     "resolutions": {
       "react": "16.14.0",
       "@ezsystems/ezplatform-admin-ui-modules": "1.0.0"
     }
     

2. Missing TypeScript Support

   • Issue: No .d.ts files may cause IDE errors.
   • Fix: Declare types manually or use @types/react for base components.

3. Undocumented Props

   • Issue: Some components may have hidden props (e.g., data-testid).
   • Fix: Inspect the source or use console.log to explore props:

     <Button label="Debug" onClick={() => console.log(Button.propTypes)} />
     

4. eZ Platform API Changes

   • Issue: Breaking changes in eZ Platform’s backend may break UI components.
   • Fix: Subscribe to eZ Platform release notes and update dependencies.

5. Performance with Large DataGrids

   • Issue: Slow rendering with 1000+ rows.
   • Fix: Use windowing or virtualization (e.g., react-window).

Debugging Tips

1. Console Logging

   • Log props/state to understand component behavior:

     <Button
       label="Debug"
       onClick={() => console.log('Button clicked!', { props })}
     />
     

2. React DevTools

   • Inspect component hierarchies and props in the browser’s React DevTools.

3. Network Requests

   • Check the Network tab for failed API calls (e.g., ContentService requests).

4. Error Boundaries

   • Wrap components in error boundaries to catch rendering errors:

     class ErrorBoundary extends React.Component {
       state = { hasError: false };
       static getDerivedStateFromError() { return { hasError: true }; }
       render() { return this.state.hasError ? <div>Fallback UI</div> : this.props.children; }
     }
     

Extension Points

1. Custom Themes

   • Override CSS variables (e.g., --ez-button-primary-color) in your global styles.

2. New Components

   • Fork the repo and contribute missing components (e.g., Select, DatePicker).

3. Hooks Utilities

   • Create custom hooks for common patterns (e.g., useContentService):

     const useContentService = () => {
       const { services } = useContext(eZPlatformContext);
       return services.contentService;
     };
     

4. Storybook Integration

   • Document components with Storybook:

     yarn add -D @storybook/react
     

Configuration Quirks

1. eZ Platform Context

   • Ensure your app provides the eZPlatformContext (check ez-platform-admin-ui docs).

2. Lazy Loading

   • Dynamically import components to reduce bundle size:

     const LazyButton = React.lazy(() => import('@ezsystems/ezplatform-admin-ui-modules/Button'));
     

3. Environment Variables

   • Use process.env for API endpoints (e.g., API_URL) in components.

4. Build Optimization

   • Configure webpack to exclude unused components:

     // webpack.config.js
     optimization: {
       splitChunks: { chunks: 'all' },
     },