اکشن ها

• انواع اکشن ها
• آپدیت کردن صفحات بدون ایجاد صفحه جدید

انواع اکشن ها

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

شما میتوانید داخل بعضی از خواص المان ها از اکشن ها استفاده کنید که این المان ها در فصل قبل بررسی شدند. همین طور میتوان چند اکشن را پشت سر هم صدا کرد که برای این کار آن ها را با استفاده از " ; " از یکدیگر جدا می کنیم.

زبان اپسان در حال حاظر از پانزده اکشن مختلف پشتیبانی می کند که بعضی از این اکشن ها مقدار ورودی دارند که با استفاده از" / " و سپس نوشتن ورودی مشخص می شوند.

command :

این اکشن دستوری را به سمت سرور ارسال می کند تا صفحه یا دیالوگ جدیدی را بارگیری (load) کند. مقدار ورودی ای که در سمت سرور نیز به شما می رسد پس از " / " در پایان command می آید. به عنوان مثال:

<page>
    <button text="goto page 2" onClick="command/page2">
</page>

در این مثال دستور page2 برای سرور ارسال شده و سرور موظف است صفحه ی بعد را ارسال کند. مقدار ورودی هر چیزی میتواند باشد و دقیقا همان مقدار سمت سرور رفته و شما نیز می توانید صفحه ی بعد را با استفاده از آن مشخص و ارسال کنید.

• App :

این اکشن برای کنترل های درون برنامه استفاده می شود به طور مثال برای بستن برنامه.

ورودی های ممکن شامل موارد زیر است:

↵  end :

این کد ، اپسان شما را می بندد.

<page>
    <button text="exit the app" onClick="app/end">
</page>

↵  Back :

بدون در نظر گرفتن کدهای داخل المان ها به صفحه ی قبل بر میگردد و در صورت نبود صفحه ی قبل برنامه را می بندد.

<page>
    <button text="return to previous page" onClick="app/back">
</page>

↵  BackKey :

عملیات باز گشت را شروع میکند و کاملا مشابه فشرده شدن کلید بازگشت توسط کاربر است. در صورتی که در page خاصیت onback را مشخص کرده باشید این خاصیت صدا می شود.

↵  closedialog :

عملیات بستن دایالوگی را که باز است را انجام میدهد.

↵  closesnack :

عملیات بستن اسنک بار را که باز است را انجام میدهد.

↵  result :

  فراخواننده ی آن به عنوان نتیجه ارسال میشود action یا دیالوگ کنونی مشخص میکند که پس از بسته شدن آن در page نتیجه ای را برای

مقدار داده شده در تابع app/result  باز شود پس از استفاده از اکشن dialog/d1->script/s1:showResult($data) مثلا اگر یک دیالوگ با اکشن

   قابل دریافت است showResult

• Dialog :

یک دیالوگ آفلاین (offline) که شما داخل کد خود نوشته اید را اجرا میکند. ورودی این اکشن id دایالوگ مورد نظر شماست.

<page>
    <button text="opening a dialog" onClick="dialog/dialog4">
</page>
  
<dialog borderCornerRadius="3" id= "dialog4"> 
  <frame layout="linear_vertical" width="75" height="75" gravity="center"> 
    <image src="http://162.55.105.137:8080/api/public/dl/IPI8gq4o" width="match_parent" selfgravity="center"></image>
  </frame> 
  <frame layout="linear_vertical">
    <text renderas="html" textcolor="#E64724" text="<b>به اپسان خوش آمدید<\b>" textsize="18" textalignment="center"></text>
  </frame>
  <button text="تایید" borderCornerRadius="3" background="#E64724" onClick="app/closedialog"></button>
</dialog>

• Page :

یک صفحه  آفلاین که شما داخل کد خود نوشته اید را اجرا میکند.

ورودی این اکشن id صفحه مورد نظر شماست.

<page title="اپسان" background="#FFFFFF" toolbarColor="#E64724" width="match_parent" height="match_parent">
  <frame  width="match_parent" layout="linear_vertical" height="match_parent" background="#FFF" >
      <button textcolor="#FFDDCE"  background="#E64724" borderCornerRadius="10"  width="250" onClick="page/nextPage">صفحه بعد</button>
  </frame>
</page>

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" id="nextPage" > <frame margin="center" width="wrap_content" height="770"> <text textcolor="E64724" textsize="20" margin_bottom="250" >"اپلیکیشن اپسان"</text> </frame> </page>

• Call :

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

<page>
    <button text="press to call" onClick="call/09xxxxxxxxx">
</page>

• ---

  Share :

عملیات اشتراک گذاری را انجام میدهد.

<page>
    <button text="press to share" onClick="share/متن قابل اشتراک">
</page>

• ---

  View :

برای نمایش فایل ها داخل سیستم عامل با دیگر ام ای ها استفاده میشود.

<page>
    <button text="press to view" onClick="view/fileAddress">
</page>

آدرس فایل باید به صورت content://filepath باشد. در صورتی که فایل توسط مینی اپ شما دانلود شده باشد آدرس فایل پس از دانلود شدن آن باز میگردد. برای اطلاعات بیشتر به بخش دانلود مراجعه کنید.

• ---

  viewbase64 :

  این اکشن از ورژن appsan:0.1.73 در دسترس است.

  به توسعه‌دهندگان اجازه می‌دهد تا داده‌های کدگذاری شده با Base64 را به عنوان فایل باز کنند. این عملکرد از قالب `viewbase64` استفاده می‌کند که داده‌ها را به صورت Base64 به همراه نوع MIME مشخص می‌کند. در ادامه توضیحات این عملکرد آورده شده است:

  نحوه استفاده از viewbase64

  هنگامی که از عملکرد viewbase64 استفاده می‌کنید، باید یک رشته داده معتبر را به عنوان ورودی به این عملکرد بدهید. این رشته باید شامل نوع MIME و داده‌های Base64 باشد.

  مثال‌هایی از استفاده:

  • داده‌های یک فایل PDF به صورت Base64:

    <page>
      <button text="show pdf" onClick="viewbase64/application/pdf,JVBERi0xLjUKJdDUxdgK...">
    </page>
    

  نکات:

  • در صورت بروز خطا در حین پردازش داده‌ها، این خطاها ثبت خواهند شد اما عملکرد متوقف نمی‌شود.
  • اگر نوع MIME مشخص نشده باشد، فایل به صورت text/plain ذخیره و باز می‌شود.

  Snackbar :

یک اسنک بار با آیدی مشخص را نشان میدهد.

<page>
    <button text="show snackbar" onClick="snackbar/welcomeSnackbar">
</page>

• ---

  Navigate :

موقعیت جغرافیایی با فرمت lat,long را ورودی میگیرد که lat و long به ترتیب طول و عرض جغرافیایی به صورت عدد اعشاری هستند.

این اکشن مقدار ورودی را روی نرم افزار نقشه نصب شده روی گوشی کاربر نمایش میدهد.

<page>
    <button text="show on map" onClick="navigate/35.8029459">
</page>

• vStream :

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

<page>
    <button text="opening media" onClick="vstream/http://yourURL">
</page>

• Update :

همانند اکشن command دستور ورودی را برای سرور می فرستد که سرور با استفاده از آن مقادیری که در حال حاضر روی صفحه به کاربر نمایش داده میشوند را تغییر میدهد. این امکان در فصل بعد مورد بررسی قرار می گیرد.

<frame gravity="left">
                <frame textcolor="#fff" background="#FFFAFA" gravity="center" id="" onClick="">
                    <text textsize="12" gravity="center" textcolor="#1E90FF" onclick="update/seeAll">مشاهده همه</text>
</frame>

• InlineUpdate :

امکان اجرای update به صورت offline را ارائه میدهد.

<page>
  <button onClick="inlineupdate/up">goto next page</button>
</page>
<inlineupdate id="up">
  {"widgetData":{"num":{"text":"2"}}}
</inlineupdate>

• Qr code :

یک پنجره تمام صفحه با یک qrCode اسکنر نمایش میدهد و مقدار بازگشتی را به عنوان یک variable ذخیره می کند و سپس به صورت آپدیتی با کلید qrcode برای شما ارسال می شود.

در صورت اجرای درست پرامپت "بارکد یا QR کد خود را اسکن کنید." نمایش داده میشود.

<page>
    <button text="QR code" onClick="qrcode">
</page>

• Web :

مقدار ورودی (URL) را داخل مرورگر گوشی باز میکند.

در صورت در دسترس نبودن لینک عبارت "لینک مورد نظر یافت نشد" نمایان میشود.

<page>
    <button text="open URL" onClick="web/http://example.com">
</page>

• Script:

برای اجرای یک تابع در script های نوشته شده ی شما استفاده می شود.

<page>
    <button text="call script" onClick="script/myscript:myFunction()">
    <script id="myscript">
    	function myFunction() {
      		console.log("Hello Appsan");
        }
    </script>
</page>

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

• appstorage:

برای ذخیره داده در shared storage  در اندروید و در local storage در وب ذخیره می شود و قابل دسترسی با bind است

برای ذخیره ی مقدار یک کلید را پس از \ قرار داده و مقدار مورد نظر برای ذخیره را پس از : قرار دهید.

<page>
    <button text="save text" onClick="appstorage/myKey:my text to save">
</page>

• location:

این اکشن از ورژن appsan:0.1.74 در دسترس است.

اکشن location برای مدیریت و نمایش تنظیمات موقعیت مکانی کاربر مورد استفاده قرار می‌گیرد. این اکشن دو حالت مختلف دارد: نمایش دیالوگ تنظیمات موقعیت مکانی و باز کردن تنظیمات موقعیت مکانی در سیستم عامل. با استفاده از این اکشن ها به همراه bind های مربوط به location می توانید در صورت خاموش بودن موقعیت مکانی درخواست روشن کردن آن را بدهید.

1. location/showdialog

این اکشن دیالوگ تنظیمات موقعیت مکانی را به کاربر نمایش می‌دهد تا وی بتواند تنظیمات موقعیت مکانی دستگاه را فعال کند. این اکشن به دقت بالایی برای موقعیت‌یابی نیاز دارد و از APIهای گوگل برای نمایش دیالوگ استفاده می‌کند.

مثال استفاده:

<button text="Show Location Dialog" onclick="location/showdialog"/>

این دکمه دیالوگ تنظیمات موقعیت مکانی را به کاربر نمایش می‌دهد.

2. location/openSettings

این اکشن صفحه تنظیمات موقعیت مکانی را مستقیماً در سیستم عامل باز می‌کند، جایی که کاربر می‌تواند موقعیت مکانی دستگاه را فعال یا غیرفعال کند.

مثال استفاده:

<button text="Open Location Settings" onclick="location/openSettings"/>

این دکمه صفحه تنظیمات موقعیت مکانی دستگاه را باز می‌کند.

Bind

با استفاده از bind می توانید یک variable را به مقادیر مختلف وصل کنید مثلا با گذاشتن "bind="os/version ورژن اندروید کاربر را دریافت کنید.

بایند های تعریف شده:

OS:

• os/screenwidth
• os/screenheight
• os/screenorientation
• os/layoutdirection
• os/version
• os/type

Appsan:

• appsan/version
• appsan/client

Element:

این bind اتریبیوت های المان را به شما تحویل می دهد ، به عنوان مثال برای گرفتن متن text از المان تکستی با آی دی txt1 این variable را داخل کد قرار دهید.:

<var id="textValue" bind="element/txt1:text"></var>

به طور کلی ساختار bind برای المان ها به صورت زیر است:

element/id:attr

که id ، آی دی المان مورد نظر و attr ، اتریبیوت آن المان است.

User:

این bind امکان گرفتن یک id منحصر به فرد از کاربر وارد شده را ایجاد می کند که می تواند برای شناسایی کاربر وارد شده استفاده شود.

مثال:

<var id="identity" bind="user/identifier"></var>

appstorage:

این bind امکان گرفتن مقدار ذخیره شده با appstorage را فراهم میکند. برای گرفتن مقدار کلید مقدار را بعد از / قرار دهید.

<var id="identity" bind="appstorage/myKey"></var>

component:

<var id="myValue" bind="component/myKey"></var>

Deeplink:

برای دسترسی به داده های دیپ لینک بایند های زیر وجود دارد که به صورت deeplink/key  با کلید های زیر در دسترس است.

Available:

 بررسی می کند که آیا کاربر از طریق یک لینک عمیق به جلسه فعلی رسیده است یا خیر.
برمی گرداند: "true" (رشته) اگر داده های لینک عمیق وجود داشته باشد، در غیر این صورت "false" (رشته).

Path:

 بخش مسیر اصلی URL لینک عمیق را استخراج می کند.
برمی گرداند: رشته مسیر (مثلا "/products/1234") یا `null` در صورت نیافتن داده های لینک عمیق.

Query:

 پارامترهای کوئری درون لینک عمیق را جدا می کند.
برمی گرداند: رشته ای که نشان دهنده پارامترهای کوئری است. (مثلا "?color=blue&size=large") یا `null` در صورت نیافتن داده های لینک عمیق.

queryjson:

 یک رشته json از پارامتر ها ی داخل deeplink را بر میگرداند.

Host:

 بخش نام میزبان (hostname) در URL لینک عمیق را بازیابی می کند.
برمی گرداند: رشته نام میزبان (مثلا "[www.example.com](https://www.example.com)") یا `null` در صورت نیافتن داده های لینک عمیق.

Port:

 شماره پورت مشخص شده در URL لینک عمیق (در صورت وجود) را استخراج می کند.
برمی گرداند: رشته شماره پورت (مثلا "8080") یا `null` در صورت نیافتن داده های لینک عمیق.

Fragment:

 شناسه قطعه (fragment identifier) در URL لینک عمیق را که اغلب برای ناوبری درون صفحه ای استفاده می شود، بازیابی می کند.
برمی گرداند: رشته قطعه (مثلا "#section3") یا `null` در صورت نیافتن داده های لینک عمیق.

Pathsegments:

 بخش های جداگانه مسیر لینک عمیق را به صورت یک آرایه ارائه می دهد.
برمی گرداند: رشته ای حاوی بخش های مسیر که با کاما جدا شده اند (مثلا "products,1234") یا `null`در صورت نیافتن داده های لینک عمیق.

Queryparameters:

 بخش پارامترهای کوئری در لینک عمیق را به یک نمایش رشته ای کاربرپسند تبدیل می کند.
برمی گرداند: رشته ای با قالبی که پارامترهای کوئری را نشان میدهد (مثلا "{color: blue, size: large}") یا `null` در صورت نیافتن داده های لینک عمیق.

location:

این بایند از ورژن appsan:0.1.74 در دسترس است.

location/on:

Bind location/on برای بررسی فعال یا غیرفعال بودن موقعیت مکانی (GPS) بر روی دستگاه کاربر استفاده می‌شود. این Bind به توسعه‌دهندگان امکان می‌دهد تا به سادگی وضعیت GPS دستگاه را بررسی کرده و نتیجه آن را دریافت کنند.

مقدار بازگشتی:

• اگر GPS فعال باشد، مقدار "true" بازگردانده می‌شود.
• اگر GPS غیرفعال باشد، مقدار "false" بازگردانده می‌شود.

آپدیت کردن صفحات بدون ایجاد صفحه جدید

اگر در خواصی که از اکشن پشتیبانی می کنند از اکشن update استفاده کنید، پیامی با اطلاعات داخل صفحه (به فصل "مقادیر ارسالی برای سرور" مراجعه کنید) برای میکروسرویس شما ارسال میشود. داخل این پیام کلید update وجود دارد که با استفاده از مقدار ورودی آن که در کد xml خود پس از “ / ” وارد کردید میتوانید تغییرات مورد نیاز را مشخص کنید.

علاوه بر مقدار ورودی کلید update دیتای صفحه ای که کاربر مشاهده می کند نیز برای شما ارسال می شود که میتوانید از آن برای شناسایی تغییرات مورد نیاز استفاده کنید. (به فصل "مقادیر ارسالی برای سرور" مراجعه کنید)

برای مشخص کردن تغییرات شما باید کد JSON به شکل زیر بسازید:

{
    widgetdata: {
        [id]:{
            [attr]:[value]
            color:red,
            text:"hello"
            override
        }
    },
 
    variabledata:{
        var1:3
    }
 
}

همان طور که در مثال مشخص شده است، تغییرات اعمالی به دو دسته تقسیم می شوند :

1. widgetdata : برای مشخص کردن تغییرات المان ها استفاده می شود.
2. variabledata : برای تغییر در variable ها مورد استفاده قرار میگیرد.

• widgetdata :

تغییرات المان ها داخل این کلید قرار میگیرند.

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

برای مثال همان طور که در کد بالا دیده میشود با گذاشتن text به عنوان کلید و متن “hello” به عنوان مقدار متن نمایش داده شده روی دستگاه کاربر به “hello” تغییر میکند و این اتفاق بدون باز شدن صفحه جدید رخ می دهد.

• variabledata :

تغییرات variable ها در این کلید قرار می گیرد. ساختار جیسونی که داخل این کلید قرار میگیرد به صور ت نام متغیر به عنوان کلید و مقدار جدید آن به عنوان مقدار خواهد بود.

مقادیر ارسالی برای سرور

با هر بار صدا شدن میکروسرویس شما مقادیری برای شما داخل یک JSON ارسال میشود این مقادیر به صورت زیر است:

• Inputs :

مقادیر المان هایی که برای آن ها id تعریف کرده ایددر این کلید جیسون برای شما ارسال می شود. این مقادیر برای هر المان متفاوت است به عنوان مثال مقدار المان  text متن داخل آن و مقدار المان textInput متن ورودی کاربر میباشد.

تمام این مقادیر به صورت یک json برای شما ارسال شده که در یک طرف id المان به عنوان کلید و مقدار المان به عنوان مقدار جیسون داده میشود.

برای مثال با ارسال شدن کد xml زیر:

<page>
    <text id="text 1" text="enter your phone number"/>
    <texstInput id="phone" hint="phone number"/>
    <button text="goto page 2" onClick="command/page2"/>
</page>

مقدار جیسون بازگردانده شده پس از انتخاب دکمه goto page 2 برابر با مقدار زیر خواهد بود:

{
    "text1": "enter your phone number",
    "phone": "01234566789"
}

که “0123456789” مقدار وارد شده توسط کاربر است.

تمامی المان هایی که id داشته باشند داخل این JSON نمایش داده می شوند. همین چنین متغیرهایی (variable) که تعریف می شوند نیز به همین صورت نمایش داده می شوند.

• Command :

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

• Update :

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

• sdp_userId :

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