packages/
 metafox/
    note/
      config/
        config.php
      routes/
        api.php
      resources/
        lang/: define supported languages
          drivers.php: define drivers
          en/
            phrase.php: define message translation
            validation.php: define message phrases
          menu/
            items.php: define menu items
            menus.php: define menus
      src/
        Database/
          Factories/
          Migrations/
          Seeders/
        Http/
         Controllers/
         Requests/
         Resources/
        Listeners/
        Models/
        Obsevers/
        Policies/
        Providers/
        Repositories/
      tests/
        Tests/
          Unit/: Unit test source root
          Features/: Feature test source root
      composer.json

 
cd frontend/
 
yarn && yarn bootstrap
 
npx metafox-cli
 
✔ What do you need? · Create new app
✔ What is vendor/company name? · metafox
✔ What is app name? · note
Generating files ...
Updating workspace ...

frontend/
  packages/
    metafox/
      note/
        src/
          reducers/
          sagas/
        package.json
        tsconfig.json
        constants.ts
        types.ts: define typings
        index.tsx: general export
        module.d.ts: integrate typing

/**
 * @type: route
 * path: /note
 * name: note.home
 */
 
import React from "react";
 
function HomePage() {
  return <div>This is note home page</div>;
}
 
export default HomePage;

yarn bundle

cp -rf frontend/app/dist/* web/

/**
 * @type: route
 * name: note.home
 * path: /note
 */
 
import { createLandingPage } from "@metafox/framework";
 
export default createLandingPage({
  appName: "note",
  pageName: "note.home",
  resourceName: "note",
});

{
  "large": {
    "blocks": [
      {
        "blockId": "ia",
        "component": "core.block.sideAppHeader",
        "slotName": "side",
        "title": "Notes",
        "icon": "ico-compose-alt",
        "blockLayout": "sidebar app header",
        "freeze": true
      },
      {
        "component": "core.block.sidebarAppMenu",
        "slotName": "side",
        "title": "Note",
        "blockId": "i8",
        "menuName": "sidebarMenu",
        "blockLayout": "sidebar app menu"
      }
    ],
    "templateName": "two-column-fixed"
  },
  "info": {
    "bundle": "web",
    "name": "note.home"
  }
}

<?php
 
 /* this is auto generated file */
 return [
     [
         'name'=> 'note.sidebarMenu',
         'resolution'=> 'web',
     ],
     [
         'name' => 'note.admin',
         'resolution'=> 'admin',
     ],
 ];

<?php
 
 /* this is auto generated file */
 return [
     [
         'module_id' => 'note',
         'menu' => 'core.primaryMenu',
         'name' => '',
         'parent_name' => '',
         'label' => '',
         'ordering' => 4,
         'is_deleted' => 0,
         'version' => 0,
         'is_active' => 1,
         'to' => '/',
         'icon' => 'ico-newspaper-alt',
         'testid' => '',
         'extra' => [
             'subInfo' => 'Browse ',
         ],
     ],
     [
         'tab'      => 'all',
         'menu'     => 'note.sidebarMenu',
         'name'     => 'all',
         'label'    => 'note::phrase.all_note',
         'ordering' => 1,
         'icon'     => 'ico-hashtag',
         'to'       => '/note',
     ],
 ];

php artisan package:install company/note --fast

{
  "large": {
    "blocks": [
      {
        "blockId": "ia",
        "component": "core.block.sideAppHeader",
        "slotName": "side",
        "title": "Notes",
        "icon": "ico-compose-alt",
        "blockLayout": "sidebar app header",
        "freeze": true
      },
      {
        "component": "core.block.sidebarAppMenu",
        "slotName": "side",
        "title": "Note",
        "blockId": "i8",
        "menuName": "sidebarMenu",
        "blockLayout": "sidebar app menu"
      },
      {
        "blockId": "x8",
        "component": "note.block.SampleBlock",
        "slotName": "main"
      }
    ],
    "templateName": "two-column-fixed"
  },
  "info": {
    "bundle": "web",
    "name": "note.home"
  }
}

{
  "blockId": "x8",
  "component": "note.block.SampleBlock",
  "slotName": "main"
}

/**
 * @type: block
 * name: note.block.SampleBlock
 * title: Sample Block
 * description: This is deveveloper sample guide block
 */
import React from "react";
import { createBlock, ListViewBlockProps } from "@metafox/framework";
 
function SampleBlock() {
  return <div>Sample Block</div>;
}
 
export default createBlock<ListViewBlockProps>({
  name: "SampleBlock",
  extendBlock: SampleBlock,
  defaults: {
    title: "Sample",
  },
});

yarn reload

id                 : Primary key
module_id          :
user_id            :
user_type          : user_type and user_id is morph columns to this note creator.
owner_id           :
owner_type         : owner_id and owner_type is morph columns to this note owner.
privacy            : Who can see this note.
total_view         :
total_like         :
total_comment      :
total_reply        :
total_share        :
total_attachment   :
title              : Note title
is_approved        :
is_draft           : Is this note post as draft ?
is_sponsor         :
sponsor_in_feed    :
is_featured        : Is this note mark as featured ?
featured_at        :
image_path         :
server_id          : Disk id to storage image
tags               : Contains notes tags
created_at         :
updated_at         :

<?php
 
use MetaFox\Platform\Support\DbTableHelper;
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
 
/*
 * stub: /packages/database/migration.stub
 */
 
/*
 * @ignore
 * @codeCoverageIgnore
 * @link \$PACKAGE_NAMESPACE$\Models
 */
return new class () extends Migration {
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up(): void
    {
        if (Schema::hasTable('notes')) {
            return;
        }
 
        Schema::create('notes', function (Blueprint $table) {
            $table->bigIncrements('id');
 
            DbTableHelper::setupResourceColumns($table, true, true, true, true);
 
            DbTableHelper::totalColumns($table, ['view', 'like', 'comment', 'reply', 'share', 'attachment']);
 
            $table->string('title', 255);
 
            $table->unsignedTinyInteger('is_draft')->default(0);
 
            DbTableHelper::featuredColumn($table);
            DbTableHelper::sponsorColumn($table);
            DbTableHelper::approvedColumn($table);
            DbTableHelper::imageColumns($table);
            DbTableHelper::tagsColumns($table);
 
            $table->timestamps();
        });
    }
 
    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down(): void
    {
        Schema::dropIfExists('notes');
    }
};
 

php artisan package:install company/note --fast

<?php
 
namespace Company\Note\Providers;
 
use Illuminate\Database\Eloquent\Relations\Relation;
use Illuminate\Support\ServiceProvider;
 
class PackageServiceProvider extends ServiceProvider
{
 
    public array $singletons = [
        \Company\Note\Repositories\NoteRepositoryInterface::class     => \Company\Note\Repositories\Eloquent\NoteRepository::class,
        // .. more dependencies
    ];
}

<?php
 
namespace Company\Note\Http\Controllers\Api;
use Illuminate\Support\Facades\Route;
 
Route::prefix('/note')
    ->resource('resource', NoteController::class);

php artisan cache:reset

{
  "data": [],
  "links": {
    "first": "http://127.0.0.1:8080/api/v1/note?page=1",
    "last": "http://127.0.0.1:8080/api/v1/note?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "http://127.0.0.1:8080/api/v1/note?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "http://127.0.0.1:8080/api/v1/note",
    "per_page": 100,
    "to": null,
    "total": 0
  }
}

<?php
 
namespace Company\Note\Http\Resources\v1\Note;
 
use MetaFox\Platform\Resource\WebSetting as ResourceSetting;
 
/**
 *--------------------------------------------------------------------------
 * Note Web Resource Setting
 *--------------------------------------------------------------------------
 * stub: /packages/resources/resource_setting.stub
 * Add this class name to resources config gateway.
 */
 
/**
 * Class NoteWebSetting
 * Inject this class into property $resources.
 * @link \Company\Note\Http\Resources\v1\WebSetting::$resources;
 * @SuppressWarnings(PHPMD.ExcessiveClassLength)
 * @SuppressWarnings(PHPMD.ExcessiveMethodLength)
 */
class WebSetting extends ResourceSetting
{
    /**
     * Defines frontend redux actions
     */
    protected function initActions(): void
    {
        $this->addActions([
            'searchItem'         => [
                'apiUrl'=> '/note',
                'pageUrl'     => '/note/search',
                'placeholder' => 'Search notes',
            ],
            'homePage'           => [
                'pageUrl' => '/note',
            ],
            'viewAll'            => [
                'apiUrl'   => '/note',
                'apiRules' => [],
            ],
            'viewItem'           => [ // view item detail action.
                'apiUrl'  => '/note/:id',
            ],
            'deleteItem'         => [
                'apiUrl'  => '/note/:id',
                'confirm' => [
                    'title'   => 'Confirm',
                    'message' => 'Are you sure you want to delete this item permanently?',
                ],
            ],
            'editItem'           => [
                'pageUrl' => '/note/edit/:id',
            ],
            'addItem'            => [
                'pageUrl' => '/note/add',
                'apiUrl'  => '/note/form',
            ],
        ]);
    }
 
    /**
     * Define forms json should return in web-settings.
     */
    protected function initForms(): void
    {
        $this->addForms([
            'filter' => new SearchNoteForm(),
        ]);
    }
}

    [
        'driver'     => 'MetaFox\\Note\\Http\\Resources\\v1\\Note\\WebSetting',
        'type'       => 'resource-web',
        'name'       => 'note',
        'version'    => 'v1',
        'resolution' => 'web',
        'is_active'  => true,
        'is_preload' => false,
    ],

/**
 * @type: route
 * name: note.home
 * path: /note
 */
 
import { createLandingPage } from "@metafox/framework";
 
export default createLandingPage({
  appName: "note",
  pageName: "note.home",
  resourceName: "note",
});

<?php
 
namespace Company\Note\Http\Controllers\Api;
 
use Illuminate\Support\Facades\Route;
 
/**
 * --------------------------------------------------------------------------
 *  API Routes
 * --------------------------------------------------------------------------
 *
 *  This file will be loaded by @link \MetaFox\Platform\ModuleManager::getApiRoutes()
 *
 *  stub: app/Console/Commands/stubs/routes/api.stub
 */
 
Route::group([
    'namespace'  => __NAMESPACE__,
    'middleware' => 'auth:api', // logged in required
], function () {
    // routes to form
    Route::get('note/form', 'NoteController@getStoreForm');
    Route::get('note/form/:id', 'NoteController@getUpdateForm');
    Route::get('note/form/search', 'NoteController@getSearchForm');
 
    // routes for note resource
    Route::get('note', 'NoteController');
 
});

<?php
namespace Company\Note\Http\Controllers\Api\v1;
 
 
// import use method
 
class NoteController extends ApiController
{
    /**
     * @var NoteRepositoryInterface
     */
    private NoteRepositoryInterface $repository;
 
    // other method and properties
    ....
 
    /**
     * Get updating form
     *
     * @param  int  $id
     *
     * @return UpdateNoteForm
     */
    public function getUpdateForm(int $id): UpdateNoteForm
    {
        $resource = $this->repository->find($id);
 
        return new UpdateNoteForm($resource);
    }
 
    /**
     * Get updating form
     *
     * @param  int  $id
     *
     * @return SearchNoteForm
     */
    public function getSearchForm(int $id): SearchNoteForm
    {
        $resource = $this->repository->find($id);
 
        return new SearchNoteForm($resource);
    }
 
 
    /**
     * Get updating form
     *
     * @param  int  $id
     *
     * @return StoreNoteForm
     */
    public function getDestroyForm(int $id): StoreNoteForm
    {
        $resource = $this->repository->find($id);
 
        return new StoreNoteForm($resource);
    }
}

<?php
 
namespace Company\Note\Http\Resources\v1\Note;
 
use MetaFox\Platform\MetaFoxForm;
use MetaFox\Platform\Support\Form\AbstractForm;
use MetaFox\Platform\Support\Form\Field\CancelButton;
use MetaFox\Platform\Support\Form\Field\Submit;
use MetaFox\Platform\Support\Form\Field\Text;
use Company\Note\Models\Note as Model;
 
class StoreNoteForm extends AbstractForm
{
  /**
   * Prepare title, method, action, value of form object
   */
    protected function prepare(): void
    {
        $this->config([
            'title'  => __p('core.phrase.edit'),
            'action' => '/note',    // target api url
            'method' => 'POST', // use "POST" method
            'value'  => [
                // default value.
            ],
        ]);
    }
 
  /**
   * Define form structure.
   */
    protected function initialize(): void
    {
        $basic = $this->addBasic();
 
        // add form fields.
        $basic->addFields(
            new Text([
                'name'          => 'title',
                'required'      => true,
                'returnKeyType' => 'next',
                'label'         => 'Title',
                'validation'    => [ // add client validation rules
                  'required' => true,
                  'nullable' => false,
                  'errors'=>[
                    'required'=> __p('validation.this_is_required_field'),
                  ]
                ]
            ])
        );
 
 
        // add cancel buttons
        $footer = $this->addFooter();
        $footer->addFields(
            new CancelButton([]),
            new Submit([
                'label' => ($this->resource && $this->resource->id) ?
                    __p('core.phrase.save_changes') :
                    __p('core.phrase.create'),
            ]),
        );
    }
}

{
  "status": "success",
  "data": {
    "component": "form",     // define ReactJs render component
    "title": "Add New Note", // form title
    "action": "/note",       // target api for http request when form submit.
    "method": "POST",        // http method for http request when form submit.
    "value": {               // initial values.
      "module_id": "note",
      "privacy": 0,
      "draft": 0,
      "tags": [],
      "owner_id": 0,
      "attachments": []
    },
    "validation": {         // define validation object, based on https://www.npmjs.com/package/yup
      "type": "object",
      "properties": {
        "title": {
          "label": "Title",
          "type": "string",
          "required": true,
          "minLength": 3,
          "maxLength": 255,
          "errors": {
            "maxLength": "Title must be at most 255 characters"
          },
        }
      }
    },
    "elements": {         // define form structure
      "basic": {          // basic form section
        "name": "basic",
        "component": "container",
        "testid": "field basic",
        "elements": {
          "title": {                 // form field
            "component": "text",     // Define react render component to form.element.[component]
            "returnKeyType": "next",
            "maxLength": 255,
            "fullWidth": true,
            "margin": "normal",
            "size": "medium",
            "variant": "outlined",
            "name": "title",
            "required": true,
            "label": "Title",
            "placeholder": "Fill in a title for your note",
            "description": "Maximum 255 of characters",
            "testid": "field title"
          },
          "text": {
            "fullWidth": true,
            "variant": "outlined",
            "returnKeyType": "default",
            "name": "text",
            "required": true,
            "label": "Post",
            "placeholder": "Add some content to your note",
            "component": "RichTextEditor",
            "testid": "field text"
          },
      },
    }
  }
}

/**
 * @type: formElement
 * name: form.element.textarea
 */
import MuiTextField from "@mui/material/TextField";
import { useField } from "formik";
import { camelCase } from "lodash";
import { createElement } from "react";
import { FormFieldProps } from "../types";
 
const TextAreaField = ({
  config,
  disabled: forceDisabled,
  name,
  formik,
}: FormFieldProps) => {
  const [field, meta] = useField(name ?? "TextField");
  const {
    label,
    disabled,
    labelProps,
    placeholder,
    variant,
    margin = "normal",
    fullWidth,
    type = "text",
    rows = 5,
    description,
    autoFocus,
    required,
    maxLength,
  } = config;
 
  // fix: A component is changing an uncontrolled input
  if (!field.value) {
    field.value = config.defaultValue ?? "";
  }
 
  const haveError = Boolean(meta.error && (meta.touched || formik.submitCount));
 
  return createElement(MuiTextField, {
    ...field,
    required,
    multiline: true,
    disabled: disabled || forceDisabled || formik.isSubmitting,
    variant,
    label,
    "data-testid": camelCase(`field ${name}`),
    autoFocus,
    inputProps: { "data-testid": camelCase(`input ${name}`), maxLength },
    rows,
    InputLabelProps: labelProps,
    placeholder,
    margin,
    error: haveError ? meta.error : false,
    fullWidth,
    type,
    helperText: haveError ? meta.error : description,
  });
};
 
export default TextAreaField;

<?php
 
namespace Company\Note\Http\Requests\v1\Note;
 
use Illuminate\Foundation\Http\FormRequest;
 
class StoreRequest extends FormRequest
{
    /**
     * Get the validation rules that apply to the request.
     *
     * @return array<string, mixed>
     */
    public function rules()
    {
        // Getting validation rules.
        return [
            'title'=> ['string', 'required']
        ];
    }
}

note/
  resources/
    lang/
      en/                 : Language code `vi`
        phrase.php        : Phrase groups: `phrase`
        validation.php    : Phrase groups: `validation`
        ...
      fr/                 : Others language code.

<?php
return [
  'notes' => 'Notes',         //: phrase_name =  "note", phrase_value = "Notes"
  'label_menu_s' => 'Notes',
  'note_label_saved' => 'Note',
  'specify_how_many_points_the_user_will_receive_when_adding_a_new_note' => 'Specify how many points the user will receive when adding a new note.',
  'specify_how_many_points_the_user_will_receive_when_deleting_a_new_note' => 'Specify how many points the user will receive when deleting a note.',
  'new_note_post' => 'New Note Post',
  'edit_note' => 'Editing Note',
  'add_some_content_to_your_note' => 'Add some content to your note',
  'fill_in_a_title_for_your_note' => 'Fill in a title for your note',
  'control_who_can_see_this_note' => 'Control who can see this note.',
  'note_type' => 'Note Type',
  'added_a_note' => 'added a note',
  'note_notification_type' => 'Note Notification',
  'note_featured_successfully' => 'Note featured successfully.',
];

<?php
 
/**
 * namespace: "note" is the alias of package `company\note`.
 * group: "phrase"
 * note: "note_length_title"
 */
echo __('note::phrase.note_length_title'); // output "Note Title"

resources/
  lang/
    en/
      auth.php
      pagination.php
      passwords.php
      phrase.php
      validation.php

<?php
echo __p('auth.failed'); // ouput: These credentials do not match our records.

{
  "toggle_layout_preview": "Toggle Device Preview",
  "total_like": "{ value, plural, =0{No likes} =1{# like} other{# likes} }",
  "total_photo": "{ value, plural, =0{No photos} =1{# photo} other{# photos} }",
  "total_video": "{ value, plural, =0{No videos} =1{# video} other{# videos} }",
  "total_post": "{ value, plural, =0{No posts} =1{# post} other{# posts} }",
  "total_view": "{ value, plural, =0{No views} =1{# view} other{# views} }",
  "total_vote": "{ value, plural, =0{No votes} =1{# vote} other{# votes} }",
  "total_play": "{ value, plural, =0{No plays} =1{# play} other{# plays} }",
  "total_comment": "{ value, plural, =1{# comment} other{# comments} }",
  "total_share": "{ value, plural, =1{# share} other{# shares} }",
  "total_track": "{ value, plural, =1{# track} other{# tracks} }",
  "event_start_date": "start {date}",
  "text_direction": "Text Direction",
  "edit_block_name": "Edit Block {name}",
  "ok": "OK",
  "copy": "Copy",
  "close": "Close",
  "cancel": "Cancel",
  "add_layout_block": "Add New Block"
}

import { useGlobal } from "@metafox/framework";
import React from "react";
 
function MyComponent() {
  // use i18n helper
  const { i18n } = useGlobal();
 
  return <div>{i18n.formatMessage({ id: "toggle_layout_preview" })}</div>;
  // output: <div>Toggle Device Preview</div>
}

function * saga(){
  const { i18n } = yield* getGlobalContext();
 
  console.log({i18n.formatMessage({id: 'toggle_layout_preview'})});
  // output: Toggle Device Preview
}

{
  "status": "success",
  "data": {
    "accepted": "The :attribute must be accepted.",
    "active_url": "The :attribute is not a valid URL.",
    "after": "The :attribute must be a date after :date.",
    "after_or_equal": "The :attribute must be a date after or equal to :date.",
    "alpha": "The :attribute may only contain letters.",
    "alpha_dash": "The :attribute may only contain letters, numbers, dashes and underscores.",
    "alpha_num": "The :attribute may only contain letters and numbers.",
    "array": "The :attribute must be an array.",
    "before": "The :attribute must be a date before :date.",
    "before_or_equal": "The :attribute must be a date before or equal to :date."
  },
  "message": null,
  "error": null
}

/**
 * @type: route
 * name: note.browse
 * path: /note/:tab(friend|all|pending|feature|spam|draft)
 */
import { createBrowseItemPage } from "@metafox/framework";
 
export default createBrowseItemPage({
  appName: "note",
  resourceName: "note",
  pageName: "note.browse",
  categoryName: "note_category",
});

<?php
 
namespace Company\Note\Models;
 
// declares php "uses" directive.
 
class Note extends Model implements HasGlobalSearch // , and other interfaces
{
 
    // others property and method
    public function toSearchable(): ?array
    {
        // A draft blog is not allowed to be searched
        return [
            'title' => $this->title,
            'text'  => 'content of your text',
            'category' => '',
            // others data.
        ];
    }
}

<?php
 
namespace Company\Note\Models;
use MetaFox\Platform\Support\FeedAction;
 
// declares php "uses" directive.
 
class Note extends Model implements ActivityFeedSource // , and other interfaces
{
    /**
     * Define content of feed action put to activity streams
     *
     * @return FeedAction
     */
    public function toActivityFeed(): ?FeedAction
    {
        if ($this->isDraft()) {
            return null;
        }
 
        return new FeedAction([
            'user_id'    => $this->userId(),
            'user_type'  => $this->userType(),
            'owner_id'   => $this->ownerId(),
            'owner_type' => $this->ownerType(),
            'item_id'    => $this->entityId(),
            'item_type'  => $this->entityType(),
            'type_id'    => $this->entityType(),
            'privacy'    => $this->privacy,
        ]);
    }
 
    /**
     * Define morph map to privacy streams.
     */
    public function privacyStreams(): HasMany
    {
        return $this->hasMany(PrivacyStream::class, 'item_id', 'id');
    }
}