راهنمای شروع برنامه نویسی با اپسان

• راه اندازی اولیه
• ابزار ها
• نصب پلاگین اینتلیج (روش پیشنهادی)
• ساخت مینی اپ
• ایجاد پروژه ی جدید
• ساختار فایل ها
• تنظیم آدرس SDK اپسان
• اجرا و خطا یابی
• اجرای مینی اپ روی وب
• اجرای مینی اپ روی اندروید
• خطا یابی با استفاده از log
• برنامه نویسی با اپسان
• مفاهیم ساختاری
• نمونه مینی اپ ها
• ساخت یک مینی اپ TODO
• انتشار مینی اپ
• راهنمای Appsan-CLI

راه اندازی اولیه

ابزار ها

 

 

 

مقدمه

روند ایجاد و اجرای مینی اپ ها از دو بخش کد نویسی و تست تشکیل می شود. پلتفرم اینتگرو پیا ابزار های زیر را برای تسریع توسعه در اختیار توسعه گر قرار می دهد.

نرم افزار اپسان روی گوشی

نرم افزار اپسان، برای تست و اجرای مینی اپ ها نیاز بوده و باید روی گوشی نصب شود. در صورت نصب بودن اپسان امکان اتصال گوشی به کامپیوتر و تست کد های اپسان روی گوشی ایجاد می شود.

کلاینت اپسان

کلاینت اپسان وظیفه ی برقراری ارتباط بین کامپیوتر و نرم افزار اپسان روی گوشی را دارد

پیش نیاز

• نصب اپلیکیشن اپسان اندروید روی گوشی
• نصب جاوا و وجود آن در environment-variable های سیستم عامل
• دانلود Intelij Idea Ultimate و دانلود و فعال سازی appsan-intelij-plugin روی آن (روش پیشنهادی)
• دانلود appsan-cli و قرار دادن آن داخل پوشه پروژه (در صورت استفاده از VS-CODE)

لینک های دانلود

• اپلیکیشن اپسان
• Appsan SDK
• Intelij Idea

نصب پلاگین اینتلیج (روش پیشنهادی)

 

فعال سازی پلاگین

ابتدا باید پلاگین اینتلیجی اپسان را فعال کنید. برای این کار نرم افزار intelij Idea را باز کنید و به بخش settings بروید یا کلید Ctrl + Alt + S را بزنید. در این بخش قسمت plugins بروید. روی کلید چرخ دنده کلیک کرده و Install Plugin from Disk را بزنید.

در پنجره ی باز شده فایل zip پلاگین اپسان دانلود شده را انتخاب کنید. این فایل با نام appsan-intelij-*.zip داخل فابل زیپ sdk است .

 

در صورت نیاز نرم افزار را بسته و دوباره باز کنید یا کلید Restart IDE را بزنید.

.

 

 

 

ساخت مینی اپ

ایجاد پروژه ی جدید

 

 

داخل اینتلیجی از منوی بالا  File > New > Project… را انتخاب کنید

در پنجره ی باز شده نوع پروژه Appsan را انتخاب کرده، آدرس SDK دانلود شده را داخل ورودی Path to Appsan SDK وارد کنید و next را بزنید.

در این بخش نام پروژه و آدرس ذخیره سازی را وارد کرده و create  را بزنید.

یک پروژه اپسان برای شما ایجاد می شود

ساختار فایل ها

 

مینی اپ شما از مجموعه ای از فایل های .appsan تشکیل شده است که در آخر تبدیل به یک فایل واحد شده و در موبایل نمایش داده می شود.

برای تمیز تر شدن کد ها و امکان ایجاد پروژه های بزرگتر منطق برنامه از نمای آن جدا می شود که برای نما از فایل های .xml.appsan و برای منطق از فایل .js.appsan استفاده می شود. فایل های شکسته شده باید در فایل xml.appsan معرفی شوند تا در زمان اجرای برنامه این فایل ها داخل فایل اصلی جایگزین شوند. برای معرفی فایل شکسته شده داخل فایلی دیگر از include استفاده می شود و آدرس فایل جدید در اتریبیوت layout به آن داده می شود.

* آدرس فایل ها همیشه از پوشه ی layout به بعد وارد می شود.

 

برای درک بهتر ساختار فرض کنید مینی اپ شما یک نرم افزار todo می باشد. یک نرم افزار todo از یک صفحه ی لیست کار ها و یک صفحه ی کار جدید تشکیل می شود. ساختار پیشنهادی برای این اپ به صورت زیر است.

 

تنظیم آدرس SDK اپسان

 

از منو فایل settings را انتخاب کنید

داخل این پنجره به Languages & Frameworks > Appsan مراجعه کرده و آدرس پوشه SDK دانلود شده را در قسمت Path to SDK وارد نمایید

اجرا و خطا یابی

اجرای مینی اپ روی وب

 

 

 برای اجرای مینی اپ در قسمت run config در قسمت بالا سمت راست intelij گزینه یAdd configuration یا Edit configuration را بزنید. در پنجره باز شده روی + زده و Appsan را انتخاب نمایید.

سپس نام مورد نظر برای اجرا و فایل اجرا را انتخاب کنید. Run type را روی Web  قرار دهید.

پس از اجرا، آدرس وب داخل console نمایش داده می شود.

Android دریافت کرده و با پوشه ی libs/bin/platform-tools جایگزین کنید.

 

نمای وب پیش نمایش مینی اپ شما را نمایش می‌دهد و ممکن است خروجی دریافتی با خروجی پس از باندل شدن متفاوت باشد. علاوه بر این امکانات سوپر اپ مانند اطلاعات کاربر یا توکن ورود در این روش در دسترس نیست و باید دستی در کد وارد شود. 

خطا های اجرا

Project has no JDK configuration

 در بخش Project در پنجره باز شده SDK را انتخاب کنید ورژن 11 یا بالاتر از JAVAرا انتخاب کرده یا در صورت عدم وجود ورژن Add را بزنید تا به صورت خودکار دانلود شود.

اجرای مینی اپ روی اندروید

 

 

 

 

 

 

 

 

برای اجرای مینی اپ خود از نصب بودن اپسان و فعال بودن usb debuging روی گوشی اندرویدی خود مطمئن شوید.

فعال سازی حالت توسعه اپسان

برای اجرای مینی اپ روی اندروید باید حالت توسعه روی اپ قرمز فعال شود. برای این کار وارد اپ قرمز قسمت پروفایل شوید و کلید بروز رسانی پروفایل (کلید گرد فلش دار در بالا سمت چپ) را نگه دارید تا پیام سرویس توسعه اجرا شد نمایش داده شود. برای غیر فعال سازی حالت توسعه بار دیگر این کلید را نگه دارید. زمانی که حالت توسعه روشن است یک ناتیفیکیشن در ناتیفیکیشن بار گوشی مبنی بر فعال بودن حالت توسعه نمایش داده می شود..

تنظیمات اجرا در IDE

 برای اجرای مینی اپ در قسمت run config در قسمت بالا سمت راست intelij گزینه یAdd configuration یا Edit configuration را بزنید. در پنجره باز شده روی + زده و Appsan را انتخاب نمایید.

سپس نام مورد نظر برای اجرا و فایل اجرا را انتخاب کنید.

برای اجرای نرم افزار گوشی را به کامپیوتر وصل کرده و دگمه ی اجرای intelij در بالا سمت راست را انتخاب کنید.

خطا های اجرا

Project has no JDK configuration

 در بخش Project در پنجره باز شده SDK را انتخاب کنید ورژن 11 یا بالاتر از JAVAرا انتخاب کرده یا در صورت عدم وجود ورژن Add را بزنید تا به صورت خودکار دانلود شود.

 

failed to create socket, is appsan bridge running?

این خطا به معنی اجرا نبودن bridge در اپسان است برای اجرای این برنامه دستور زیر را در terminal وارد کنید.

java -jar libs/appsan-tcp-bridge.jar

اجرا ی مینی اپ روی مک و لینوکس

لایبرری های همراه با پلاگین تنها platform-tools مربوط به ویندوز را همراه خود دارد برای استفاده از پلاگین در مک یا لینوکس platform-tools مربوط به سیستم عامل خود را از سایت Android دریافت کرده و با پوشه ی libs/bin/platform-tools جایگزین کنید.

خطا یابی با استفاده از log

 

 

 

 

اپسان برخی از اتفاقات و خطا ها رابه صورت log نمایش می دهد.

یکی از این موارد ریکوست های وب است که متن ارسالی و جواب بازگشت داده شده آن داخل لاگ قابل مشاهده است.

 

دسترسی به لاگ ها

برای دسترسی به لاگ ها CLI را با دستور logs و نام دستگاه خود اجرا کنید

Java -jar libs/Appsan-CLI-1.0-SNAPSHOT.jar logs -d <device-id>

برای به دست آوردن id دستگاه اندرویدی خود میتوانید دستور زیر را اجرا کنید.

Java -jar libs/Appsan-CLI-1.0-SNAPSHOT.jar devices

پس از اجرای دستور logs می توانید لاگ ها را روی آدرس http://localhost:12982/logs/ داخل browser  دلخواه خود ببینید.

دسترسی به لاگ ها در intelij

از قسمت اجرا بخش edit configuration را باز کنید

در پنجره باز شده روی + کلیک کرده . گزینه JAR Application را انتخاب کنید

سپس نام مورد نظر را در بخش Name و آدرس Appsan-CLI را در بخش Path to JAR وارد کنید. در قسمت Program arguments مقدار زیر را وارد کنید.

logs -d <device-serial>

که <device-serial> همان سریال دستگاه که در بالا از ترمینال دریافت شد میباشد.

 

حالا با اجرای logs در اینتلیجی لاگ ها روی browser قابل رویت خواهد بود.

 

برنامه نویسی با اپسان

مفاهیم ساختاری

نمایش صفحه

هر مینی‌اپ باید با یک رابط کاربری شروع شود. این رابط، نقطه آغاز تعامل کاربر با برنامه است. برای نمایش یک صفحه کامل که بتواند محتوای متنی، تصاویر، دکمه‌ها و دیگر المان‌ها را نمایش دهد، در اپسان از Page استفاده می‌کنیم.

چرا Page؟ Page المانی است که به صورت پیش‌فرض به عنوان "نمای اصلی" یک برنامه یا بخشی از آن استفاده می‌شود. هر چیزی که کاربر در یک صفحه مشاهده می‌کند، فرزندان همین Page خواهند بود.

مثال: ساخت یک صفحه ساده در این مثال، یک صفحه به نام "صفحه اصلی" طراحی شده است که حاوی متنی برای خوش‌آمدگویی به کاربر است:

<page id="main-page" title="صفحه اصلی" layout="linear_vertical" scrollable="true">
    <text text="به اپسان خوش آمدید" textsize="20" textcolor="#424750" />
</page>

ویژگی‌های کلیدی Page:

• id: شناسه یکتا برای صفحه.
• title: عنوانی که در نوار ابزار نمایش داده می‌شود.
• layout: نوع چیدمان محتوا (افقی یا عمودی).
• scrollable: مشخص می‌کند که صفحه قابلیت اسکرول دارد یا خیر.

اولین المان در کد اپسان با اجرای مینی اپ اجرا می شود. این المان میتواند از نوع page، dialog، action یا دیگر المان های قابل اجرا باشد.

صفحه (Page) به شما اجازه می‌دهد یک نمای اصلی ایجاد کنید. در داخل یک صفحه می‌توان انواع مختلفی از المان‌ها مانند متن (Text)، دکمه‌ها (Button)، تصاویر (Image) و سایر المان‌ها را قرار داد. یک مینی اپ میتواند صفحات مختلف داشته باشد.

اپسان در زمان اجرا اولین صفحه (یا المان قابل اجرا دیگر) در کد را نمایش میدهد پس از آن منطق جابجایی بین صفحات باید توسط دولپر مشخص شود. این کار با استفاده از اکشن ها انجام میشود.

اکشن‌ها در اپسان وظیفه مدیریت و اجرای دستورات را بر عهده دارند. یکی از رایج‌ترین کاربردهای اکشن‌ها، جابجایی بین صفحات است. اکشن‌ها همچنین برای اجرای اسکریپت‌ها، بستن دیالوگ‌ها و تعامل با سایر بخش‌های اپلیکیشن استفاده می‌شوند که در بخش های بعدی به آن ها اشاره می شود.

 

اکشن ها

جابجایی بین صفحات با اکشن

جابجایی بین صفحات در اپسان با اکشن‌های page/pageId انجام می‌شود. این اکشن صفحه‌ای با شناسه (ID) مشخص را باز می‌کند. استفاده از این روش باعث می‌شود تجربه کاربری روان و سریع باشد.

برای جابجایی بین صفحات چند صفحه داخل کد تعریف میکنیم و به هر یک id میدهیم هر page با id خود شناخته می شود و برای باز کردن page از این id استفاده می شود.

برای مثال، سه صفحه ایجاد می‌کنیم که کاربر می‌تواند بین آن‌ها جابجا شود. صفحه‌ها شامل یک متن و دکمه‌هایی برای رفتن به صفحه دیگر هستند.

<!-- صفحه اول -->
<page id="page1" title="صفحه اول" layout="linear_vertical" scrollable="true">
    <text text="این صفحه اول است." textsize="20" textcolor="#424750" />
    <button text="برو به صفحه دوم" onclick="page/page2" />
    <button text="برو به صفحه سوم" onclick="page/page3" />
</page>

<!-- صفحه دوم -->
<page id="page2" title="صفحه دوم" layout="linear_vertical" scrollable="true">
    <text text="این صفحه دوم است." textsize="20" textcolor="#424750" />
    <button text="بازگشت به صفحه اول" onclick="page/page1" />
    <button text="برو به صفحه سوم" onclick="page/page3" />
</page>

<!-- صفحه سوم -->
<page id="page3" title="صفحه سوم" layout="linear_vertical" scrollable="true">
    <text text="این صفحه سوم است." textsize="20" textcolor="#424750" />
    <button text="برو به صفحه اول" onclick="page/page1" />
    <button text="برو به صفحه دوم" onclick="page/page2" />
</page>

در مثال جابجایی بین صفحات، از اکشن‌ها در ویژگی onclick دکمه‌ها استفاده شد. با کلیک روی دکمه‌ها، اکشن مربوطه اجرا شده و کاربر به صفحه دیگری منتقل می‌شود. در اپسان، اکشن‌ها ابزار اصلی برای اجرای دستورات و تعاملات در برنامه هستند.

اکشن‌ها تنها محدود به ویژگی onclick نیستند. بسیاری از ویژگی‌های دیگر نیز می‌توانند اکشن دریافت کنند. این ویژگی‌ها معمولاً با پیشوند on شروع می‌شوند. در ادامه، چند مثال از اکشن‌ها در بخش‌های مختلف ارائه شده است:

قابلیت ترکیب اکشن ها

چند اکشن می‌توانند در یک ویژگی به صورت زنجیره‌ای اجرا شوند. این اکشن ها با ; یا -> جدا می شوند. اکشن هایی که با ; جدا شوند پشت سر هم به صورت موازی اجرا می شوند و اکشن هایی که با -> جدا می شوند به ترتیب اجرا شده و پس از پایان اکشن اول اکشن بعدی با نتیجه اکشن اول صدا می شود.

<button text="ذخیره و بازگشت" onclick="script/form-script:saveForm();page/summary-page" />
<button text="امضا و ارسال" onclick="ekyc/generateToken('0300000','1X12345678')->script/sign:submit($data)" />

همه ی اکشن ها امکان استفاده با -> را ندارند. در صورت عدم پشتیبانی اکشن از -> ممکن است اکشن بعدی اجرا نشود یا به طور همزمان با اکشن قبلی اجرا شود.

 

اکشن‌های پرکاربرد

در اپسان، برخی از اکشن‌ها به طور مکرر استفاده می‌شوند. این اکشن‌ها در بخش اکشن‌های مستندات اپسان به صورت کامل توضیح داده شده‌اند:

• page/pageId: جابجایی به صفحه‌ای با شناسه مشخص.
• dialog/dialogId: باز کردن یک دیالوگ.
• app/closedialog: بستن دیالوگ باز.
• script/scriptId:functionName(): اجرای یک تابع جاوااسکریپت.
• app/exit: خروج از برنامه.

برای آشنایی با باقی اکشن ها میتوانید بخش اکشن ها را مطالعه نمایید.

 

انتقال داده بین صفحات: معرفی متغیرها (Variables)

 

تا اینجا با مفهوم Page آشنا شدیم و یاد گرفتیم که چگونه از اکشن‌ها برای جابجایی بین صفحات استفاده کنیم. اما در بسیاری از موارد، نیاز است که داده‌ها بین صفحات جابجا شوند. برای مثال، در یک فرم ثبت‌نام ممکن است کاربر اطلاعاتی را در یک صفحه وارد کند و در صفحه بعدی نتیجه آن را مشاهده کند.

Variable: ابزار مدیریت و انتقال داده

متغیرها (Variable) در اپسان برای ذخیره و انتقال داده‌ها بین صفحات یا سایر بخش‌های برنامه استفاده می‌شوند. این متغیرها می‌توانند مقادیر مختلفی مانند متن، عدد یا اشیاء را نگه‌داری کرده و در هر نقطه از برنامه قابل دسترسی باشند.

نحوه تعریف و استفاده از متغیرها

در اپسان، متغیرها با استفاده از متد Appsan.setVariable() تعریف و مقداردهی می‌شوند. برای دسترسی به مقدار متغیر نیز از متد Appsan.getVariable() استفاده می‌شود علاوه بر این میتوانید متغیر را داخل xml با تگ var با مقدار اولیه مشخص اعریف کنید.

<var id="phone" value="0211231225"/>

Appsan.setVariable('phone', '02112345678')

مثال: ذخیره و استفاده از متغیرها

• ذخیره مقدار در متغیر در صفحه اول، نام کاربر در یک متغیر ذخیره می‌شود:

<page id="page1" title="صفحه اول" layout="linear_vertical">
    <textinput id="username" hint="نام کاربری" />
    <button text="ذخیره و برو به صفحه بعد" onclick="script/main-script:saveUsername()" />
</page>

<script id="main-script">
    function saveUsername() {
        const username = Appsan.findElementById('username').value;
        Appsan.setVariable('user_name', username);
        Appsan.runAction('page/page2');
    }
</script>

• دسترسی به مقدار متغیر در صفحه دوم در صفحه دوم، مقدار ذخیره شده نمایش داده می‌شود:

<page id="page2" title="صفحه دوم" layout="linear_vertical">
    <text id="welcomeMessage" text="در حال بارگذاری..." />
    <script id="page2-script">
        function initPage() {
            const username = Appsan.getVariable('user_name').value;
            Appsan.setProperty('welcomeMessage', 'text', `سلام، ${username}!`);
        }
    </script>
    <onshown action="script/page2-script:initPage()" />
</page>

نکات کلیدی در استفاده از متغیرها

1. دسترسی در تمام برنامه: متغیرها به صورت سراسری تعریف می‌شوند و در هر صفحه یا بخش از برنامه قابل دسترسی هستند.
2. مدیریت ساده داده‌ها: با استفاده از متغیرها، نیازی به ارسال مستقیم داده‌ها از یک صفحه به صفحه دیگر نیست.
3. حذف متغیرها: می‌توانید متغیرها را با مقداردهی مجدد بازنویسی کنید یا در صورت نیاز حذف کنید.

 

 

 

 

 

 

نمونه مینی اپ ها

ساخت یک مینی اپ TODO

 

این فصل فرض میکند نحوه ی ایجاد پروژه ی پایه، اجرا و تست مینی اپ که در فصل های گذشته گفته شده را مطالعه کردید. و با کلیات برنامه نویسی اپسان که در بخش فرانت‌اند توضیح داده شده است آشنایی دارید.

انتشار مینی اپ

راهنمای Appsan-CLI

راهنمای استفاده از ابزار خط فرمان CLI برای Appsan

این ابزار CLI به شما امکان مدیریت، اجرا، و تعامل با پروژه‌های Appsan را می‌دهد. دستورات اصلی در CLI عبارت‌اند از:

---

1. Run (اجرا)

برای اجرای پروژه Appsan:

java -jar AppsanCLI.jar run [options]

گزینه‌ها:

• -pl یا --platform: پلتفرم اجرا (مقدار: usb, web).
• -f یا --file: نام فایل XML که باید اجرا شود.
• -r یا --root: مسیر پوشه پروژه.
• -k یا --keyVal: جایگزینی کلید و مقدار
• -v یا --variable: افزودن یک متغیر به انتهای فایل.
• -o یا --out: مسیر خروجی.
• --debug: فعال‌سازی حالت دیباگ.
• --adb-path: مسیر ADB برای دستگاه‌های اندروید.
• --port: پورت برای پیش‌نمایش. (حالت وب)
• --socket-port: پورت برای اتصال WebSocket. (حالت وب)
• --keep-comments: حفظ کامنت‌ها در زمان بیلد.

---

2. Bundle (باندل کردن)

برای ایجاد بسته‌های باندل:

java -jar AppsanCLI.jar bundle [options]

گزینه‌ها:

• -f یا --file: نام فایل XML.
• -r یا --root: مسیر ریشه منابع.
• -k یا --keyVal: جایگزینی کلید و مقدار.
• -v یا --variable: افزودن متغیر.
• -q یا --qualifier: افزودن خصوصیات.
• -b یا --bundle-type: نوع باندل (zip, xml).
• --keep-comments: حفظ کامنت‌ها.

---

3. Devices (مدیریت دستگاه‌ها)

برای نمایش لیست دستگاه‌های متصل:

java -jar AppsanCLI.jar devices

---

4. Logs (دریافت لاگ‌ها)

برای مشاهده و مدیریت لاگ‌های پروژه:

java -jar AppsanCLI.jar logs [options]

گزینه‌ها:

• -d یا --device: انتخاب دستگاه برای مشاهده لاگ.

---

5. Exit Bridge (خروج از رابط اندروید tcp-bridge)

برای ارسال دستور خروج به پل ارتباطی:

java -jar AppsanCLI.jar exit-bridge

---

نکات اضافی:

• نصب: برای استفاده از این CLI، اطمینان حاصل کنید که جاوا ۱۱ یا بالاتر نصب شده باشد.
• پیکربندی: فایل appsan.json باید در مسیر پروژه موجود باشد تا تنظیمات پروژه به‌درستی بارگذاری شود.
• اشکال‌زدایی: در صورت وقوع خطا، از گزینه‌های دیباگ برای دریافت اطلاعات بیشتر استفاده کنید.

مثال‌ها:

• اجرای پروژه روی پلتفرم وب:

java -jar AppsanCLI.jar run -pl web -f [project-dir]/layout/app.xml -r [project-dir]/layout

• ایجاد باندل ZIP:

java -jar AppsanCLI.jar bundle -b zip -f [project-dir]/layout/app.xml -r [project-dir]/layout

• نمایش دستگاه‌ها:

java -jar AppsanCLI.jar devices

• دریافت لاگ‌ها از دستگاه خاص:

java -jar AppsanCLI.jar logs -d device1