مستندات اپسان

• ساختار زبان
• منشاء
• رندر شدن روی دستگاه
• المان ها
• مقدمه
• Page
• Dialog
• PermissionDialog
• FAB
• Permission
• Text
• AutoCompleteTextInput
• TextInput
• Checkbox
• Button
• Divider
• Card
• Image
• Map
• Marker
• Videoplayer
• DropDown
• SimpleDialog
• Snackbar
• Frame
• Footer
• المان های قابل رویت
• المان های غیر قابل رویت
• BottomSheetDialog
• ImageButton
• Img
• InputTextDialog
• ProgressBar
• RadioButton
• RadioGroup
• ButtonGroup
• Action
• InlineUpdate
• material-textinput
• date picker
• BottomSheet
• variable
• deepLinkReceiver
• OSM Map
• webpage
• اکشن ها
• انواع اکشن ها
• آپدیت کردن صفحات بدون ایجاد صفحه جدید
• بخش توسعه دهنده
• ادیتور
• دیباگ
• طراحی پروتوتایپ
• استفاده از جاوا اسکریپت در اپسان
• متد ها
• تحلیل سفر مینی‌اپ
• معرفی تحلیل سفر مینی‌اپ
• مینی‌اپ بومی: حالت خودکار و تنظیم سفر در پنل
• مینی‌اپ بومی: ثبت دستی مراحل و نتیجه سفر
• مینی‌اپ وب: تحلیل خودکار و ثبت دستی سفر

ساختار زبان

منشاء

زبان اپسان بر اساس XML  طراحی شده است و به طور کلی از قوانین XML  پیروی می کند.

خلاصه ای از قوانین XML به صورت زیر است:

• هر صفحه از تعدادی تگ (tag) تشکیل میشود که با استفاده از ساختار <tag></tag> نمایش داده می شود که <tag> به معنای شروع تگ و </tag> نشان دهنده ی پایان این تگ است.

<myTag></myTag>

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

<parentTag>
	<childTag>
    </childTag>
</parentTag>

• برای مشخص کردن خواص (attribute) یک تگ میتوان جلوی نام تگ شروع کننده این خواص را نوشت و به آن ها مقدار داد.

<myTag attribute1="value1" attribute2="value2"></myTag>

• در صورتی که یک تگ فرزندی نداشته باشد میتوان برای کوتاه کردن کد از نوشتن تگ پایانی صرف نظر کرد و به ازای آن از "/>" در آخر تگ شروع کننده استفاده کرد.

<myTag attribute1="value1" attribute2="value2"/>

رندر شدن روی دستگاه

زبان اپسان مانند HTML به صورت صفحه صفحه رندر می شود.

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

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

هر یک از این المان ها در بخش المان ها مفصلا بررسی می شود.

المان ها

مقدمه

المان ها قطعات سازنده ی نمای اپسان شما هستند.

هر المان توسط دستگاه بررسی میشود و به المان مشابه در اندروید تبدیل میشود. هرکدام از المان ها خواص خود را دارند برای مثال المانی که نیاز به تصویر داشته باشد خاصیت تصویر پذیری دارد. در ادامه به بررسی انواع المان ها و خواص آن ها خواهیم پرداخت.

همین طور بین بعضی از المان ها خواص مشترکی وجود دارند که آن را مشاهده می کنیم.

اشتراک همه المان ها

id :

همه ی المان ها قابلیت id پذیری را دارند در نتیجه شما میتوانید به تمام المان ها، یک id یکتا نسبت دهید تا بتوانید مقدارآن ها را در زمان بازگشت نتایج بررسی کنید. ( رجوع شود به بخش " مقادیر ارسالی برای سرور" )

المان های در بر گیرنده

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

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

• Page
• Dialog
• PermissionDialog

المان های فرزند

المان هایی هستند که بر روی المان های مادر اجرا میشوند.

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

• Permission
• Fab
• Text

• AutoCompleteTextInput

• TextInput
• Checkbox
• Button
• Divider
• Image
• Map
• Marker
• VideoPlayer
• DropDown
• SimpleDialog
• Snackbar
• Frame
• Footer

Page

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

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

• Title :

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

• onBack :

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

• Layout :

نوع چیدمان صفحه را مشخص میکند و دو مقدار linear_horizontal و linear_vertical را میپذیرد.

• OnShown :

اکشنی که موقع نمایش داده شدن صفحه رخ میدهد را مشخص میکند.

• OnResume :

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

• OnPause :

اکشنی که موقع pause شدن صفحه رخ میدهد را مشخص میکند.

• OnDestroy :

اکشنی که موقع از بین رفتن صفحه رخ میدهد را مشخص میکند.

• toolbarColor :

رنگ toolbar را مشخص میکند.

• toolbar :

برای نمایش toolbar است.

• statusbarColor :

رنگ statusbar را مشخص میکند.

• clearBackStack :

صفحات قبلی را از بازگشت حذف میکند و در نتیجه با انتخاب بازگشت توسط کاربر در صورت عدم وجود دستور خاصی در onback ، برنامه بسته میشود.

• scrollable :

خاصیت اسکرول پذیری صفحه را مشخص میکند. مقادیر قابل قبول true و false می باشد.

• windowsoftinputmode :

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

و نمونه ای از کد با فرزند image را در زیر مشاهده می کنیم:

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
     <image src = "http://162.55.105.137:8080/api/public/dl/6-OQTsC-"  scaletype ="center_crop"   width="300" height="300" margin_bottom="500" margin_top="50"></image>
</page>

نتیجه ی اجرای کد بالا به شکل زیر است :

Dialog

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

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

• Text :

متن توضیحات دایالوگ را مشخص میکند.

• Title :

تیتر دایالوگ را مشخص میکند.

• Onshown :

اکشنی که موقع نمایش داده شدن دایالوگ رخ میدهد را مشخص میکند.

• Ondismiss :

اکشنی که موقع dismiss شدن دایالوگ رخ میدهد را مشخص میکند.

• Background :

رنگ پس زمینه دایالوگ را مشخص میکند.

• TextColor :

.رنگ متن توضیحات دایالوگ را مشخص میکند

در ادامه یک نمونه از کد dialog را مشاهده کنید:

<dialog borderCornerRadius="3">
    <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 title="">
    <text id="txtP" text="Not updated"/>

    <button text="open dialog" onclick="dialog/d1"/>
    <button text="update text" onclick="script/s1:update()"/>
    <button text="auto close dialog" onclick="dialog/d1;script/s1:autoCloseDialog()"/>

    <script id="s1">
    function update() {
    Appsan.setProperty("txtP", "text", "Updated from page");
    }

        function autoCloseDialog() {
            setTimeout(function() {
                Appsan.runAction("app/closedialog:d1");
        console.log("ran")
            }, 2000);
        }
    </script>
</page>

<bottomsheetdialog id="d1">
<text id="txt" text="Not updated"/>
<button text="Update Me" onclick="script/s2:update()"/>
<button text="Update Parent" onclick="script/s2:updateParent()"/>
<button text="close" onclick="app/closedialog"/>
<button text="close with script" onclick="script/s2:closeDialog()"/>
<script id="s2">
    function update() {
    Appsan.setProperty("txt", "text", "Updated");
    }
    function updateParent() {
    Appsan.setProperty("txtP", "text", "Updated from dialog");
    }
    function closeDialog() {
    Appsan.runAction("app/closedialog");
    }

    function autoCloseDialog() {
    setTimeout(function() {
                    Appsan.runAction("app/closedialog:d1");
    console.log("ran")
    }, 2000);
    }
</script>
</bottomsheetdialog>

PermissionDialog

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

خواص این المان :

     ↵  onAllowed :

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

فرزندان المان :

     ↵  Permission :

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

FAB

این المان یک المان فرزند است که Floating Action Button نام دارد و معمولا به شکل یک دکمه ی دایره ای است که با کلیک بر آن می توان مانند یک button اکشنی را اجرا کند.

خواص این المان :

     ↵  Validate :

با نوشتن id ورودی هایی که نیاز به چک شدن دارن و جدا کردن آن ها با “ , ” تمام تکست باکس ها و دیگر ورودی ها با regex که داخل خاصیت validation در آن المان داده شده چک میشوند و در صورتی که تمام آن ها درست بودند اکشن نهایی داخل onclick اجرا میشود. این اتفاقات پس از کلیک شدن المان رخ می دهد.

     ↵  OnClick :

اکشنی که موقع click شدن روی این المان رخ میدهد را مشخص میکند.

     ↵  Align :

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

     ↵  src :

اگر نیاز باشد عکسی در این المان نمایش داده شود آدرسش با این ویژگی مقداردهی میشود.

     ↵  tint :

رنگ عکس را تغییر میدهد.

در ادامه یک نمونه از کد fab را مشاهده کنید:

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
     <fab  scaletype ="center_crop"   width="300" height="300" margin_bottom="670" margin_right="170" background="#E64724" visibility="visible"></fab>
</page>

 در نتیجه کد فوق به صورت زیر اجرا میشود:

Permission

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

اطلاعاتی که در حال حاضر پشتیبانی میشود عبارت است:

1. شماره تلفن (phone)

2. موقعیت کاربر (location)

خواص این المان :

     ↵  Required :

                نشان دهنده اجباری بودن یا نبودن مقدار درخواستی میباشد. و مقدار true برای اجباری بودن و false به معنی اجباری نبودن است.

     ↵  Request :

                نوع مقدار مورد نیاز را مشخص میکند که میتواند phone برای گرفتن شماره تلفن همراه و  location برای دریافت موقعیت جغرافیایی                     کاربر به صورت   latitude,longitude می باشد. نحوه دریافت اطلاعات در فصلی به همین نام بررسی میشود.

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

<permissionDialog id="permDialog">
  		<permission id="phonePerm" request="phone" required="true"></permission>
</permissionDialog>

و نتیجه ی اجرای کد فوق به شکل زیر است :

Text

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

خواص این المان :

     ↵  Text :

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

     ↵  TextStyle :

                استایل متن را مشخص میکند و مقادیر bold ، italic ، bold_italic و normal را میپذیرد.

     ↵  AllCaps :

                حروف متن را بزرگ میکند.

     ↵  TextIsSelectable :

                متن را قابل انتخاب میکند.

     ↵  Ellipsize :

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

     ↵  MaxLines :

                بیشترین تعداد خط برای متن را مشخص میکند.

     ↵  textColor :

                رنگ متن مورد نظر را مشخص میکند.

     ↵  textSize :

                اندازه متن مورد نظر را مشخص میکند.

     ↵  Textalignment :

                جهت متن مورد نظر را مشخص میکند و میتواند مقادیر  right برای راست،  left برای چپ و center برای وسط را داشته یاشد. مقدار                        پیشفرض center است.

     ↵  Renderas :

                برای شکل دهی به متن (formatting) میتوانید از تگ های html یا markDown استفاده کنید که برای این کار به ترتیب مقادیر html یا                      markdown استفاده می شود. برای غیر فعال سازی از text استفاده کنید. مقدار پیشفرض نیز text میباشد.

     ↵  font :

                با وارد کردن لینک فونت .ttf میتوانید از فونت مورد نظر خودتان برای متن استفاده کنید.

     ↵  justificationMode:

.استفاده میشود  justificationMode="inter_word" کردن متن از دستور   justify  برای             

در ادامه یک نمونه از کد text را مشاهده می کنید:

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

نتیجه اجرای کد فوق به صورت زیر است :

AutoCompleteTextInput

این المان مشابه با المان textInput است با این تفاوت که شما می توانید لیستی از پیشنهادات یا suggestion وارد کنید و در هنگام نوشتن حروفی از آن کلمه ، آن کلمه به کاربر پیشنهاد شود. متن پیشنهادی به صورت آرایه در اتریبیوت suggestion قرار میگیرد.

     ↵  OnSuggestionSelected :

                زمانی که یکی از گزینه ها انتخاب شود صدا زده میشود.

     ↵  Threshold :

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

     ↵  value:

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

     ↵  rightIcon:

               امکان نمایش آیکون در سمت راست textinput را فراهم میکند.

     ↵  leftIcon:

              امکان نمایش آیکون در سمت چپ textinput را فراهم میکند.

     ↵  suggestion :

              گزینه های پیشنهادی را نشان میدهد. میتوان به دو صورت پیاده کرد.

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
	<frame margin="center" width="wrap_content" height="770">
        <autocompletetextinput id="in">
              <suggestion text="tehran" value="tehran"/>
          	  <suggestion text="karaj" value="karaj"/>
		</autocompletetextinput>
    </frame>
</page>

یا 

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
	<frame margin="center" width="wrap_content" height="770">
        <autocompletetextinput 
                       id="in" suggestions="[&quot;tehran&quot;,&quot;karaj&quot;,&quot;tabriz&quot;]">
		</autocompletetextinput>
    </frame>
</page>

آرایه شما باید escape شده باشد مثلا آرایه [ "a" , "b" , "c" ] به صورت زیر باید نوشته شود:

["a","b","c"]

اجرای کد فوق به شکل زیر است :

TextInput

ورودی متن برای کاربر ایجاد میکند.

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

و علاوه بر آن خواص زیر را نیز داراست :

   ↵  Hint :

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

   ↵  HintColor :

                رنگ hint را مشخص میکند.

     ↵  Inputtype :

                مقدار ورودی کاربر را محدود میکند. می تواند مقادیر number برای عدد،  password برای رمز و  phone برای شماره تلفن داشته باشد. این مقدار فقط نوع کیبرد دستگاه را مشخص میکند و کاربر میتواند با استفاده از کیبرد خارجی مقادیر دیگری نیز وارد کند برای چک کردن این مقادیر از  خاصیت validation استفاده کنید.

                مقادیر number و number_signed و number_decimal و number_decimal_signed و password و number_password و phone و none را میتواند بگیرد.

     ↵  Multiline :

              در صورت true بودن به کاربر اجازه میدهد بیش از یک خط اطلاعات وارد کند و در غیر این صورت به صورت تک خطی نمایش داده می شود.

     ↵  Validation :

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

                مقادیر phone_number و number و email و required را میگیرد.

     ↵  onChange :

                پس از هر بار تغییر در مقدار المان صدا میشود و مقدار آن میتواند اکشن باشد.

     ↵  onInvalid :

                پس از هر بار که مقدار ورودی نامعتبر باشد صدا میشود و مقدار آن میتواند اکشن باشد.

     ↵  Enabled :

                قابل انتخاب بودن المان را مشخص میکند.

     ↵  Request :

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

     ↵  maxlength:

                حداکثر طول ورودی را مشخص میکند.

در ادامه یک نمونه از textinput را مشاهده می کنید:

<page title="ورود به اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent">
  <frame layout="linear_vertical" margin_top="100" height="770" width="match_parent">
     <frame layout="linear_horizontal" width="wrap_content" gravity = "center" margin_top="-400">
       <image src="http://162.55.105.137:8080/api/public/dl/DG6B6onI" width="25" height="25"></image>
       <textInput id="username" text="" textColor="#000000" hint="Username"  width="250"></textInput>
     </frame>
</page>

اجرای کد فوق به صورت زیر است :

Checkbox

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

خواص این المان :

     ↵  Text :

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

     ↵  Disabled :

قابل تغییر بودن المان را مشخص میکند اگر true باشد غیر قابل تغییر و اگر false باشد قابل تغییر است.

     ↵  Checked :

این متغیر دو مقدار true یا false را می پذیرد و در صورتی که مقدار آن true باشد به صورت پیش فرض چک شده نمایش داده میشود.

در ادامه یک نمونه کد از checkbox را مشاهده می کنید:

<page title="چک باکس تست" background="#FFFFFF" toolbarColor="#E64724" width="match_parent" height="match_parent" scrollable="true"> 
   <frame layout = "" layout="linear_vertical" width="200" >
     <frame  width="match_parent" height="wrap_content"gravity="center" background="#DDD" borderCornerRadius="3" margin_top="70">
     <checkbox text="اپسان چک" id="onlineCheckBox" checked="true" color = "#E64724"  width="180" height="70"></checkbox>
      <image src ="https://i.ibb.co/9Hwn6TW/monitor.png" width="65" height="65" margin_top="21"></image>
     </frame>
</page>

نتیجه اجرای کد به صورت زیر نمایش داده می شود :

Button

این المان فرزند موجب ایجاد یک دکمه قابل کلیک میشود.

خواص این المان تمام خواص المان text را در برگرفته است و علاوه بر آن خواص زیر را نیز داراست:

   ↵  Onclick :

                در صورت کلیک شدن المان صدا میشود و مقدار آن یک اکشن می باشد.

   ↵  Enabled :

                قابل انتخاب بودن این المان را مشخص میکند.

   ↵  ProgressbarGravity :

                مکان نسبی Progressbar بر روی button با این ویژگی مقدار دهی میشود.و مقادیر left,right,center را میپذیرد.

   ↵  ProgressbarPadding :

                مقدار فاصله از ۴ طرف را میتوان با این عدد مقدار دهی کرد.

   ↵  ProgressbarRadius :

                شعاع Progressbar را میتوان با این ویژگی مقداردهی کرد.

   ↵  ProgressbarColor :

                رنگ Progressbar را مشخص میکند.

   ↵  ProgressbarBackgroundColor :

                رنگ پس زمینه Progressbar را مشخص میکند.

   ↵  ProgressbarStrokeWidth :

                طول دایره داخلی progressbar را مشخص میکند.

   ↵  ShowProgressbar :

                با این ویژگی میتوان نمایش یا عدم نمایش Progressbar را مشخص کرد.

   ↵  Validate :

                با نوشتن id ورودی هایی که نیاز به چک شدن دارن و جدا کردن آن ها با  “ , ” تمام تکست باکس ها و دیگر ورودی ها با regex که داخل خاصیت validation در آن المان داده شده چک میشوند و در صورتی که تمام آن ها درست بودند اکشن نهایی داخل onclick اجرا میشود. این اتفاقات پس از کلیک شدن المان رخ می دهد.

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

<page title="اپسان" background="#FFFFFF" toolbarColor="#E64724" width="match_parent" height="match_parent">
  <frame  width="match_parent" layout="linear_vertical" height="match_parent" background="#FFF" >
     <image src = "http://162.55.105.137:8080/api/public/dl/6-OQTsC-"  scaletype ="center_crop"   width="300" height="300" margin_bottom="100"  margin_top="50"></image>
      <button textcolor="#FFDDCE"  background="#E64724" borderCornerRadius="10" width="250" onClick="command/welcomeAdmin" margin_top="-100">ورود به آموزش اپسان</button>
      <button textcolor="#FFDDCE"  background="#E64724" borderCornerRadius="10"  width="250" onClick="command/welcomeStudent">خروج</button>
  </frame>
</page>

و نتیجه ی اجرای کد فوق به شکل زیر است :

Divider

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

خواص این المان :

     ↵  Color :

              رنگ پس زمینه المان را مشخص میکند. مقدار این خاصیت یک کد رنگ HTML است.

     ↵  Size :

              ضخامت خط را مشخص میکند و واحد آن dpi میباشد.

     ↵  Orientation :

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

کد زیر مثالی از Divider است :

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
   <text g textalignment="center" renderas="html" textsize="22" text="<b>اپلیکیشن اپسان</b>" margin_top = "50" margin_bottom="50"></text>
  <divider color = "#E64724" size = "2" ></divider>
     <text g textalignment="center" renderas="html" textsize="22" text="<b>خوش آمدید</b>" margin_top = "50" margin_bottom="50"></text>
</page>

کد بالا به صورت زیر اجرا می شود :

Card

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

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

   ↵  Onclick :

                در صورت کلیک شدن المان صدا میشود و مقدار آن یک اکشن می باشد.

   ↵  Size :

                سایز المان را مشخص میکند.

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

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
  <card height="wrap_content" width="wrap_content" margin="50" gravity="center">
       <text textcolor="E64724" textsize="20"  gravity="center_right">به  اپسان خوش آمدید</text>
      <button textcolor="#FFDDCE"  background="#E64724" borderCornerRadius="10"  width="250">خروج</button>
    </card>
</page>

و نتیجه ی اجرای کد فوق به شکل زیر است :

Image

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

خواص این المان :

     ↵  Src :

              لینک تصویر میباشد و تصویر از این لینک بارگیری می شود.

     ↵  Aspectratio :

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

     ↵  NoPlaceholder :

              Placeholder را حذف میکند.

     ↵  Tint :

              رنگ عکس را تغییر میدهد.

     ↵  scaletype :

              نحوه نمایش تصویر را مشخص میکند و مقادیر center برای نمایش در مرکز  center_crop برای نمایش در مرکز با بریدن اضافات                          center_inside برای نمایش در مرکز و داخل،  fit_center برای کوچک کردن عکس به صورتی که با طول و عرض داده شده و مرکز محور مطابق شود ، fit_end برای نمایش در انتها  fit_start برای نمایش در شروع و  fit_xy برای پیروی از طول و عرض مادر و focus_crop برای برش از قسمت متمرکز را میگیرد.

در ادامه یک نمونه از کد image را مشاهده می کنید:

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
     <image src = "http://162.55.105.137:8080/api/public/dl/6-OQTsC-"  scaletype ="center_crop"   width="300" height="300" margin_bottom="500" margin_top="50"></image>
</page>

نتیجه کد به صورت زیر نمایش داده می شود :

Map

این المان فرزند، نقشه ای را نمایش می دهد که میتوان به طور دلخواه لوکیشنی بر آن تنظیم کرد.

خواص این المان :

     ↵  Latitude :

                عرض جغرافیایی مرکز نمایش نقشه

     ↵  Longitude :

                طول جغرافیایی مرکز نمایش نقشه

     ↵  ShowTitle :

                این ویژگی مشخص میکند عنوان نمایش داده شود یا خیر.

     ↵  Text :

                todo

     ↵  DisableScroll :

                غیر فعال بودن خاصیت scroll نقشه را مشخص میکند.

     ↵  DisableZoom :

                غیر فعال بودن خاصیت zoom نقشه را مشخص میکند.

     ↵  DisableTilt :

                قابلیت زاویه دادن به نقشه را حذف میکند.

     ↵  Title :

                عنوان نقشه را مشخص میکند.

     ↵  Icon :

                icon نقشه را مشخص میکند.

     ↵  OnClick :

                این ویژگی مشخص میکند زمانی که روی نقشه کلیک شد چه اتفاقی رخ دهد و یک اکشن میپذیرد.

     ↵  OnReady :

                زمانی که نقشه به طور کامل load شود اجرا میشود.

     ↵  Color :

                رنگ را مشخص میکند.

     ↵  Zoom :

              بزرگنمایی نقشه در هنگام شروع

     ↵  showUserDot :

                مقداری true یا false که به ترتیب نمایش یا عدم نمایش نقطه آبی مکان فعلی کاربر را مشخص میکند.

     ↵  onChange :

                در زمان تغییر مکان نقشه توسط کاربر صدا میشود و مقدار آن نیز یک اکشن است.

در ادامه یک نمونه از کد map را مشاهده می کنید که لوکیشن آن بر دانشگاه شهید بهشتی تنظیم شده است:

<page title="نمایش نتایج روی نقشه" scrollable="false" toolbarColor="#E64724">
  <map id="map" width="match_parent" height="match_parent" latitude="35.8029459" longitude="51.3933681" showUserDot="true" onChange="update/map">
    <polylineGroup>
      <point latitude="35.8029459" longitude="51.3933681" ></point>
    </polylineGroup>
  </map>
<footer gravity="right" margin_bottom="10" background="#0FFF" height="120" >
<frame width="wrap_content"  scrollable="true">
<frame onClick="command/details" width="wrap_content" height="wrap_content" background="#FFF" layout="linear_horizontal"  evenweight="false" scrollable="false" borderCornerRadius="2">
<frame  width="wrap_content"  layout="linear_vertical" scrollable="false">
<text width="wrap_content" text="map"/>
<text width="wrap_content" textsize="15" textcolor="#8e8e8e" text="در چند متری شما"/>
</frame>
</frame>
</frame>
</footer>
</page>

و در نتیجه کد فوق به صورت زیر اجرا میشود :

Marker

این المان فقط میتواند فرزند المان map باشد و یک نشانگر (پوینتر) بر روی نقشه نمایش می دهد.

خواص این المان عبارتند از :

     ↵  Title :

                تیتر مکان نمایش داده شده رو ی نقشه

     ↵  onClick :

                اکشنی که پس از کلیک روی متن مکان رخ میدهد.

     ↵  OnMarkerClick :

                اکشنی که پس از کلیک روی marker رخ میدهد.

     ↵  Text :

                متنی که زمانی که روی marker کلیک شود نمایش داده میشود.

نمونه کدی از marker را مشاهده می کنیم :

<page title="مشخصات نتیجه روی نقشه" scrollable="false" toolbarColor="#E64724"> 
<map  height="250" width="match_parent" latitude="35.757956" longitude="51.410821" >
<marker latitude="35.757205" longitude="51.410530" title="{{title}}"/>
</map>
</page>

و نتیجه اجرای آن به شکل زیر است :

Videoplayer

المان فرزندی که یک ویدیو را به کاربر نمایش میدهد.

خواص این المان :

     ↵  Src :

                لینک دانلود ویدیو (این لینک باید مستقیم باشد)

     ↵  AutoPlay :

                دو مقدار true یا false را دریافت می کند. در صورتی که مقدار آن true باشد، ویدیو به صورت خودکار پخش می شود.

     ↵  Controlable :

               دو مقدار true یا false را دریافت می کند. در صورتی که مقدار آن true باشد، نوار کنترل ویدیو (برای pause یا play کردن و یا تغییر                        volume) نمایش داده می شود در غیر این صورت این موارد قابل کنترل نخواهد بود.

     ↵  PlayAudio :

               دو مقدار true یا false را دریافت می کند. در صورتی که مقدار آن false باشد، ویدیو بدون صدا (mute) پخش خواهد شد.

در ادامه یک نمونه از کد video player را مشاهده می کنید که ویدیو با لینک مورد نظر را اجرا می کند:

<page title="تماشای ویدیو" toolbarColor="#E64724">
  <videoplayer 
           src="https://aspb28.cdn.asset.aparat.com/aparat-video/147ec9a4b7a2704556d6e1bf2a2b54a833809454-360p.mp4?wmsAuthSign=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjJkMjg2YWYzYzdmNzgyODdkOGY5Yzc0Y2UxNDFkYjdlIiwiZXhwIjoxNjI1NjAzODU2LCJpc3MiOiJTYWJhIElkZWEgR1NJRyJ9.hzd_dtz5xHDevnDoExvUbw3RtV4tyio7RvEUb07Os3U"
           width="match_parent" height="match_parent"
           autoplay="true" controlable="true" playaudio="true" margin_top="150" />
</page>

اجرای کد بالا به شکل زیر است :

DropDown

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

هر گزینه با یک item نمایش داده میشود.

خواص این المان :

     ↵  onSelectionChange :

              مقدار ورودی آن یک update است و تغییری را نمایش میدهد.

     ↵  Hint :

              یک متن به عنوان راهنمایی را نشان میدهد.

     ↵  Rtl :

              نشان میدهد جهت راست به چپ است یا برعکس.

     ↵  value :

              مقادیر المان را در خود نگه میدارد.

در اینجا نمونه کدی از DropDown می بینیم :

<page title="ورود به اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent">
<frame width="240" height="765">
  		<frame borderStrokeWidth="0.2" borderColor="#4682B4" borderCornerRadius="3" width="240" margin_bottom="300">
			<dropdown onSelectionChange="" id="selected_gender" hint="انتخاب کنید..." >
				<item id="non-binary" onClick="" text_color="#7F7F7F">هیچکدام</item>
				<item id="male" onClick="">مرد</item>
				<item id="female" onClick="">زن</item>
			</dropdown>
          </frame>
</frame>
</page>

و اجرای آن به شکل زیر است :

SimpleDialog

این المان به طور کلی مشابه با المان dialog است با این تفاوت که از آن المان ساده تر است ، یعنی المان دیگری درون آن قرار نمیگیرد و فقط قابلیت نمایش متن و عنوان را دارد. برای فراخوانی این المان نیاز است در یک المان دیگر در بخش onClick عبارت "dialog/id" را قرار دهید که مقدار id باید با مقدار مشخص شده ی شما (مانند مثال زیر) جایگزین شود.

خواص این المان :

   ↵  Onclick :

                در صورت کلیک شدن المان صدا میشود و مقدار آن یک اکشن می باشد.

در ادامه یک نمونه از کد simpleDialog را مشاهده کنید:

<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="dialog/smpdg">تست دیالوگ</button>
  </frame>
</page>

<simpledialog title="dialog" text="This is a message" id="smpdg"> </simpledialog>

و در نتیجه کد فوق به صورت زیر اجرا میشود :

Snackbar

به کمک این المان شما می توانید یک snackbar را در اپلیکیشن خود نمایش دهید.

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

• Text :

متن توضیحات snackbar را مشخص میکند.

• Duration :

مدت زمان نمایش snackbar را مشخص می کند و سه مقدار long ، short و indefinite را می گیرد.

• Location :

محل قرار گیری اسنک بار را تعیین می کند و دو مقدار top و bottom را می گیرد.

• BackgroundColor :

تیتر رنگ پس زمینه snackbar را مشخص میکند

• TextColor :

رنگ متن توضیحات متن snackbar را مشخص میکند.

• Reverse :

جهت چینش اجزا را مشخص میکند.

• OnAction :

اکشنی که این snackbar اجرا میکند را مشخص میکند.

• Action :

متن اکشنی که این snackbar اجرا میکند را مشخص میکند.

در ادامه یک نمونه از کد snackbar را مشاهده می کنید:

<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="snackbar/welcomeSnackbar" margin_top="100">تست اسنک بار</button>
    <snackbar text="به سرویس اپسان خوش آمدید" duration="long" location="bottom" textColor="FF5733" id="welcomeSnackbar">
  </snackbar>
  </frame>
</page>

و نتیجه ی اجرای کد فوق به شکل زیر است :

Frame

این المان برای نظم دادن به المان های دیگر کاربرد دارد ، به طوریکه المان های دیگر می توانند در این المان قرار گرفته و سپس اعمالی مثل margin را برای همه ی المان های داخل frame در نظر بگیریم.

خواص این المان :

   ↵  Layout :

                چیدمان اجزای درون frame را مشخص میکند و مقادیر linear_horizontal ، linear_vertical ، relative ، frame و flow را میپذیرد.

   ↵  WeightSum :

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

   ↵  EvenWeight :

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

   ↵  Reverse :

                جهت چینش اجزا را مشخص میکند.

   ↵  OnScroll :

                در صورت scroll شدن صدا زده میشود و مقدار آن یک اکشن میباشد.

   ↵  OnScrolledToEnd :

                در صورت scroll شدن تا انتهای frame صدا زده میشود و مقدار آن یک اکشن میباشد.

   ↵  OnScrolledToStart :

                در صورت scroll شدن تا ابتدای frame صدا زده میشود و مقدار آن یک اکشن میباشد.

   ↵  hidehorizontalscrollbar :

                اسکرول افقی را پنهان میکند. مقادیر: true , false.

   ↵  hideverticalscrollbar :

                اسکرول عمودی را پنهان میکند. مقادیر: true , false.

در ادامه یک نمونه از کد frame را مشاهده کنید:

<page title="اپسان" background="#FFFFFF" toolbarColor="#E64724" width="match_parent" height="match_parent">
  <frame  width="match_parent" layout="linear_vertical" height="match_parent" background="#D9D6D4" margin="30">
     <text gravity="center">به اپسان خوش آمدید</text>
      <button textcolor="#FFDDCE"  background="#E64724" borderCornerRadius="10"  width="200" >خروج</button>
  </frame>
</page>

و نتیجه ی اجرای کد فوق به شکل زیر است :

Footer

این المان در قسمت پایین صفحه قرار می گیرد و می توان المان های دیگر مثل text یا button را به آن اضافه کرد سپس بوسیله ی onClick المان های موجود می توان کاربر را به بخش های مورد نظر هدایت کرد

خواص این المان :

   ↵  Toback :

                نشان میدهد این المان پشت دیگر layout ها render میشود.

   ↵  WeightSum :

                این پارامتر مجموع وزن المان های داخل footer را مشخص میکند.

   ↵  EvenWeight :

                این ویژگی به این معناست که وزن همه المان های داخل footer یکسان است.

در ادامه نمونه کدی از استفاده footer با 3 بخش نظرسنجی ، خانه و پروفایل را مشاهده می کنیم :

<page title="اپسان" background="#DDDDDD" toolbarColor="#E64724" width="match_parent" height="match_parent" >
<footer background="#E64724">
        <frame layout="linear_vertical" background="#E64724" height="50">
            <frame layout="linear_horizontal" gravity="center">

               <frame layout="linear_vertical"  background="#E64724"  onclick=""  gravity="center">

                   <image src="https://s2.uupload.ir/files/round_account_circle_white_24dp_fhxf.png"
                          borderCornerRadius="0" width="24" height="24" gravity="right" />
                                      
          <text textsize="12" gravity="center" textcolor="white">پروفایل</text>
          </frame>
          
          <frame layout="linear_vertical"  background="#E64724" gravity="center">
          <image src="https://s2.uupload.ir/files/round_poll_white_24dp_ysj.png"
            borderCornerRadius="0" width="24" height="24" gravity="right" />
                                      
          <text textsize="12" gravity="center" textcolor="white">نظرسنجی</text>
          </frame>
          
           <frame layout="linear_vertical"  background="#E64724" gravity="center">

           <image src="https://s2.uupload.ir/files/round_home_white_24dp_rq7x.png"
                  borderCornerRadius="0" width="24" height="24" gravity="right"/>
                                    
          <text textsize="12" gravity="center" textcolor="white">خانه</text>
          </frame>

      </frame>
    </frame>
</footer>

</page>

و نتیجه ی اجرای کد فوق به شکل زیر است :

المان های قابل رویت

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

• Layout :

      نحوه چیدمان المان ها را مشخص میکند و دو مقدار linear_horizontal و linear_vertical وwrap_content وmatch_parent را قبول میکند.

               ↵  Linear_horizontal :

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

               ↵  Linear_vertical :

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

• Width :

      این خاصیت نشان دهنده طول (پهنا) یک المان است و میتواند مقادیر wrap_content ، match_parent و یا یک عدد را به خود اختصاص دهد.

               ↵  Wrap_content :

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

               ↵  Match_parent :

                          طول المان را به اندازه ی مقدار المان مادرش در نظر می گیرد. اگر المان مادری نداشته باشد اندازه صفحه دستگاه را میگیرد.

               ↵  عدد :

                          این عدد نشان دهنده طول المان در واحد dpi می باشد.

• Height :

       این خاصیت نشان دهنده عرض (ارتفاع) یک المان است و میتواند مقادیر wrap_content ، match_parent و یا یک عدد را به خود اختصاص دهد.

               ↵  Wrap_content :

                            عرض را نسبت به مقادیر داخل المان انتخاب میکند.

               ↵  Match_parent :

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

               ↵  عدد :

                          این عدد نشان دهنده عرض المان در واحد dpi می باشد.

• Padding :

      در داخل المان فضای خالی ایجاد میکند به این صورت که هر فرزند به اندازه مقدار داده شدن فاصله خود را از گوشه ی مادرش حفظ میکند.این خاصیت فقط میتواند عدد باشد و در واحد dpi محاسبه میشود.

• Padding_right :

      مانند padding عمل میکند اما فقط فاصله ی خود را از  گوشه راست مادرش حفظ میکند.

• Padding_left :

      مانند padding عمل میکند اما فقط فاصله ی خود را از  گوشه چپ مادرش حفظ میکند.

• Padding_top :

      مانند padding عمل میکند اما فقط فاصله ی خود را از  گوشه بالا مادرش حفظ میکند.

• Padding_bottom :

      مانند padding عمل میکند اما فقط فاصله ی خود را از  گوشه پایین مادرش حفظ میکند.

• Margin :

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

• Margin_right :

      مانند margin عمل میکند اما فقط فاصله ی خود را از  گوشه راست مادرش حفظ میکند.

• Margin_left :

      مانند margin عمل میکند اما فقط فاصله ی خود را از  گوشه چپ مادرش حفظ میکند.

• Margin_top :

      مانند margin عمل میکند اما فقط فاصله ی خود را از  گوشه بالا مادرش حفظ میکند.

• Margin_bottom :

      مانند margin عمل میکند اما فقط فاصله ی خود را از  گوشه پایین مادرش حفظ میکند.

• onClick :

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

• validate :

     با نوشتن id ورودی هایی که نیاز به چک شدن دارن و جدا کردن آن ها با  “ , ” تمام تکست باکس ها و دیگر ورودی ها با regex که داخل خاصیت validation در آن المان داده شده چک میشوند و در صورتی که تمام آن ها درست بودند اکشن نهایی داخل onclick اجرا میشود. این اتفاقات پس از کلیک شدن المان رخ می دهد.

• background :

       رنگ پس زمینه المان را مشخص میکند. مقدار این خاصیت یک کد رنگ HTML مانند 58D3F7 است.

• borderStrokeWidth :

     ضخامت حاشیه المان را مشخص میکند و یک عدد در واحد dpi است.

• borderStrokeDashWidth :

     ضخامت خط تیره ی حاشیه المان را مشخص میکند و یک عدد در واحد dpi است. پیشفرض آن 0 است.

• borderStrokeDashGap:

 فاصله ی بین هر خط تیره ی حاشیه المان را مشخص میکند و یک عدد در واحد dpi است. پیشفرض آن 0 است.

• borderColor :

       رنگ حاشیه المان را مشخص میکند. مقدار این خاصیت یک کد رنگ HTML است.

• borderCornerRadius :

    شعاع گوشه های حاشیه المان را مشخص میکند و یک عدد در واحد dpi است.

 . با دادن 4 مقدار 4 گوشه مختلف را مقداردهی میکنیم ↵         

• Visibility :

      قابل دیدن بودن المان را مشخص میکند.

دارای مقادیر visible و invisible و gone میباشد.

• Gravity :

      با استفاده از این خصوصیت، می توانیم مشخص کنیم که محتوای درون یک شیء چگونه موقعیت دهی شوند.

دارای مقادیر none و top و right و left و bottom و top_center و bottom_center و top_right و top_left و bottom_right و bottom_left و center_right و center_left و center و center_horizontal و center_vertical میباشد.

• SelfGravity :

      مکان خود المان را مشخص میکند.

• ChildGravity :

      مکان المان های داخلی را مشخص میکند.

• Clickable :

.قابل کلیک بودن یا نبودن المان را مشخص میکند       

• MaxHeight :

      بیشترین عرضی که المان میتواند داشته باشد را مشخص میکند.

• MaxWidth :

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

• Weight :

      اندازه نسبی یک عنصر نسبت به عناصر دیگر با این ویژگی مشخص میشود.

↵  هنگام استفاده ازین المان حتما باید مقدار width را wrap_content  کنید وگرنه برعکس شده و وزن بزرگتر کوچکتر دیده میشود. 

• Clickable :

      قابل کلیک بودن المان را مشخص میکند.

• Focusable :

      قابل focus بودن المان را مشخص میکند.

• Elevation :

      برای المان shadow قرار میدهد.

• OnFocus :

      زمانی که روی المان focus شود صدا زده میشود و مقدار آن یک اکشن است.

• OnFocusLost :

      زمانی که المان از حالت focus خارج شود صدا زده میشود و مقدار آن یک اکشن است.

• endiconmode :

     زمانی که میخواهیم متن زیر المانهای دیگر قرار نگیرند. ('endiconmode= 'costum )

المان های غیر قابل رویت

بعضی المان ها به کار بر نمایش داده نمی شوند و برای نگه داشتن اطلاعات از آن ها استفاده میشود.

یکی از این المان ها variable است که دارای دو خاصیت است :

1.  id

2. value
   

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

BottomSheetDialog

این المان به طور کلی مشابه با المان dialog است با این تفاوت که این دیالوگ در قسمت پایین صفحه نمایش داده می شود و مشابه با المان dialog المان های دیگر را داخل خود می پذیرد. توصیه می شود که از این دیالوگ به جای دیالوگ ساده استفاده شود زیرا از لحاظ طراحی در آخرین نسخه های اندروید از این دیالوگ استفاده شده است و باعث افزایش زیابیی بصری می شود.

برای فراخوانی این المان نیاز است در یک المان دیگر در بخش onClick عبارت "dialog/id" را قرار دهید که مقدار id باید با مقدار مشخص شده ی شما (مانند مثال زیر) جایگزین شود.

خواص این المان :

   ↵  Cancelable :

                قابل cancle بودن دایالوگ را مشخص میکند.

   ↵  dialogborderradius:

                ویژگی border-radius  گوشه های دیالوگ را تعیین میکند.

   ↵  hideverticalscrollbar:

                اسکرول بار را پنهان میکند و مقادیر true, false میگیرد.

   ↵  title:

                به کمک این اتریبیوت میتوان title المان را مشخص کرد.

   ↵  windowsoftinputmode:

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

   ↵  dialogborderradius:

                مقدار radius دیالوگ مشخص میکند.

   ↵  dialogbackground:

                رنگ background را مشخص میکند.

در ادامه یک نمونه از کد dialog را مشاهده کنید:

<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="dialog/btmdg">تست دیالوگ</button>
  </frame>
</page>

<bottomsheetdialog id="btmdg"> <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> </bottomsheetdialog>

و در نتیجه کد فوق به صورت زیر اجرا میشود :

ImageButton

این المان یک المان از جنس Button است و برای کاربر یک تصویر را به نمایش می گذارد.

خواص این المان :

     ↵  Src :

              لینک تصویر میباشد و تصویر از این لینک بارگیری می شود.

   ↵  Validate :

                با نوشتن id ورودی هایی که نیاز به چک شدن دارن و جدا کردن آن ها با  “ , ” تمام تکست باکس ها و دیگر ورودی ها با regex که داخل خاصیت validation در آن المان داده شده چک میشوند و در صورتی که تمام آن ها درست بودند اکشن نهایی داخل onclick اجرا میشود. این اتفاقات پس از کلیک شدن المان رخ می دهد.

     ↵  OnClick :

              در صورت کلیک شدن المان صدا میشود و مقدار آن یک اکشن می باشد.

     ↵  Align :

              موقعیت مکانی شروع المان در صفحه را مشخص میکند

     ↵  Tint :

              رنگ عکس را تغییر میدهد.

     ↵  scaletype :

              نحوه نمایش تصویر را مشخص میکند و مقادیر center برای نمایش در مرکز  center_crop برای نمایش در مرکز با بریدن اضافاتcenter_inside برای نمایش در مرکز و داخل،  fit_center برای کوچک کردن عکس به صورتی که با طول و عرض داده شده و مرکز محور مطابق شود ، fit_end برای نمایش در انتها  fit_start برای نمایش در شروع و  fit_xy برای پیروی از طول و عرض مادر و focus_crop برای برش از قسمت متمرکز را میگیرد.

Img

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

خواص این المان :

     ↵  Src :

              لینک تصویر میباشد و تصویر از این لینک بارگیری می شود.

   ↵  Validate :

                با نوشتن id ورودی هایی که نیاز به چک شدن دارن و جدا کردن آن ها با  “ , ” تمام تکست باکس ها و دیگر ورودی ها با regex که داخل خاصیت validation در آن المان داده شده چک میشوند و در صورتی که تمام آن ها درست بودند اکشن نهایی داخل onclick اجرا میشود. این اتفاقات پس از کلیک شدن المان رخ می دهد.

     ↵  OnClick :

              در صورت کلیک شدن المان صدا میشود و مقدار آن یک اکشن می باشد.

     ↵  Align :

              موقعیت مکانی شروع المان در صفحه را مشخص میکند

     ↵  Tint :

              رنگ عکس را تغییر میدهد.

     ↵  scaletype :

              نحوه نمایش تصویر را مشخص میکند و مقادیر center برای نمایش در مرکز  center_crop برای نمایش در مرکز با بریدن اضافاتcenter_inside برای نمایش در مرکز و داخل،  fit_center برای کوچک کردن عکس به صورتی که با طول و عرض داده شده و مرکز محور مطابق شود ، fit_end برای نمایش در انتها  fit_start برای نمایش در شروع و  fit_xy برای پیروی از طول و عرض مادر و focus_crop برای برش از قسمت متمرکز را میگیرد.

     ↵  aspectRatio :

              انداره و مدل عکس را مشخص میکند. مقادیر center و center_crop و center_inside و fit_center و fit_end و fit_start و fit_xy و focus_crop را میگیرد.

پشتیبانی از تصاویر Base64

نسخه مورد نیاز: قابلیت‌های جدید این بخش شامل بارگذاری امن و غیرهمزمان Base64، رویدادهای onload/onerror و محدودیت‌های قابل تنظیم، از appsansdk-core 0.1.78 به بعد در دسترس هستند. فرمت‌های base64:// و data: در نسخه‌های قبلی نیز پشتیبانی می‌شدند.

خاصیت src علاوه بر لینک‌های معمولی و مسیر فایل‌های محلی، دو فرمت قبلی Base64 را نیز بدون نیاز به تغییر در کد مینی‌اپ پشتیبانی می‌کند:

• base64://BASE64_DATA
• data:image/png;base64,BASE64_DATA (یا MIME type معتبر تصویر)

<img id="photo" width="match_parent" height="300" />

Appsan.setProperty('photo', 'src', 'base64://' + imageData);
// یا
Appsan.findElementById('photo').setProperty('src', dataUrl);

سازگاری با نسخه‌های قبل: امضای API و فرمت‌های base64:// و data: تغییری نکرده‌اند و کدهای فعلی بدون مهاجرت کار می‌کنند.

نحوه بارگذاری و مدیریت حافظه

بارگذاری Base64 به‌صورت غیرهمزمان انجام می‌شود تا Thread اصلی برنامه مسدود نشود. داده به‌صورت stream در فایل موقت decode می‌شود، ابعاد تصویر قبل از ساخت Bitmap بررسی می‌شود و تصویر متناسب با اندازه View و بودجه حافظه downsample می‌شود. هنگام تغییر مجدد src، درخواست قبلی لغو خواهد شد.

در زمان بارگذاری placeholder نمایش داده می‌شود. اگر داده نامعتبر یا بزرگ‌تر از محدودیت‌های مجاز باشد، آیکن خطا نمایش داده شده، خطا در لاگ Appsan ثبت می‌شود و در صورت تعریف شدن onerror اکشن مربوطه اجرا می‌شود. این رفتار جایگزین freeze یا crash شدن برنامه است.

OnLoad

اختیاری است و پس از بارگذاری موفق تصویر اجرا می‌شود. مقدار $data شامل width و height تصویر اصلی است. برای منابع غیر Base64 ممکن است این دو مقدار صفر باشند.

OnError

اختیاری است و در صورت شکست بارگذاری اجرا می‌شود. مقدار $data شامل فیلدهای code و message است.

<img
    id="photo"
    width="match_parent"
    height="300"
    onload="script/script:imageLoaded($data)"
    onerror="script/script:imageFailed($data)"
/>

<script id="script">
function imageLoaded(data) {
    console.log('Image loaded:', data.width, data.height);
}

function imageFailed(error) {
    console.error('Image error:', error.code, error.message);
}
</script>

کدهای خطای Base64

• INVALID_DATA_URL: ساختار Data URL معتبر نیست یا فرمت Base64 ندارد.
• INVALID_BASE64: داده Base64 نامعتبر یا خالی است.
• IMAGE_SOURCE_TOO_LARGE: اندازه متن Base64 یا داده decodeشده از حد مجاز بیشتر است.
• IMAGE_DIMENSIONS_TOO_LARGE: ابعاد تصویر یا حافظه Bitmap از حد مجاز بیشتر است.
• IMAGE_DECODE_FAILED: داده، تصویر پشتیبانی‌شده‌ای نیست یا خواندن آن شکست خورده است.
• IMAGE_OUT_OF_MEMORY: با وجود کنترل‌های اولیه، حافظه کافی برای decode موجود نبوده است.

محدودیت‌های پیش‌فرض

اگر تصویر از این محدودیت‌ها عبور کند، بارگذاری کنترل‌شده شکست می‌خورد و onerror فراخوانی می‌شود. کوچک بودن ظاهری المان به‌تنهایی به معنی کم بودن حافظه Bitmap نیست؛ SDK تصویر را هنگام decode متناسب با اندازه المان نمونه‌برداری می‌کند.

تنظیم محدودیت‌ها در برنامه میزبان

این تنظیم اختیاری و فقط برای توسعه‌دهنده برنامه میزبان است. مینی‌اپ‌ها نیازی به تغییر ندارند.

Appsan.getInstance().setImageSourceLimits(
    new ImageSourceLimits.Builder()
        .setMaximumEncodedBytes(24L * 1024L * 1024L)
        .setMaximumDecodedDataBytes(18L * 1024L * 1024L)
        .setMaximumDecodedBitmapBytes(32L * 1024L * 1024L)
        .setMaximumDimension(16_384)
        .build()
);

InputTextDialog

یک دایالوگ است که به صورت پیش فرض InputText داخل خود دارد.

ProgressBar

Progress Bar برای نشان دادن پیشرفت یک کار استفاده می شود

خواص این المان : 

• Color :

رنگ المان را مشخص میکند.

• Layout :

نوع چیدمان صفحه را مشخص میکند و دو مقدار circular و linear را میپذیرد.

RadioButton

از radio button ها زمانی استفاده می شود که بخواهیم تنها اجازه انتخاب یک گزینه را به کاربر بدهیم. فرض کنید برای تعیین جنسیت کاربر طبیعتا یکی از دو مورد مرد یا زن باید انتخاب شود برای همین از radio button استفاده می شود.برای اینکه چندین radio button داشته باشید باید انها را داخل یک radio group تعریف کنید:

خواص این المان: 

• Reverse :

چیدمان را مشخص میکند.

• HighlightColor :

رنگ را مشخص میکند.

• Checked :

این مشخصه نشان میدهد این گزینه انتخاب شده است یا خیر.

• Disabled :

قابل تغییر بودن المان را مشخص میکند اگر true باشد غیر قابل تغییر و اگر false باشد قابل تغییر است.

• GroupValue :

در صورتی که از radio button داخل radio group استفاده شود این مقدار را داخل radio group نشان میدهد

RadioGroup

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

ButtonGroup

ButtonGroup برای یک مجموعه از Button ها مورد استفاده قرار می گیرد. به زبان ساده به گروهی از Button ها ButtonGroup می گویند. در این صورتی فقط یکی از Button ها قابل انتخاب خواهد بود.

  : choicemode

           را میتواند بگیرد multiple  و  single مقادیر

Action

اکشن یک المان است که یک id و یک action میگیرد و action را فراخوانی میکند.

• برای زمانی که بخواهیم چند action فراخوانی کنیم با جدا کردن آنها توسط " ; " این کار را انجام دهیم .

onclick="script/myScript:changeColor();script/myScript:changeFont()"

.است script ، action و myscript ، id همانطور که در کد بالا مشخص است 

• برای زمانی که بخواهیم چند action پشت سرهم اجرا شوند از "<-" استفاده میشود.

onclick="script/s1:run()->page/page1"

. اجرا میشوند  page و script در کد بالا نیز دو اکشن متفاوت به ترتیب 

InlineUpdate

نوعی update است که میتواند به صورت offline صدا زده شود.توجه داشته باشید که توضیح update در بخش های دیگر آمده است.

material-textinput

material-textinput

 دارای اتریبیوت های زیر میباشد

: hint↵  

.  متن پیشنهادی را نشان میدهد      

: error↵  

    .ارور را نشان میدهد      

: strokecolor↵  

 .را مشخص میکند.strokeرنگ     

. است focusedstrokecolor از دیگر اتریبیوت های مشابه      

: strokewidth↵  

.را مشخص میکند stroke  قطر      

. است strokewidthfocused از دیگر اتریبیوت های مشابه      

: suffix و prefix↵  

.مربوط به قابلیت پیشبینی موارد میباشد      

: enabled↵  

.فعال بودن یا نبودن این المان را مشخص میکند      

: maxChar↵  

   .ماکسیمم تعداد کارکترورودی را تعیین میکند     

: showError↵  

    .ارور گرفته شده را نشان میدهد      

: expandHint ↵  

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

: helpertext↵  

    .متنهایی را نیز میتوان برای کمک از پیش اماده کرد و به کاربر پیشنهاد داد     

: appearance↵  

 .میباشد fill, none دارای مقادیر    

 : textalignment↵  

.نحوه قرار گیری متن را مشخص میکند    

: مقادیر زیر را میگیرد       

'textend' و 'textstart' و 'viewend' و 'viewstart' و 'gravity'  

:starticon و endicon↵ 

(endiconmode= costum ) زمانی که میخواهیم متن زیر المانهای دیگر قرار نگیرند

:اتریبیوتهایی مربوط به آن شامل

endiconclick↵ 

endiconscaletype↵ 

endicontint↵ 

endiconmode↵ 

showendicon↵ 

erroricon↵ 

erroriconscaletype↵ 

starticontint↵ 

starticonscaletype↵ 

showstarticon↵  

starticonclick↵  

: دارد counter همچنین اتریبیوتهای برای 

showCounter↵ 

counterMax↵  

:نمونه کد آن به صورت زیر است

<frame width="328" height="56"  borderCornerRadius="5"  >
	<material-textinput width="328" height="56" expandHint="true" background="white" >
		<textinput hint="which" ></textinput>
			<autocompletetextinput id="in" threshold="2">
				<suggestion text="one" value="one"  />
				<suggestion text="two" value="two"/>
				<suggestion  text="three" value="three"/>
		</autocompletetextinput>
	</material-textinput>
</frame>

: نمونه کد رمز عددی راست چین 

<material-textinput margin_left="10" margin_right="10" hint="پسورد" rtl="true"
        endiconmode="password_toggle" showendicon="true"
    >
        <textinput id="newContactName" textdirection="rtl" inputtype="number_password"
            textalignment="view_start"/>
    </material-textinput>

date picker

: date picker نمونه کد یک

<page onshown="dialog/datePickerDialog">
    <reactive-data id="defaltValue" valueBind="component/defaultValue" elementBind="year:text"/>
    <button onclick="dialog/datePickerDialog" text="Ss"/>
</page>

<bottomsheetdialog id="datePickerDialog" onshown="script/datePickerScript:initCalendar()">
    <text margin_bottom="16">تاریخ مستند مورد نظر را انتخاب کنید</text>

    <frame layout="frame">
        <imagebutton onclick="script/datePickerScript:nextMonth()" height="42" src="images/previous.png" gravity="left"/>
        <frame layout="linear_horizontal">
            <text id="year">1401</text>
            <text id="month">تیر</text>
        </frame>
        <imagebutton onclick="script/datePickerScript:lastMonth()" height="42" src="images/next.png" gravity="right"/>
    </frame>

    <frame id="calendar" layout="linear_vertical">

    </frame>

    <frame layout="linear_horizontal" margin_top="10" borderCornerRadius="5" background="">
        <button background="#55BECC" textsize="14" textcolor="white">انتخاب</button>
    </frame>


    <include layout="comp/date-picker.js.appsan"/>
</bottomsheetdialog>

<script id="datePickerScript">

    class PersianDate extends Date {
        constructor(...args) {
            super(...args);
        }

        toLocaleDateString = () => super.toLocaleDateString('fa-IR-u-nu-latn');
        getParts = () => this.toLocaleDateString().split("/")
        getDay = () => super.getDay() === 6 ? 0 : super.getDay() + 1
        getDate = () => this.getParts()[2];
        getMonth = () => this.getParts()[1];
        getYear = () => this.getParts()[0];
        getMonthName = () => this.toLocaleDateString("fa-IR", {month: 'long'});
        getDayName = () => this.toLocaleDateString("fa-IR", {weekday: 'long'});
    }

    const jCal = {
        monthsDays: [
            31, 31, 31,
            31, 31, 31,
            30, 30, 30,
            30, 30, 29
        ],
        monthNames: [
            'فروردین',
            'اردیبهشت',
            'خرداد',
            'تیر',
            'مرداد',
            'شهریور',
            'مهر',
            'آبان',
            'آذر',
            'دی',
            'بهمن',
            'اسفند',
        ],
        getMonthDays: (month) => {
            return jCal.monthsDays[month - 1];
        },
        gregorian_to_jalali: (gy, gm, gd) => {
            var g_d_m = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334];
            var jy = (gy <= 1600) ? 0 : 979;
            gy -= (gy <= 1600) ? 621 : 1600;
            var gy2 = (gm > 2) ? (gy + 1) : gy;
            var days = (365 * gy) + (parseInt((gy2 + 3) / 4)) - (parseInt((gy2 + 99) / 100))
                + (parseInt((gy2 + 399) / 400)) - 80 + gd + g_d_m[gm - 1];
            jy += 33 * (parseInt(days / 12053));
            days %= 12053;
            jy += 4 * (parseInt(days / 1461));
            days %= 1461;
            jy += parseInt((days - 1) / 365);
            if (days > 365) days = (days - 1) % 365;
            var jm = (days < 186) ? 1 + parseInt(days / 31) : 7 + parseInt((days - 186) / 30);
            var jd = 1 + ((days < 186) ? (days % 31) : ((days - 186) % 30));
            return [jy, jm, jd];
        },
        jalali_to_gregorian: (jy, jm, jd) => {
            var gy = (jy <= 979) ? 621 : 1600;
            jy -= (jy <= 979) ? 0 : 979;
            var days = (365 * jy) + ((parseInt(jy / 33)) * 8) + (parseInt(((jy % 33) + 3) / 4))
                + 78 + jd + ((jm < 7) ? (jm - 1) * 31 : ((jm - 7) * 30) + 186);
            gy += 400 * (parseInt(days / 146097));
            days %= 146097;
            if (days > 36524) {
                gy += 100 * (parseInt(--days / 36524));
                days %= 36524;
                if (days >= 365) days++;
            }
            gy += 4 * (parseInt((days) / 1461));
            days %= 1461;
            gy += parseInt((days - 1) / 365);
            if (days > 365) days = (days - 1) % 365;
            var gd = days + 1;
            var sal_a = [0, 31, ((gy % 4 == 0 && gy % 100 != 0) || (gy % 400 == 0)) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
            var gm
            for (gm = 0; gm < 13; gm++) {
                var v = sal_a[gm];
                if (gd <= v) break;
                gd -= v;
            }
            return [gy, gm, gd];
        },
        getMonthName: (month) => {
            return jCal.monthNames[month - 1];
        }
    }

    let pDate = new PersianDate();

    function nextMonth() {
        let month = +pDate.getMonth() + 1;
        if (month === 13) month = 1;
        const firstOfMonth = jCal.jalali_to_gregorian(pDate.getYear(), month, 1);
        pDate = new PersianDate(firstOfMonth);
        initCalendar();
    }

    function lastMonth() {
        let month = pDate.getMonth() - 1;
        if (month === 0) month = 12;
        const firstOfMonth = jCal.jalali_to_gregorian(pDate.getYear(), month, 1);
        pDate = new PersianDate(firstOfMonth);
        initCalendar();
    }

    function initCalendar() {
        let rows = '<frame layout="linear_vertical">';

        const firstOfMonth = jCal.jalali_to_gregorian(pDate.getYear(), pDate.getMonth(), 1);
        let monthOffset = new Date(firstOfMonth[0], firstOfMonth[1] - 1, firstOfMonth[2]).getDay() + 2;
        if(monthOffset > 6) monthOffset = monthOffset - 7;

        // rows += `<text>${new Date(firstOfMonth[0], firstOfMonth[1], firstOfMonth[2])}</text>`
        // rows += `<text>${new Date(firstOfMonth[0], firstOfMonth[1] - 1, firstOfMonth[2]).getDay()}</text>`
        // rows += `<text>${firstOfMonth}</text>`
        // rows += `<text>${monthOffset}</text>`
        // rows += `<text>${(1 - monthOffset)}</text>`

        rows += `<frame layout="linear_horizontal" reverse="true">
                <text>ش</text>
                <text>ی</text>
                <text>د</text>
                <text>س</text>
                <text>چ</text>
                <text>پ</text>
                <text>ج</text>
                </frame>\n`

        for (let i = (1 - monthOffset); i <= (41 - monthOffset); i++) {
            if ((i - 2 + monthOffset) % 7 === 0) {
                if (i > 1) rows += '<' + `/frame>\n`
                rows += `<frame layout="linear_horizontal" reverse="true">\n`
            }
            rows += `<text>${(i > 0 && i <= jCal.getMonthDays(pDate.getMonth())) ? i : ''}</text>\n`;
        }
        rows += `</frame>`
        rows += `</frame>`

        Appsan.setProperty("calendar", "innerElements", rows)
        Appsan.setProperty("year", "text", pDate.getYear())
        Appsan.setProperty("month", "text", jCal.getMonthName(pDate.getMonth()))
    }
</script>

BottomSheet

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

   ↵  peekHeight:

                بیشترین ارتفاعی که میگیرد را مشخص میکند.

   ↵  animatePeekHeight:

               به کمک آن امکان با انیمیشن آمدن المان فعال میشود.

   ↵  draggable:

                قابلیت drag کردن را تعیین میکند.

   ↵  hidable:

                قابلیت hide شدن پیدا میکند.

   ↵  state:

                مقادیر collapsed, hidden, expanded, halfexpanded را میگیرد.

   ↵  fitToContents:

                اندازه اش به اندازه ی محتوای درون المان وابسته میشود.

   ↵  expandedoffset:

                فاصله از بالای المان زمان expand بودن را مشخص میکند.

   ↵  halfExpandedRatio:

                نقطه ای که در آن به صورت نصفه باز شده باشد.

   ↵  maxwidth:

               حداکثر عرضی که المان میگیرد را نشان میدهد.

   ↵  maxheight:

                حداکثر طولی که المان میگیرد را نشان میدهد.

   ↵  skipcollapsed:

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

: windowsoftinputmode ↵  

نحوه نمایش المان های دیالوگ و خود دیالوگ زمانی که کیبرد باز میشود را مشخص میکند               

variable

: دارای سطح ویژگی های زیر میباشد variable  

: value↵  

.مقدار المان را در خود نگه میدارد

: bind↵  

.مورداستفاده قرار میگیرد data binding برای 

: access↵  

 .است که کاربردشان مانند زبان های دیگر میباشد protected و public و private سطح دسترسی متغیرها نیز قابلیت تغییر دارند و شامل مقادیر

: type↵  

. نوع متغیرها را مشخص میکند

.میباشد number و int و long و boolean و object و array و string دارای مقادیر

deepLinkReceiver

<page>
    <text text="DeepLink test, this page is opened as default page when path is not a match."/>
    <button text="btn" onclick=""/>
</page>

<page id="paymentPage">
    <text text="This is payment page"/>
    <text id="txt1" text="click the button to get data"/>
    <button text="get data" onclick="script/s1:getData()"/>

<script id="s1">
    function getData() {
        const path = Appsan.getBind("deeplink/path");
        Appsan.setProperty("txt1", "text", path);
    }
</script>
</page>

<deepLinkReceiver>
    <deeplink path="payment" page="paymentPage"></deeplink>
    <deeplink path="page2" page="page2"></deeplink>
</deepLinkReceiver>

OSM Map

این المان فرزند، نقشه ای را نمایش می دهد که میتوان به طور دلخواه لوکیشنی بر آن تنظیم کرد.

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

خواص این المان :

     ↵  Latitude :

                عرض جغرافیایی مرکز نمایش نقشه

     ↵  Longitude :

                طول جغرافیایی مرکز نمایش نقشه

     ↵  DisableScroll :

                غیر فعال بودن خاصیت scroll نقشه را مشخص میکند.

     ↵  DisableZoom :

                غیر فعال بودن خاصیت zoom نقشه را مشخص میکند.

     ↵  DisableTilt :

                قابلیت زاویه دادن به نقشه را حذف میکند.

     ↵  Title :

                عنوان نقشه را مشخص میکند.

     ↵  Icon :

                icon نقشه را مشخص میکند.

     ↵  OnClick :

                این ویژگی مشخص میکند زمانی که روی نقشه کلیک شد چه اتفاقی رخ دهد و یک اکشن میپذیرد.

     ↵  OnReady :

                زمانی که نقشه به طور کامل load شود اجرا میشود.

     ↵  Zoom :

              بزرگنمایی نقشه در هنگام شروع

     ↵  showUserDot :

                مقداری true یا false که به ترتیب نمایش یا عدم نمایش نقطه آبی مکان فعلی کاربر را مشخص میکند.

     ↵  onChange :

                در زمان تغییر مکان نقشه توسط کاربر صدا میشود و مقدار آن نیز یک اکشن است.

     ↵  animateMovements :

              تغییرات مکان مرکز نقشه را با انیمیشن انجام می دهد.

در ادامه یک نمونه از کد map را مشاهده می کنید که لوکیشن آن بر دانشگاه شهید بهشتی تنظیم شده است:

<page title="نمایش نتایج روی نقشه" scrollable="false" toolbarColor="#E64724">
     <osmmap id="map" width="match_parent" height="match_parent" latitude="37.181680" longitude="50.028010" showUserDot="true" >
        <marker latitude="37.181680" longitude="50.028010"
            title="title" onClick="command/details">
        </marker>
    </osmmap>
</page>

webpage

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

عنصر webpage به توسعه‌دهندگان این امکان را می‌دهد که صفحات وب را به صورت مستقیم در پروژه‌های Appsan خود اضافه کنند. این عنصر شامل دو ویژگی کلیدی به نام‌های src و title است.

ویژگی‌ها

پوشه‌های web و webdist

مثال

<webpage src="https://example.com" title="نمونه وب"/>
<webpage src="myWebProject" title="پروژه داخلی"/>

در مثال اول، یک صفحه وب خارجی با لینک مستقیم بارگذاری می‌شود. در مثال دوم، یک پروژه وب داخلی که فایل‌های ساخته شده آن در پوشه webdist/myWebProject قرار دارد، بارگذاری خواهد شد.

نکات مهم

این مستندات برای راهنمایی توسعه‌دهندگان در اضافه کردن و مدیریت صفحات وب در پروژه‌های Appsan طراحی شده است.

اکشن ها

انواع اکشن ها

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

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

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

ترکیب و کنترل جریان اکشن‌ها

یک عبارت اکشن می‌تواند از چند اکشن و چهار ساختار زیر تشکیل شود:

اولویت عملگرها

اولویت از بیشترین به کمترین به این ترتیب است: ()، سپس ^، سپس -> و در آخر ;. بنابراین عبارت ac1;ac2->ac3 به معنی اجرای موازی ac1 با زنجیره ac2->ac3 است. برای اینکه ac3 منتظر پایان هر دو اکشن بماند باید بنویسید (ac1;ac2)->ac3.

اجرای ترتیبی و انتقال نتیجه

در ac1->ac2، اکشن ac2 تا پایان ac1 اجرا نمی‌شود. اگر ac1 نتیجه‌ای تولید کند، آن نتیجه از طریق $data در اختیار ac2 قرار می‌گیرد.

<button text="Select image"
        onClick="imagepicker/gallery->script/image:showResult($data)" />

اجرای موازی و نتیجه گروه

در ac1;ac2 هر شاخه ورودی اولیه یکسانی دریافت می‌کند، ولی نتیجه یک شاخه برای شاخه دیگر قابل مشاهده نیست. در (ac1;ac2)->ac3، اکشن ac3 پس از پایان موفق هر دو شاخه اجرا می‌شود و یک آرایه مرتب از نتایج را در $data دریافت می‌کند. ترتیب آرایه مطابق ترتیب نوشتن شاخه‌ها است و برای اکشنی که نتیجه ندارد مقدار null قرار می‌گیرد.

مدیریت خطا با ^

در ac1^ha1->ac2^ha2، اگر ac1 شکست بخورد، ha1 اجرا می‌شود و ac2 اجرا نخواهد شد. اگر ac1 موفق باشد، ha1 رد می‌شود و اجرای زنجیره به ac2 می‌رسد؛ در صورت شکست ac2 نیز ha2 اجرا می‌شود.

اجرای موفق handler خطای اکشن اصلی را به موفقیت تبدیل نمی‌کند و اکشن‌های بعدی زنجیره اجرا نمی‌شوند. برای یک handler چندمرحله‌ای از پرانتز استفاده کنید:

ac1^(ha1->ha2)->ac3

اگر ac1 شکست بخورد، زنجیره ha1->ha2 اجرا می‌شود، اما ac3 اجرا نخواهد شد. در (ac1;ac2)^handler ابتدا پایان همه شاخه‌های موازی بررسی می‌شود و سپس در صورت وجود خطا، handler فقط یک بار اجرا می‌شود.

handler اطلاعات خطا را به صورت یک object در $data دریافت می‌کند:

{
  "expression": "ac1",
  "errors": [
    {
      "branchPath": [0],
      "action": "ac1",
      "type": "ExceptionType",
      "message": "Error message",
      "input": null
    }
  ]
}

پرانتز و حالت‌های تو در تو

• ac1->(ac2;ac3): پس از موفقیت ac1، دو اکشن بعدی به صورت موازی اجرا می‌شوند.
• (ac1;ac2)->ac3: ac3 منتظر پایان موفق هر دو شاخه می‌ماند.
• (ac1;ac2)^handler: خطای کل گروه پس از پایان همه شاخه‌ها به handler ارسال می‌شود.
• برای handler تو در تو باید پرانتز صریح به کار رود؛ نوشتن ac1^ha1^ha2 معتبر نیست.

استفاده از کاراکترهای عملگر در ورودی اکشن

اگر یکی از کاراکترهای رزروشده جزئی از ورودی اکشن است، آن را با \ escape کنید:

پرانتزهای داخل ورودی یک اکشن، مانند script/x:fn($data)، به صورت خودکار جزئی از همان اکشن محسوب می‌شوند. فقط اگر خود اکشن باید با پرانتز باز شروع شود از \( استفاده کنید. توالی‌های ناشناخته مانند \d بدون تغییر باقی می‌مانند.

عبارت‌هایی با پرانتز ناقص، عملگر بدون اکشن، گروه خالی یا handler زنجیره‌ای بدون پرانتز معتبر نیستند. در API قدیمی خطا ثبت می‌شود و هیچ بخش ناقصی از عبارت اجرا نخواهد شد.

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 کابر را نمایش می دهد. این آیدی منحصر به فرد است و شما می توانید از آن به عنوان اعتبار سنجی کاربر استفاده کنید.

بخش توسعه دهنده

ادیتور

ورود به ادیتور

• گام اول :

در ابتدا در پنل اپسان به آدرس https://dev.appsan.ir ( با شماره تلفن همراهِ یکسان با اکانت در اپلیکیشن ) اکانت ساخته و لاگین می کنیم.

• گام دوم :

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

• گام سوم :

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

محیط ادیتور

• در بخش قرمز ما میتوانیم کد xml را وارد و یا مشاهده کنیم.
• در بخش زرد با استفاده از Properties میتوانیم xml خود را آماده کنیم.
• همینطور با استفاده از بخش سبز میتوانیم آپدیت های xml را مشاهده کنیم.

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

همچنین با استفاده از گزینه Templates می توان به المان هایی نظیرMusicPlayer , VideoPlayer, Map, Marker و search دسترسی پیدا کرد وهمینطور نمونه کد های آن ها را مشاهده کرد.

اجرای کد

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

و همچنین برای اجرای کد روی تلفن همراه خود وارد اکانت خود در اپلیکیشن اپسان می شویم و با اجرا کردن کد در ادیتور، xml آن را روی گوشی خود مشاهده میکنیم.

(نحوه اجرای کد در ادیتور)

دیباگ

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

سپس با فشردن دکمه ی اجرای کد مطابق با شکل زیر ، کد شما در اپلیکیشن اندروید اپسان اجرا می شود:

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

این قسمت از 3 بخش هشدارها ، طراحی و مقادیر تشکیل شده است:

• هشدار ها: در صورت وجود هشدار در کد شما ، در این بخش نمایش داده می شود.

• طراحی: کد xml وارد شده در ایتور ، در این قسمت نیز نمایش داده می شود.

• مقادیر: در صورت وجو المان هایی که مقادیری را دریافت می کنند ، در این بخش نمایش داده می شود.

طراحی پروتوتایپ

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

برای شروع کار باید صفحه گوشی را انتخاب نمایید. می توانید صفحه ای با ابعاد iphone 6 plus را انتخاب کنید. (انتخاب مدل گوشی خیلی اهمیتی ندارد و می توانید موارد دیگری را به دلخواه انتخاب نمایید)

به کمک ctrl و اسکرول موس یا علامت ذره بین می توانید zoom in / out کنید.

در ادامه به منوی toolbar این نرم افزار و قابلیت های مختلف آن می پردازیم:

1.  برای select یا به طور کلی کلیک عادی روی صفحه
2. ترسیم اشکال مختلف که همان دکمه ها ، فریم ها ، خطوط و غیره در xml هستند
3. کشیدن اشکال دلخواه مثل خطوط curve
4. اضافه کردن متن بوسیله ی Text box
5. به کمک ctrl و اسکرول ماوس یا این دکمه می توانید در صفحه zoom in / out کنید

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

همچنین چندین فریم یا نوشته را می توان با هم select کرده و از Repeat Grid برای همگی استفاده کرد.

تصاویر، icon ها و لوگوهای مدنظر خود را می توان با drag & drop در صفحه قرار بدهید و اندازه ی آن ها را نیز تنظیم کنید.

می توانید از کیت لوگوهای آماده متریال هم استفاده کنید. مطابق با تصویر با انتخاب گزینه ی  More UI صفحه دانلود باز شده و می توانید بسته ی UI مورد نظر خود را دانلود کیند ، سپس آن را unzip کرده و فایل xd را باز کنید.

برای جابه جایی صفحات طراحی شده یا کپی کردن آن ها، باید کلید ctrl را گرفته و روی بک گراند کلیک کنید.
در صورت نیاز صفحه را جا به جا کنید (ctrl را رها نکنید) یا اینکه copy و paste کنید.

استفاده از جاوا اسکریپت در اپسان

متد ها

console

متد ها:

Appsan

متد ها:

HTTPClient

FormData

File Apis

اضافه شده در ورژن appsan-js:0.1.51

اظلاعات بیشتر در Web File Api

کلاس ها:

Blob

File

FileList

WebSocket Apis

این متد ها از ورژن jsscript:0.1.72 در دسترس است.

WebSocket

برای اطلاعات بیشتر مستندات websocket وب را مطالعه نمایید.

تحلیل سفر مینی‌اپ

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

معرفی تحلیل سفر مینی‌اپ

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

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

چه اطلاعاتی ثبت می‌شود؟

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

نسخه‌های موردنیاز

برای مینی‌اپ کاملاً بومی، دو مورد اول لازم است. برای مینی‌اپ وب داخل Android WebView، هر چهار مورد باید با نسخه‌های بالا یا نسخه سازگار جدیدتر استفاده شوند.

روش‌های ثبت سفر

حالت خودکار

شروع سفر، نمایش صفحات بومی و تغییر مسیرهای معمول وب بدون ثبت دستی توسعه‌دهنده شناسایی می‌شود. این حالت، انتخاب پیش‌فرض است.

حالت دستی

برای مراحل معنایی که از چرخه صفحه یا URL قابل تشخیص نیست، توسعه‌دهنده رویداد را صریحاً ثبت می‌کند؛ مانند نمایش پنجره تأیید، انتخاب روش پرداخت یا پایان موفق یک فرایند چندمرحله‌ای.

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

مینی‌اپ بومی: حالت خودکار و تنظیم سفر در پنل

در مینی‌اپ بومی، افزونه Analytics چرخه اجرای مینی‌اپ و نمایش عناصر page و dialog را به‌صورت خودکار به رویدادهای سفر تبدیل می‌کند.

چه چیزهایی خودکار ثبت می‌شوند؟

نکته: شناسه عناصر باید پایدار، کوتاه و غیرحساس باشد؛ مانند checkout، payment-confirmation یا error-network. متن قابل‌نمایش، شماره سفارش و اطلاعات کاربر را به‌عنوان ID استفاده نکنید.

تنظیم سفر در پنل اپسان

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

۱. ورود به زبانه سفرها

۲. باز کردن تنظیمات سفر

۳. ایجاد تعریف جدید و افزودن مراحل

قوانین خطا

مشاهده یک صفحه یا دیالوگ می‌تواند سفر را خودکار خطادار کند. در حالت تطبیق دقیق، ID باید کاملاً برابر باشد. در حالت Regex، الگو روی کل ID اجرا می‌شود؛ برای نمونه error-(network|timeout).

Regex فقط روی شناسه فنی اجرا می‌شود، نه متن دیالوگ یا محتوای لاگ. موتور مشترک سرور و Android از قواعد RE2 استفاده می‌کند و Lookaround یا Backreference را پشتیبانی نمی‌کند.

مشاهده نتیجه

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

مینی‌اپ بومی: ثبت دستی مراحل و نتیجه سفر

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

چه زمانی ثبت دستی لازم است؟

اکشن‌های سفر

ثبت نتیجه همراه تغییر صفحه

اکشن‌ها مانند سایر اکشن‌های Appsan با -> زنجیره می‌شوند. در مثال زیر ابتدا صفحه موفقیت باز و سپس سفر تکمیل می‌شود.

<button
    id="pay-button"
    text="پرداخت"
    onclick="page/success->analytics/journey/complete" />

ثبت مرحله سفارشی

<button
    id="confirm-button"
    text="تأیید"
    onclick="analytics/journey/step/custom/payment-authorized" />

ثبت خطا با دلیل

<button
    id="retry-button"
    text="تلاش دوباره"
    onclick="analytics/journey/fail/payment_declined" />

افزودن داده به سفر

<button
    id="wallet-button"
    text="کیف پول"
    onclick="analytics/journey/data/payment.method/wallet" />

قواعد شناسه و داده

نکته امنیتی: نام کاربر، شماره تماس، توکن، شماره سفارش و متن آزاد را در شناسه، دلیل خطا یا داده سفر قرار ندهید. برای موارد متغیر از کدهای عمومی و پایدار استفاده کنید.

ارتباط با تعریف پنل

نوع و شناسه‌ای که در اکشن step می‌فرستید باید با مرحله تعریف‌شده در پنل یکسان باشد. برای نمونه، اکشن analytics/journey/step/custom/payment-authorized در پنل به‌صورت نوع custom و شناسه payment-authorized تعریف می‌شود.

مینی‌اپ وب: تحلیل خودکار و ثبت دستی سفر

در مینی‌اپ وب، SDK مسیرهای داخل صفحه را شناسایی و از طریق سوپراپ به Analytics بومی Appsan ارسال می‌کند. همین کد در نسخه PWA نیز قابل استفاده خواهد بود.

نصب و فعال‌سازی

نسخه 0.1.0 یا جدیدتر بسته زیر را به پروژه وب اضافه کنید:

npm install @appsan-web/mini-web-sdk@^0.1.0

در پروژه Android میزبان نیز Appsan Core 0.1.78، Appsan Analytics 0.1.0 و Appsan Web Extension 0.0.8 یا نسخه سازگار جدیدتر لازم است.

import { AppsanWeb } from '@appsan-web/mini-web-sdk';

AppsanWeb.analytics.configure({
  autoTrackRoutes: true
});

حالت خودکار

گزینه autoTrackRoutes به‌صورت پیش‌فرض فعال است. SDK مسیر اولیه و تغییرات بعدی را از منابع زیر تشخیص می‌دهد:

مسیرهای تکراریِ پشت‌سرهم دوباره ثبت نمی‌شوند. در حالت پیش‌فرض Query String و Fragment معمولی از شناسه مرحله حذف می‌شوند؛ اما مسیر Hash Router مانند #/checkout نگهداری می‌شود.

مسیرهای پویا و حساس

اگر URL شامل شناسه سفارش، شناسه کاربر یا مقدار متغیر است، همیشه routeIdResolver تعریف کنید تا پیش از ثبت، مسیر عمومی و پایدار شود.

AppsanWeb.analytics.configure({
  autoTrackRoutes: true,
  routeIdResolver: url =>
    url.pathname.replace(//orders/[^/]+/, '/orders/:id')
});

برای نادیده گرفتن یک مسیر، از Resolver مقدار null برگردانید.

چه زمانی حالت دستی لازم است؟

متدهای دستی

مثال کامل

import { AppsanWeb } from '@appsan-web/mini-web-sdk';

AppsanWeb.analytics.step('dialog', 'payment.confirmation');
AppsanWeb.analytics.setData('payment.method', 'wallet');

AppsanWeb.analytics.complete().subscribe({
  next: () => console.log('Journey completed'),
  error: error => console.error(error)
});

تمام متدهای سفر یک Subject از RxJS برمی‌گردانند و در صورت نیاز می‌توان نتیجه ارسال را با subscribe دریافت کرد.

خطا و لاگ

خطاهای Runtime و Promiseهای بدون Handler به‌صورت خودکار گزارش می‌شوند. SDK عمداً console، fetch و XMLHttpRequest را شنود نمی‌کند. برای ثبت پیام تشخیصی از AppsanWeb.analytics.log، warn یا error استفاده کنید. این پیام‌ها فقط در صورت وجود قانون فعال و منطبق در تعریف سفر پنل جمع‌آوری می‌شوند.

مسیر انتقال اطلاعات

نمایش نتیجه در پنل

سفرهای ثبت‌شده از زبانه «سفرها» در پنل اپسان در دسترس هستند. برای مشاهده جزئیات هر سفر، آیکون مشاهده همان ردیف را انتخاب کنید.

تنظیم مراحل وب در پنل

برای مسیرهای خودکار، نوع مرحله را page و شناسه را دقیقاً برابر خروجی Resolver وارد کنید؛ مانند /checkout یا /orders/:id. برای مراحل دستی نیز نوع و شناسه باید با آرگومان‌های متد step یکسان باشد؛ برای نمونه dialog / payment.confirmation.

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