Oats~i を使用して Web アプリを構築する – Oats~i アプリを開始する

「Oats~i を使用して Web アプリを構築する」チュートリアル シリーズの第 2 部へようこそ。最初のパートでは、開発環境に Oats~i をインストールする方法を説明しました。見逃した場合は、ここでチェックしてください。

シリーズのこのパートでは、Oats~i アプリを開始する方法を説明します。これは、Oats~i アプリを起動し、フロントエンドでフレームワークを実行するすべてのインスタンスをカバーします。

プロジェクト全体を最初から構築するのではなく、Oats~i cli を使用してセットアップするときに Oats~i に付属する組み込みのスターター プロジェクトを使用します。このチュートリアルに必要なコードの重要な部分を開いて、それを使用して、Oats~i がクライアント/ブラウザーに到達して Web アプリの実行を開始するときにどのようにロードされるかを説明します。

詳しく見ていきましょう。

Oats~i CLI を使用してスターター プロジェクトをインストールする

Oats~i スターター プロジェクトをインストールする新しいフォルダーを作成し、ターミナルを開きます。次に、次を実行します:

npx oats-i-cli

プロンプトに従います。

これにより、Oats~i とそれにバンドルされているスターター プロジェクトが現在の作業ディレクトリにインストールされます。

最後に、スターター プロジェクトを実行するには、
を実行します。

npm run dev

ターミナルで指定されたアドレス (通常は localhost:8080) に移動し、スターター プロジェクトが動作していることを確認します。利用可能なページ間を行き来して、Oats~i がルーティングを処理し、フラグメントを通じてビューを構築していることを確認します。

次に、クライアント/ブラウザーで Oats~i を実現するコードに移りましょう。

インデックス.js

src にあるindex.js ファイルを開きます ->アプリ ->インデックス ->スクリプト。

このファイルには、cli にバンドルされているスターター プロジェクトの Oats~i を開始するコードが含まれています。これは、独自のプロジェクトで Oats~i を開始するために作成するコードとほぼ同じです。

詳しく見てみましょう。

アプリのルート

Oats~i は通常、appRoot.initApp() メソッドを通じて appRoot モジュールから初期化されます。

appRoot は、Oats~i Web アプリの初期化、メイン ナビゲーション、およびルート ビューの読み込み (テンプレートが提供されている場合) を管理する AppRoot クラスのシングルトン インスタンスです。

initApp() メソッドは、AppStateManager、MainRouter、AppRootView オブジェクトのインスタンス、デフォルト ルート、現在アプリの外部リンク インターセプト動作を定義できるオプションの追加オプションなど、いくつかの引数を取ります。

これらを詳しく見てみましょう。

AppStateManager

アプリ状態マネージャーは、Oats~i アプリのルート状態の管理を担当するモジュールです。これは主に、履歴ポップ イベントがユーザーによるブラウザの進むボタンまたは戻るボタンのクリックであるかどうかを Oats~i が理解するのに役立ちます。

この情報は、履歴 API をそのまま使用しても明らかではありません。

Oats~i は Web アプリがユーザーによって操作されるときにフラグメントの状態を保存するため、この情報を保持することは非常に重要です。したがって、以前にいたページに戻ったり進めたりする場合、それらのページのレンダリングと実行を担当するフラグメントはその状態を「記憶」し、正しい情報を表示し、自動的に正しい位置にスクロールされます。ユーザーは

にいました。

ポップ イベントが前進か後退かを知ることで、状態情報を正確に取得できるようになります。

new を呼び出して Web アプリのルーティング情報を渡すことで、AppStateManager のインスタンスを作成するだけです。

index.js ファイルでは、次の行でこれを実行します。

const appStateManager = new AppStateManager(AppRoutingInfo);

AppRoutingInfo は別のファイルですでに定義されています (これについては後で詳しく説明します)。

メインルーター

メインルーターは、Oats~i Web アプリでのルーティングを処理します。ルーター インスタンスを作成するには、「new」を呼び出し、アプリのルーティング情報、アプリ状態マネージャー インスタンス、エラー コールバック、ルート パス、およびルート同意コールバックを渡します。

アプリのルーティング情報とアプリ状態マネージャーのインスタンスについてはすでに説明しましたので、メインルーターに渡す他の引数について説明しましょう。

エラーコールバック

ルーティングに問題が発生した場合、メインルーターはエラーコールバックを起動し、ルーティングが失敗した理由を通知します。ルートを適切に定義している限り、このメソッドを提供するだけでなく、実装について心配する必要はありません。

ルートパス

メインルーターを使用すると、routeTO() メソッドを使用して JavaScript コードからルーティングを直接呼び出すことができます。また、アプリのメインのルーティング情報に基づいて、たどるべき有効なルートも決定します。

Now, if you have Oats~i running in your website with a special address such as /admin, it can be repetitive having to start every routing call or routing info with the /admin root. Instead, you can supply this to the main router as the root path, and just append the rest of your route to your routing calls or routing info.

So, instead of /admin/create, with the root path set to /admin, you can just have the route as /create. However, href attributes in links MUST be fully qualified.

Route Consent Callback

Before the main router can trigger routing for a given path, it attempts to see whether routing for that route has been permitted. The route consent callback allows you to specify this, giving you the ability to control which sections of your web app can be accessed by a given user or based on any other business or app logic.

Note: This is different from fragment consenting, which we’ll cover later.

AppRootView Object

The app root view object consists of the root view template and array of main navigation infos.

Every Oats~i app has a root view. This is the permanent section of the view which the user will always see regardless of the path they’re navigating to. The root view is wrapped within an tag and will typically contain elements such as your navbar and footer.

Here’s an example, sourced from home.sv.hbs in the Oats~i starter project

<app-root id="my-app">
        <div id="nav">
            <a href="/" class="nav-link open-sans-txt home-link"><span></span><span>Home</span></a>
            <a href="/about" class="nav-link open-sans-txt about-link"><span></span><span>About</span></a>
        </div>
        <div id="site-bg"></div>
        <main-fragment>

        </main-fragment>
</app-root>

Note: As you can infer from the Oats~i starter project, you can skip passing in a template for the app root view in the initApp() method as long as you’ve provided it in the html markup sourced for your page from the server.

Your root view object should also have a single tag specified within, where the app’s fragments will be loaded.

The AppRootView object also takes a main navigation info array, which contains a list of selectors and their active routes, which Oats~i will use to show you which navigation selector is active.

In the Oats~i starter project, specifying the main nav info makes it possible to update the styling and looks of the navigation links when you click on it and navigate to its url.

Oats~i handles the click and update boiler plate for the navigation links or buttons. All you have to do is style the links or buttons based on which one is marked as active using the attribute ‘navigation-state=”active”’

Default Route

The default route is the route Oats~i will default to incase the page loads from a url that is not specified in your app’s routing info. You can use this to curate the default web app behavior especially if it results from a log in or authentication action.

For instance, if the user has come in from a login page and is redirected to their admin page, but the initial page load is at “/admin”, you can specify the default route to be “/admin/dashboard”.

Oats~i will reroute the web app to /admin/dashboard on load and the user will always access their dashboard every time they come from logging into the app.

If you want to change this behavior to say, profile, you can simply change the default route in your web app to /admin/profile and all users logging in will have their profile page as the default page.

Extra Options

Oats~i also takes in optional extra options, with the current implementation allowing you to intercept external links within your web app. This allows you to warn users of their navigation away from your site and the url they’re about to access, in case you want to build a content protection system.

Complete Code

The complete code for starting an Oats~i app will look something like this:

//sourced from index.js in the starter app
const appStateManager = new AppStateManager(AppRoutingInfo);
    appRoot.initApp(appStateManager, new MainRouter(AppRoutingInfo, appStateManager, (args) => {}, "", async (url) => {

        return {

            canAccess: true,
            fallbackRoute: "/"
        }
    }), { template: null, mainNavInfos: AppMainNavInfo }, "");

You can wrap this code within a function that is automatically invoked when your index.js file downloads in the browser to have the web app automatically started on page load. In the starter project’s case, this is the initApp() function.

Now, there are two more things left to explain.

App Routing Info

From the startup code, you can point out that providing routing information is mandatory for an Oats~i web app to initialize. From the example’s I’ve given, we define this info elsewhere then import it in our startup script. Defining your routing info in a separate file is not mandatory, but I find it to be good practice especially when you want to add more routes or main navigation in your web app.

Here’s how routing information is defined for an Oats~i web app, using the example from the starter project.

const AppRoutingInfo = RoutingInfoUtils.buildMainRoutingInfo([

    {
        route: "/",
        target: homeMainFragmentBuilder,
        nestedChildFragments: null
    },
    {
        route: "/about",
        target: aboutMainFragmentBuilder,
        nestedChildFragments: null
    }
], AppMainNavInfo);

You can call the routing info any name you want, as long as you use the method RoutingInfoUtils.buildMainRoutingInfo() to build it.

The method will return an array of routing information, with each info holding:

• route: this is the route that info is valid for. You cannot repeat a route across your routing infos.
• target: this is the main fragment the route should start building from. Oats~i builds its fragments from the main fragment to the child fragments
• Nested child fragments: these are the child fragments that should also be built for the route, in order. This order typically represents the DOM structure, with the fragment that should be created first in DOM coming before it’s nested child or a child fragment in the same level with it.

You can notice that we also pass AppMainNavInfo to the buildMainRoutingInfo() method as well. This is the same info we passed in to the app state manager and initApp method in the starter script. Let’s look at it.

App Main Nav Info

A good web app needs good navigation. And often, setting up navigation can involve a lot of boiler plate code to not only set up the click listeners for the navigation links or buttons, but also change their styling based on which one is active.

Oats~i takes care of the boiler plate for you by requiring you only provide the navigation information needed by your web app. This takes the following format (example sourced from the starter project).

const AppMainNavInfo = MainNavigationInfoBuilder.buildMainNavigationInfo([

    {
        selector: "home-link",
        defaultRoute: "/",
        baseActiveRoute: "/",
    },
    {
        selector: "about-link",
        defaultRoute: "/about",
        baseActiveRoute: "/about",
    }
]);

You create a main navigation info in Oats~i using the method MainNavigationInfoBuilder.buildMainNavigationInfo(). It returns an array of navigation infos, with each containing:

• selector: This is a dot selector that Oats~i will use to query the navigation link or button, set up listeners (for buttons only – links/A tags are automatically intercepted), and update its “navigation-state” attribute based on whether its active or not. In your markup, this is simply a class name.
• defaultRoute: this is the default route Oats~i should route to if the navigation button is clicked. For links, since Oats~i automatically intercepts clicks on links/A tags, ensure this matches the value of your href attribute.
• baseActiveRoute: This is the base route for which the navigation button or link should be treated as active. For instance, if you have a navigation button with defaultRoute “/profile” and baseActiveRoute “/profile” and the user navigates to /profile/update-pic, Oats~i will set this button as active since this route starts with the baseActiveRoute value.

Putting Everything Together

Let’s put everything together and have the final picture of what you need to get an Oats~i app up and running. Typically, you must have defined:

• The app routing info
• The app main nav info (for main navigation links in your root view)

Then, simply get a new instance of the app state manager, and call appRoot.initApp passing this instance, the app routing info, app main nav info, and main router instance. Again, here’s the example code from the Oats~i starter project that comes bundled with the cli, now wrapped in a function that we call immediately the index.js file loads in the browser.

function initApp(){

    const appStateManager = new AppStateManager(AppRoutingInfo);
    appRoot.initApp(appStateManager, new MainRouter(AppRoutingInfo, appStateManager, (args) => {}, "", async (url) => {

        return {

            canAccess: true,
            fallbackRoute: "/"
        }
    }), { template: null, mainNavInfos: AppMainNavInfo }, "");
}

initApp();

As your web app grows and changes, the only bits of this code you’ll ever need to change are the app routing infos and main navigation infos (AppRoutingInfo and AppMainNavInfo). This will be typically because you’re adding new routes to your web app (thus updating the routing information) or adding new main navigation buttons or links (thus updating the main navigation infos).

The rest of the code will be fine untouched.

Sign Up and Follow for the Next Tutorial

A lot of this will make sense when we build our very own small project in Oats~i. That’s what we’ll be doing in the next part of this series, to learn the next fundamental concepts around building an Oats~i web app.

See you then.

Support Oats~i

You can support the development of Oats~i through Patreon or buy me a coffee.

以上がOats~i を使用して Web アプリを構築する – Oats~i アプリを開始するの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。