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

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

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

ابزار ها

 

 

 

مقدمه

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

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

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

کلاینت اپسان

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

پیش نیاز

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

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

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

 

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


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

image-1669852609780.png

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

image-1669852635086.png

 

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

image-1669852729611.png

.

 

 

 

ساخت مینی اپ

ساخت مینی اپ

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

 

 

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

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

Screenshot 2023-07-12 194039.png

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

image-1669852786111.png

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

ساخت مینی اپ

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

 

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

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

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

 

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

image-1669852801443.png

 

ساخت مینی اپ

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

 

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

Screenshot 2023-07-18 104550.png

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

Screenshot 2023-07-18 104238.png

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

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

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

 

 

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

image-1669853247984.png

image-1669852816575.png

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

image-1669852828405.png

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

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

Screenshot 2023-07-13 003751.png

 

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

خطا های اجرا

Project has no JDK configuration

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

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

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

 

 

 

 

 

 

 

 

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

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

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

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

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

image-1669853247984.png

image-1669852816575.png

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

image-1669852828405.png

برای اجرای نرم افزار گوشی را به کامپیوتر وصل کرده و دگمه ی اجرای 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

4-devices.png

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

5-browser-demo.png

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

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

1-edit-config.png

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

2-add-jar-config.png

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

logs -d <device-serial>

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

2-config-window.png

 

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

 

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

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

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

نمایش صفحه

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

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

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

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

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

اولین المان در کد اپسان با اجرای مینی اپ اجرا می شود. این المان میتواند از نوع 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)" />

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

 

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

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

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

 

انتقال داده بین صفحات: معرفی متغیرها (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]
گزینه‌ها:

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

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

java -jar AppsanCLI.jar bundle [options]
گزینه‌ها:

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

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

java -jar AppsanCLI.jar devices

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

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

java -jar AppsanCLI.jar logs [options]
گزینه‌ها:

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

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

java -jar AppsanCLI.jar exit-bridge

نکات اضافی:

مثال‌ها:

java -jar AppsanCLI.jar run -pl web -f [project-dir]/layout/app.xml -r [project-dir]/layout
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